Configuration Deployment¶
Overview¶
Use the Configuration Deployment API to create a task that deploys the configuration of a specific module object on multiple BIG-IPs to match the object in the BIG-IQ’s working-config. Separate tasks are required to update the configurations of different modules (i.e. access, adc-core, asm, dns, firewall, security-shared or websafe) but a single deployment task can update the configuration of the specified module on multiple BIG-IPs. Use the Configuration Snapshot API to create a snapshot of the working configuration on the BIG-IQ. A snapshot can record the state of the working-config objects for a specified module even when those objects are subsequently modified or deleted. Use the Configuration Restore API to revert working-config changes on the BIG-IQ to a previous snapshot state. To revert configuration changes on BIG-IP, you must deploy the restored configuration on the BIG-IQ to the BIG-IP using Configuration Deployment API.
REST Endpoint: mgmt/cm/<module>/tasks/deploy-configuration¶
Requests¶
To start the deployment task, send a POST request to the <module>/tasks/deploy-configuration endpoint. The placeholder text <module> represents the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
POST mgmt/cm/<module>/tasks/deploy-configuration¶
Request Parameters¶
The JSON in the body of the POST request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
appMode | boolean | False | Optional and for internal use only. |
deploySpecifiedObjectsOnly | boolean | False | Pertains to partial deployments only. Set to false by default. The value true restricts the deployment to the objects listed in objectsToDeployReferences only, which can cause the deployment to fail if there are missing dependencies. |
description | string | False | Optional description for task |
deviceGroupReferences | array | False | Device groups used when generating the list of differences. Used by modules that support device groups excepting access. Access has its own group property that supports a single device group reference. All members of the group are added to the deviceReferences list automatically. |
link | string | False | URL of the device group |
deviceReferences | array | True | List of devices in the modules’ all-bigips group which are receiving the deployment. All cluster members must be included if using Device Service Clustering (DSC) to select devices in clusters. |
link | string | False | URL of the BIG-IP |
disableUnusedObjectRemoval | boolean | False | Set to false by default, which flags unused shared objects as removed in the difference and removed during deployment. If true, unused objects are not listed as removed. |
name | string | True | Name for the task |
objectsToDeployReferences | array | False | The list of objects to deploy for a partial deployment. If non-null and non-empty, this is a partial deployment. Otherwise it’s a full deployment. The downstream dependencies of these objects are deployed by default. Setting deploySpecifiedObjectsOnly to true restricts deployment to objects listed in objectsToDeployReferences only, which can cause the deployment to fail if there are missing dependencies. |
link | string | False | A working-config object to deploy. Using the current-config of a removed object requires enabling partialModeEnableDeletedObjectRemoval. |
partialModeEnableDeletedObjectRemoval | boolean | False | Pertains to partial deployments only. For internal use only. The default value is false. |
properties | object | False | Generic properties of modules that aren’t supported in the base classes. If properties is present, it can be one of AccessPropertiesBag or DnPropertiesBag but not both. |
AccessPropertiesBag | object | False | Generic properties of module. |
cm:access:post-deploy | boolean | False | Access specific property |
config:apply-policies | boolean | False | Access specific property |
DnsPropertiesBag | object | False | Generic properties used by dns module. |
dnsDistributeMode | string | False | Specifies the type of DNS objects to deploy. SYNC_GROUP deploys configuration as a single member of the sync group. NON_SYNC_GROUP is deployed like a config in other modules. Possible values: “ALL”, “SYNC_GROUP” or “NON_SYNC_GROUP”. |
reevaluate | boolean | False | Set to true when restarting an evaluated deployment task to force the changes to be reevaluated. This will use the original snapshot from the evaluated task as a source and recalculate differences and config verification. |
refreshSharedConfig | boolean | False | By default, refreshSharedConfig is true and the shared module current-config, cm/shared/current-config/, is refreshed by each deployment task. refreshSharedConfig can be used to prevent unnecessary refreshes of a shared module by using true in the first deployment and then using false in all subsequent deployments. |
skipCurrentConfigRefresh | boolean | False | False by default and true should be considered for internal use only. True skips refreshing current-config for the devices in partial deployment. Available in partial deployments only if the current-config has already been refreshed. |
skipDistribution | boolean | False | Set to true to evaluate the changes and stop before sending changes to the devices. This cause the deployment to stop in status`=FINISHED and `currentStep =DISTRIBUTE_CONFIG. In that state the deployment can be restarted with a PACH request and setting skipDistribution to false to push the previously evaluated changes to the devices. |
skipVerifyConfig | boolean | False | Set to true to prevent running offline verification. |
snapshotReference | object | True | The snapshot used by deployment. When supplied as input from the client this directs the deployment to use an existing snapshot. When not supplied as input the deploy task can generate a new snapshot of live working-config, populate this property and use that when differencing. |
link | string | False | URL of the snapshot being deployed. |
verificationOptions | object | False | Optional settings to use when running offline verification. |
skipCrossModuleVerification | boolean | False | Set to true to prevent cross module offline verification. |
Query Parameters¶
None
Response¶
The JSON in the body of the response to the POST request represents the initial state of the deployment task and returns a selfLink and id for the task. The task’s status in the initial response to the POST request can be “STARTED”. To poll for an updated status of the task you can send GET requests to the task’s selfLink.
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
appMode | boolean | Optional and for internal use only. |
clusterDistributeTaskReferences | array | List of cluster distribute tasks for devices in clusters that rely on DSC on BIG-IP to keep them in sync. There will be a task per cluster. |
link | string | The URL for a cluster distribute task. |
configCopyTaskReferences | array | The deployment task started to make current-config reflect the changes that were just deployed to the device. Foldback: updating current-config to show the new state of each BIG-IP (by copying from working-config rather than by querying the device). |
link | string | The URI of a config copy task in FOLDBACK mode. |
currentStep | string | Indicates what the task is currently doing. Possible values: CLEANUP_PREVIOUS_EVALUATE”, CHECK_LICENSE”, “CHECK_OTHER_RUNNING_TASKS”, “GET_DEVICE_GROUPS”, “GET_DEVICES”, “INITIALIZE_DEVICE_DETAILS”, “CHECK_DEVICE_AVAILABILITY”, “REFRESH_SHARED_CONFIG”, “REFRESH_CURRENT_CONFIG_REST”, “LOOKUP_CLUSTERS”, “PRE_PARTIAL_DEPLOYMENT”, “INITIAL_SETUP_DONE”, “CREATE_SNAPSHOT”, “CREATE_DIFFERENCE”, “VERIFY_CONFIG”, “GET_CHILD_DEPLOY_DEVICES”, “START_CHILD_DEPLOY”, “WAIT_FOR_CHILD_DEPLOY”, “DISTRIBUTE_CONFIG”, “GET_DEPLOYMENT_TRACKERS”, “DISTRIBUTE_CONFIG_REST”, “DISTRIBUTE_DSC_CLUSTERS”, “DISTRIBUTE_OTHER”, “FOLDBACK_DEPLOYED_ADDITIONS”, “REFRESH_WORKING_CONFIG”, “POST_DEPLOYMENT” or “DONE”. |
deploySpecifiedObjectsOnly | boolean | Pertains to partial deployments only. Set to false by default. The value true restricts the deployment to the objects listed in objectsToDeployReferences only, which can cause the deployment to fail if there are missing dependencies. |
description | string | Optional description for task |
deviceDetails | array | Information about each device in the deploy task. |
hostname | string | The hostname of the device. |
deviceReference | object | The device this information pertains to. |
link | string | The URL of the device. |
differenceCount | number | The number of differences found on the device. |
status | string | The status of the distribution to the device. If FAIL check the deviceErrors for the reason. If UNCHANGED it means there were no differences for the device. Possible values: “SUCCESS”, “FAIL” or “UNCHANGED”. |
postDeploymentErrorCount | number | An error count associated with post deploy tasks if the module has implemented them. |
verificationErrorCount | number | The number of warnings verification found. |
verificationCriticalErrorCount | number | The number of critical errors verification found. These prevent any changes from being deployed to the device. |
deviceErrors | array | A list of devices that failed for some reason. |
deviceReference | object | The failed device. |
link | string | The URI for the device that failed. |
error | string | The error message for the device. |
deviceGroupReferences | array | Device groups used when generating the list of differences. Used by modules that support device groups excepting access. Access has its own group property that supports a single device group reference. All members of the group are added to the deviceReferences list automatically. |
link | string | URL of the device group |
deviceReferences | array | List of devices in the modules’ all-bigips group which are receiving the deployment. All cluster members must be included if using Device Service Clustering (DSC) to select devices in clusters. |
link | string | URL of the BIG-IP |
differenceReference | object | The difference result produced by the difference task. |
link | string | The URL of the module specific difference report. |
differenceTaskReference | object | The difference task initiate by this deployment |
link | string | The URL of the module specific difference task |
discoveryTaskReferences | array | List of the module discovery tasks that were run to refresh current-config. |
link | string | The URL of a module discovery task that was run for a specific device. |
disableUnusedObjectRemoval | boolean | Set to false by default, which flags unused shared objects as removed in the difference and removed during deployment. If true, unused objects are not listed as removed. |
distributeTaskReferences | array | List of distribute tasks deploy started for standalone devices or clusters configured with useBigiqSync=true. |
link | string | The URL for a devices distribute task. |
endDateTime | string | The time the task stopped running. |
errorMessage | string | An error encountered while the task was running. There may be errors even when the task is not FAILED. |
futureSchedule | object | The schedule that determines when the task will run. This object supports all properties of the scheduler API but only the most relevant are described here. If scheduling a deployment just use the recommended properties below. |
status | string | Determines whether or not to run the schedule. Possible values: “ENABLED” or “DISABLED”. |
timeToStartOn | string | When to start. It must be atleast 5 seconds later than the current time. |
futureScheduleReference | object | A link to the schedule. |
link | string | The link to the schedule in the scheduler API. You should not edit the schedule directly in the scheduler API. Any changes you want to make should be made by sending a PATCH to the deploy tasks futureSchedule property. |
id | string | The id for the item in the collection, used when accessing it directly. |
identityReferences | array | A list of user identities that initiated the task |
link | string | The URL of the identity. |
name | string | Name for the task |
noDifferenceFound | boolean | True when there are no differences to deploy for all of the devices specified. |
objectsToDeployReferences | array | The list of objects to deploy for a partial deployment. If non-null and non-empty, this is a partial deployment. Otherwise it’s a full deployment. The downstream dependencies of these objects are deployed by default. Setting deploySpecifiedObjectsOnly to true restricts deployment to objects listed in objectsToDeployReferences only, which can cause the deployment to fail if there are missing dependencies. |
link | string | A working-config object to deploy. Using the current-config of a removed object requires enabling partialModeEnableDeletedObjectRemoval. |
ownerMachineId | string | In a high-availability environment, the machineId of the host running the task |
parentTaskReference | object | The task API that initiated the task. |
link | string | The URL of the task that initiated this task. |
partialModeEnableDeletedObjectRemoval | boolean | Pertains to partial deployments only. For internal use only. The default value is false. |
postDeployTaskReference | object | A reference to a module specific task that runs at the end of deployment. Only the access team implements this. |
link | string | The URI for whatever the task is. |
properties | object | Generic properties of modules that aren’t supported in the base classes. If properties is present, it can be one of AccessPropertiesBag or DnPropertiesBag but not both. |
AccessPropertiesBag | object | Generic properties of access module. |
cm:access:post-deploy | boolean | Access specific property |
config:apply-policies | boolean | Access specific property |
DnsPropertiesBag | object | Generic properties used by dns module. |
dnsDistributeMode | string | Specifies the type of DNS objects to deploy. SYNC_GROUP deploys configuration as a single member of the sync group. NON_SYNC_GROUP is deployed like a config in other modules. Possible values: “ALL”, “SYNC_GROUP” or “NON_SYNC_GROUP”. |
reevaluate | boolean | Set to true when restarting an evaluated deployment task to force the changes to be reevaluated. This will use the original snapshot from the evaluated task as a source and recalculate differences and config verification. |
refreshSharedConfig | boolean | By default, refreshSharedConfig is true and the shared module current-config, cm/shared/current-config/, is refreshed by each deployment task. refreshSharedConfig can be used to prevent unnecessary refreshes of a shared module by using true in the first deployment and then using false in all subsequent deployments. |
selfLink | string | The URL to access this item directly. |
skipCurrentConfigRefresh | boolean | False by default and true should be considered for internal use only. True skips refreshing current-config for the devices in partial deployment. Available in partial deployments only if the current-config has already been refreshed. |
skipDistribution | boolean | Set to true to evaluate the changes and stop before sending changes to the devices. This cause the deployment to stop in status`=FINISHED and `currentStep =DISTRIBUTE_CONFIG. In that state the deployment can be restarted with a PACH request and setting skipDistribution to false to push the previously evaluated changes to the devices. |
skipVerifyConfig | boolean | Set to true to prevent running offline verification. |
snapshotReference | object | The snapshot used by deployment. When supplied as input from the client this directs the deployment to use an existing snapshot. When not supplied as input the deploy task can generate a new snapshot of live working-config, populate this property and use that when differencing. |
link | string | URL of the snapshot being deployed. |
snapshotTaskReference | object | The snapshot task that was started by deployment for cases where deploy is using live working-config instead of deploying from an existing snapshot. |
link | string | The URI of the snapshot task that was run. |
startDateTime | string | The time the task was started. |
status | string | The initial status of the task. The task’s status in the initial response to the POST request can be “STARTED”. To poll for an updated status of the task you can send repeated GET requests to the task’s selfLink. Possible status values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker |
type | string | Indicates the type of deployment that was run. Possible values: “Full” or “Partial”. A full, or standard, deployment task follows all references and deploys the entire configuration for the specified module of the BIG-IP. A partial, or selected, deployment task deploys a client-specified subset of pending changes. |
username | string | The user that initiated the task. |
userReference | object | The user that initiated the task. |
link | string | The URL of the user. |
verificationOptions | object | Optional settings to use when running offline verification. |
skipCrossModuleVerification | boolean | Set to true to prevent cross module offline verification. |
verifyConfigReference | object | The offline verification results for the devices in deployment. |
link | string | The URI for the offline verification result. |
verifyConfigTaskReference | object | The offline verification task that was run by deployment. |
link | string | The URL for the offline verification task. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
GET /cm/<module>/tasks/deploy-configuration/<id>¶
To check the status of a task you can send a GET request to the <module>/tasks/deploy-configuration/<id> endpoint and specify the task’s id. In the following, <module> is a placeholder representing the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe. The task’s id and selfLink can be obtained from the response to a previous GET request or from the response to the original POST used to create the task.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the discovery task. |
appMode | boolean | Optional and for internal use only. |
clusterDistributeTaskReferences | array | List of cluster distribute tasks for devices in clusters that rely on DSC on BIG-IP to keep them in sync. There will be a task per cluster. |
link | string | The URL for a cluster distribute task. |
configCopyTaskReferences | array | The deployment task started to make current-config reflect the changes that were just deployed to the device. Foldback: updating current-config to show the new state of each BIG-IP (by copying from working-config rather than by querying the device). |
link | string | The URI of a config copy task in FOLDBACK mode. |
currentStep | string | Indicates what the task is currently doing. Possible values: CLEANUP_PREVIOUS_EVALUATE”, CHECK_LICENSE”, “CHECK_OTHER_RUNNING_TASKS”, “GET_DEVICE_GROUPS”, “GET_DEVICES”, “INITIALIZE_DEVICE_DETAILS”, “CHECK_DEVICE_AVAILABILITY”, “REFRESH_SHARED_CONFIG”, “REFRESH_CURRENT_CONFIG_REST”, “LOOKUP_CLUSTERS”, “PRE_PARTIAL_DEPLOYMENT”, “INITIAL_SETUP_DONE”, “CREATE_SNAPSHOT”, “CREATE_DIFFERENCE”, “VERIFY_CONFIG”, “GET_CHILD_DEPLOY_DEVICES”, “START_CHILD_DEPLOY”, “WAIT_FOR_CHILD_DEPLOY”, “DISTRIBUTE_CONFIG”, “GET_DEPLOYMENT_TRACKERS”, “DISTRIBUTE_CONFIG_REST”, “DISTRIBUTE_DSC_CLUSTERS”, “DISTRIBUTE_OTHER”, “FOLDBACK_DEPLOYED_ADDITIONS”, “REFRESH_WORKING_CONFIG”, “POST_DEPLOYMENT” or “DONE”. |
deploySpecifiedObjectsOnly | boolean | Pertains to partial deployments only. Set to false by default. The value true restricts the deployment to the objects listed in objectsToDeployReferences only, which can cause the deployment to fail if there are missing dependencies. |
description | string | Optional description for task |
deviceDetails | array | Information about each device in the deploy task. |
hostname | string | The hostname of the device. |
deviceReference | object | The device this information pertains to. |
link | string | The URL of the device. |
differenceCount | number | The number of differences found on the device. |
status | string | The status of the distribution to the device. If FAIL check the deviceErrors for the reason. If UNCHANGED it means there were no differences for the device. Possible values: “SUCCESS”, “FAIL” or “UNCHANGED”. |
postDeploymentErrorCount | number | An error count associated with post deploy tasks if the module has implemented them. |
verificationErrorCount | number | The number of warnings verification found. |
verificationCriticalErrorCount | number | The number of critical errors verification found. These prevent any changes from being deployed to the device. |
deviceErrors | array | A list of devices that failed for some reason. |
deviceReference | object | The failed device. |
link | string | The URI for the device that failed. |
error | string | The error message for the device. |
deviceGroupReferences | array | Device groups used when generating the list of differences. Used by modules that support device groups excepting access. Access has its own group property that supports a single device group reference. All members of the group are added to the deviceReferences list automatically. |
link | string | URL of the device group |
deviceReferences | array | List of devices in the modules’ all-bigips group which are receiving the deployment. All cluster members must be included if using Device Service Clustering (DSC) to select devices in clusters. |
link | string | URL of the BIG-IP |
differenceReference | object | The difference result produced by the difference task. |
link | string | The URL of the module specific difference report. |
differenceTaskReference | object | The difference task initiate by this deployment |
link | string | The URL of the module specific difference task |
discoveryTaskReferences | array | List of the module discovery tasks that were run to refresh current-config. |
link | string | The URL of a module discovery task that was run for a specific device. |
disableUnusedObjectRemoval | boolean | Set to false by default, which flags unused shared objects as removed in the difference and removed during deployment. If true, unused objects are not listed as removed. |
distributeTaskReferences | array | List of distribute tasks deploy started for standalone devices or clusters configured with useBigiqSync=true. |
link | string | The URL for a devices distribute task. |
endDateTime | string | The time the task stopped running. |
errorMessage | string | An error encountered while the task was running. There may be errors even when the task is not FAILED. |
futureSchedule | object | The schedule that determines when the task will run. This object supports all properties of the scheduler API but only the most relevant are described here. If scheduling a deployment just use the recommended properties below. |
status | string | Determines whether or not to run the schedule. Possible values: “ENABLED” or “DISABLED”. |
timeToStartOn | string | When to start. It must be atleast 5 seconds later than the current time. |
futureScheduleReference | object | A link to the schedule. |
link | string | The link to the schedule in the scheduler API. You should not edit the schedule directly in the scheduler API. Any changes you want to make should be made by sending a PATCH to the deploy tasks futureSchedule property. |
id | string | The id for the item in the collection, used when accessing it directly. |
identityReferences | array | A list of user identities that initiated the task |
link | string | The URL of the identity. |
name | string | Name for the task |
noDifferenceFound | boolean | True when there are no differences to deploy for all of the devices specified. |
objectsToDeployReferences | array | The list of objects to deploy for a partial deployment. If non-null and non-empty, this is a partial deployment. Otherwise it’s a full deployment. The downstream dependencies of these objects are deployed by default. Setting deploySpecifiedObjectsOnly to true restricts deployment to objects listed in objectsToDeployReferences only, which can cause the deployment to fail if there are missing dependencies. |
link | string | A working-config object to deploy. Using the current-config of a removed object requires enabling partialModeEnableDeletedObjectRemoval. |
ownerMachineId | string | In a high-availability environment, the machineId of the host running the task |
parentTaskReference | object | The task API that initiated the task. |
link | string | The URL of the task that initiated this task. |
partialModeEnableDeletedObjectRemoval | boolean | Pertains to partial deployments only. For internal use only. The default value is false. |
postDeployTaskReference | object | A reference to a module specific task that runs at the end of deployment. Only the access team implements this. |
link | string | The URI for whatever the task is. |
properties | object | Generic properties of modules that aren’t supported in the base classes. If properties is present, it can be one of AccessPropertiesBag or DnPropertiesBag but not both. |
AccessPropertiesBag | object | Generic properties of access module. |
cm:access:post-deploy | boolean | Access specific property |
config:apply-policies | boolean | Access specific property |
DnsPropertiesBag | object | Generic properties used by dns module. |
dnsDistributeMode | string | Specifies the type of DNS objects to deploy. SYNC_GROUP deploys configuration as a single member of the sync group. NON_SYNC_GROUP is deployed like a config in other modules. Possible values: “ALL”, “SYNC_GROUP” or “NON_SYNC_GROUP”. |
reevaluate | boolean | Set to true when restarting an evaluated deployment task to force the changes to be reevaluated. This will use the original snapshot from the evaluated task as a source and recalculate differences and config verification. |
refreshSharedConfig | boolean | By default, refreshSharedConfig is true and the shared module current-config, cm/shared/current-config/, is refreshed by each deployment task. refreshSharedConfig can be used to prevent unnecessary refreshes of a shared module by using true in the first deployment and then using false in all subsequent deployments. |
selfLink | string | The URL to access this item directly. |
skipCurrentConfigRefresh | boolean | False by default and true should be considered for internal use only. True skips refreshing current-config for the devices in partial deployment. Available in partial deployments only if the current-config has already been refreshed. |
skipDistribution | boolean | Set to true to evaluate the changes and stop before sending changes to the devices. This cause the deployment to stop in status`=FINISHED and `currentStep =DISTRIBUTE_CONFIG. In that state the deployment can be restarted with a PACH request and setting skipDistribution to false to push the previously evaluated changes to the devices. |
skipVerifyConfig | boolean | Set to true to prevent running offline verification. |
snapshotReference | object | The snapshot used by deployment. When supplied as input from the client this directs the deployment to use an existing snapshot. When not supplied as input the deploy task can generate a new snapshot of live working-config, populate this property and use that when differencing. |
link | string | URL of the snapshot being deployed. |
snapshotTaskReference | object | The snapshot task that was started by deployment for cases where deploy is using live working-config instead of deploying from an existing snapshot. |
link | string | The URI of the snapshot task that was run. |
startDateTime | string | The time the task was started. |
status | string | The status of the task. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker |
type | string | Indicates the type of deployment that was run. Possible values: “Full” or “Partial”. Possible values: “Full” or “Partial”. A full, or standard, deployment task follows all references and deploys the entire configuration for the specified module of the BIG-IP. A partial, or selected, deployment task deploys a client-specified subset of pending changes. |
username | string | The user that initiated the task. |
userReference | object | The user that initiated the task. |
link | string | The URL of the user. |
verificationOptions | object | Optional settings to use when running offline verification. |
skipCrossModuleVerification | boolean | Set to true to prevent cross module offline verification. |
verifyConfigReference | object | The offline verification results for the devices in deployment. |
link | string | The URI for the offline verification result. |
verifyConfigTaskReference | object | The offline verification task that was run by deployment. |
link | string | The URL for the offline verification task. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
PATCH mgmt/cm/<module>/tasks/deploy-configuration/<id>¶
To cancel a running task, or restart a task with a “FINISHED” or “FAILED” status, you can send a PATCH request to the <module>/tasks/deploy-configuration endpoint and specify the task’s id. To cancel a running task, send a PATCH request to change the value of status to “CANCEL_REQUESTED”. Then send a GET request to poll the task until the value of status updates to “CANCELLED”, “FINISHED”, or “FAILED”. The values “FINISHED” or “FAILED” indicate the request was sent too late to cancel the task. A deployment task that has been evaluated without deployment can be restarted to deploy the evaluated changes to the device by changing the status from “FINISHED” to STARTED and setting skipDistribution to false. When restarting you can set a schedule to run the deployment later. A scheduled deployment can have the schedule modified by making changes to the futureSchedule properties.
Request Parameters¶
The request parameters in the PATCH request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
futureScheduleReference | object | False | A link to the schedule. |
link | string | False | The link to the schedule in the scheduler API. You should not edit the schedule directly in the scheduler API. Any changes you want to make should be made by sending a PATCH to the deploy tasks futureSchedule property. |
skipDistribution | boolean | True if restarting and deploying a previously evaluated task | Set to false to push the previously evaluated changes to the devices. |
status | string | True | To cancel a running task, send a PATCH request to change the value of status to “CANCEL_REQUESTED”. To deploy a task has been evaluated without deployment can be restarted to push the evaluated changes to the device by changing the status from “FINISHED” to “STARTED”. |
Response¶
HTTP/1.1 200 OK
The JSON in the response to a PATCH request can be the same as a GET to retrieve the task’s state.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
DELETE mgmt/cm/<module>/tasks/deploy-configuration/<id>¶
To delete a task you can send a DELETE request to the <module>/tasks/deploy-configuration endpoint and specify the task’s id. The task’s id and selfLink can be obtained from the response to a previous GET request or from the response to the original POST used to create the task.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
The JSON in the response from a DELETE request is similar to the response from a GET request.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
Examples¶
POST to deploy¶
The <module> is a placeholder representing the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
POST https://<BIG-IQ>/mgmt/cm/<module>/tasks/deploy-configuration
The following example creates a task to deploy the configuration for module on the specified BIG-IP. The JSON in the body of the POST can be similar to the following.
{
"name": "my_deploy_1",
"description": "some deploy task",
"deviceReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
}],
"deviceGroupReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/some-module-group"
}],
"snapshotReference": {
"link": "https://localhost/mgmt/cm/<module>/working-config/snapshots/<snapshot-id>"
},
"skipDistribution": true,
"reevaluate": true,
"skipVerifyConfig": true,
"verificationOptions": {
"skipCrossModuleVerification": true
},
"disableUnusedObjectRemoval": true,
"refreshSharedConfig": true,
"appMode": true,
"objectsToDeployReferences": [{
"link": "https://localhost/mgmt/cm/<module>/working-config/<collection>/<item-id>"
}],
"deploySpecifiedObjectsOnly": true,
"skipCurrentConfigRefresh": true,
"partialModeEnableDeletedObjectRemoval": true
}
Response¶
The JSON in the response to the POST can look similar to the following. The value of selfLink is the URL for the task. The value of status can be “STARTED” initially, which means the task has been started. To poll for the updated status, you can send repeated GET requests to the task’s selfLink.
{
"name": "my_deploy_1",
"description": "some deploy task",
"deviceReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
}],
"deviceGroupReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/some-module-group"
}],
"snapshotReference": {
"link": "https://localhost/mgmt/cm/<module>/working-config/snapshots/<snapshot-id>"
},
"skipDistribution": true,
"reevaluate": true,
"skipVerifyConfig": true,
"verificationOptions": {
"skipCrossModuleVerification": true
},
"disableUnusedObjectRemoval": true,
"refreshSharedConfig": true,
"appMode": true,
"objectsToDeployReferences": [{
"link": "https://localhost/mgmt/cm/<module>/working-config/<collection>/<item-id>"
}],
"deploySpecifiedObjectsOnly": true,
"skipCurrentConfigRefresh": true,
"partialModeEnableDeletedObjectRemoval": true,
"differenceTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/difference-config/<task-id>"
},
"differenceReference": {
"link": "https://localhost/mgmt/cm/<module>/reports/config-differences/<report-id>"
},
"discoveryTaskReferences": [{
"link": "https://localhost/mgmt/cm/<module>/tasks/discover-config/<task-id>"
}],
"snapshotTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/snapshot-config/<task-id>"
},
"postDeployTaskReference": {
"link": "https://localhost/mgmt/<some-task-collection>/<task-id>"
},
"distributeTaskReferences": [{
"link": "https://localhost/mgmt/<module-distribute-collection>/<task-id>"
}],
"clusterDistributeTaskReferences": [{
"link": "https://locahost/mgmt/cm/<module>/tasks/cluster-distribute-config/<task-id>"
}],
"configCopyTaskReferences": [{
"link": "https://localhost/mgmt/cm/<module>/tasks/config-copy/<task-id>"
}],
"deviceErrors": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
},
"error": "some error from BIG-IP that is likely completely useless."
}],
"noDifferenceFound": false,
"currentStep": "CLEANUP_PREVIOUS_EVALUATE",
"verifyConfigTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/verify-config/<task-id>"
},
"verifyConfigReference": {
"link": "https://localhost/mgmt/cm/<module>/reports/config-verifications/<report-id>"
},
"deviceDetails": [{
"status": "SUCCESS",
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
},
"differenceCount": 42,
"verificationErrorCount": 42,
"verificationCriticalErrorCount": 42,
"postDeploymentErrorCount": 42,
"hostname": "foo.com"
}],
"type": "Full",
"generation": 42,
"lastUpdateMicros": 1565705350970012,
"kind": "cm:adc-core:tasks:deploy-configuration:deployconfigtaskstate",
"selfLink": "https://localhost/mgmt/cm/adc-core/tasks/deploy-configuration/c0f8c6e9-1ea1-4e21-9538-618c90705b6f",
"id": "c0f8c6e9-1ea1-4e21-9538-618c90705b6f",
"status": "STARTED",
"startDateTime": "2019-10-02T19:26:45.007Z",
"errorMessage": "some error message",
"userReference": {
"link": "string"
},
"identityReferences": [{
"link": "string"
}],
"ownerMachineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "string"
},
"futureSchedule": {
"status": "ENABLED",
"timeToStartOn": "2019-10-02"
},
"futureScheduleReference": {
"link": "string"
}
}
GET to check the updated status¶
The following example gets the updated status for the task identified by id and selfLink. You can send repeated GET requests to check the status of the task, which can eventually update to “DONE” and “FINISHED”. The <module> is a placeholder representing the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
GET https://<BIG-IQ>/mgmt/cm/global/tasks/deploy-configuration/<id>
Response¶
The JSON in the response to the GET when the task is done can look similar to the following.
{
"name": "my_deploy_1",
"description": "some deploy task",
"deviceReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
}],
"deviceGroupReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/some-module-group"
}],
"snapshotReference": {
"link": "https://localhost/mgmt/cm/<module>/working-config/snapshots/<snapshot-id>"
},
"skipDistribution": true,
"reevaluate": true,
"skipVerifyConfig": true,
"verificationOptions": {
"skipCrossModuleVerification": true
},
"disableUnusedObjectRemoval": true,
"refreshSharedConfig": true,
"appMode": true,
"objectsToDeployReferences": [{
"link": "https://localhost/mgmt/cm/<module>/working-config/<collection>/<item-id>"
}],
"deploySpecifiedObjectsOnly": true,
"skipCurrentConfigRefresh": true,
"partialModeEnableDeletedObjectRemoval": true,
"differenceTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/difference-config/<task-id>"
},
"differenceReference": {
"link": "https://localhost/mgmt/cm/<module>/reports/config-differences/<report-id>"
},
"discoveryTaskReferences": [{
"link": "https://localhost/mgmt/cm/<module>/tasks/discover-config/<task-id>"
}],
"snapshotTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/snapshot-config/<task-id>"
},
"postDeployTaskReference": {
"link": "https://localhost/mgmt/<some-task-collection>/<task-id>"
},
"distributeTaskReferences": [{
"link": "https://localhost/mgmt/<module-distribute-collection>/<task-id>"
}],
"clusterDistributeTaskReferences": [{
"link": "https://locahost/mgmt/cm/<module>/tasks/cluster-distribute-config/<task-id>"
}],
"configCopyTaskReferences": [{
"link": "https://localhost/mgmt/cm/<module>/tasks/config-copy/<task-id>"
}],
"deviceErrors": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
},
"error": "some error from BIG-IP that is likely completely useless."
}],
"noDifferenceFound": false,
"currentStep": "CLEANUP_PREVIOUS_EVALUATE",
"verifyConfigTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/verify-config/<task-id>"
},
"verifyConfigReference": {
"link": "https://localhost/mgmt/cm/<module>/reports/config-verifications/<report-id>"
},
"deviceDetails": [{
"status": "SUCCESS",
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
},
"differenceCount": 42,
"verificationErrorCount": 42,
"verificationCriticalErrorCount": 42,
"postDeploymentErrorCount": 42,
"hostname": "foo.com"
}],
"type": "Full",
"generation": 42,
"lastUpdateMicros": 1565705350970012,
"kind": "cm:adc-core:tasks:deploy-configuration:deployconfigtaskstate",
"selfLink": "https://localhost/mgmt/cm/adc-core/tasks/deploy-configuration/c0f8c6e9-1ea1-4e21-9538-618c90705b6f",
"id": "c0f8c6e9-1ea1-4e21-9538-618c90705b6f",
"status": "STARTED",
"startDateTime": "2019-10-03T18:22:08.139Z",
"errorMessage": "some error message",
"userReference": {
"link": "string"
},
"identityReferences": [{
"link": "string"
}],
"ownerMachineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "string"
},
"futureSchedule": {
"status": "ENABLED",
"timeToStartOn": "2019-10-03"
},
"futureScheduleReference": {
"link": "string"
}
}
{
"name": "discovery_10.255.85.114",
"description": null,
PATCH to cancel a running task¶
You can send a PATCH request to cancel a running task specified by the task’s id. The <module> is a placeholder representing the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
PATCH https://<BIG-IQ>/mgmt/cm/<module>/tasks/deploy-configuration/<id>
In the body of the PATCH request specify the value of status as “CANCEL_REQUESTED”.
{
"status": "CANCEL_REQUESTED"
}
Response¶
Send repeated GET requests to poll the task until the value of status updates to “CANCELLED”, “FINISHED”, or “FAILED”. The values “FINISHED” or “FAILED” indicate the request was sent too late to cancel the task.
PATCH to restart and deploy an evaluated task¶
You can send a PATCH request to restart a task that has been evaluated without deployment. Specify the task to restart by the task’s id. The <module> is a placeholder representing the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
PATCH https://<BIG-IQ>/mgmt/cm/<module>/tasks/deploy-configuration/<id>
In the body of the PATCH request specify the value of status as “STARTED” and the value of “skipDistribution” to false.
{
"skipDistribution": false,
"status": "STARTED"
}
Response¶
Send repeated GET requests to poll the task until the value of status updates to “FINISHED” or “FAILED”.
PATCH to modify a task¶
You can send a PATCH request to modify a task. Specify the task to restart by the task’s id. The <module> is a placeholder representing the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
PATCH https://<BIG-IQ>/mgmt/cm/<module>/tasks/deploy-configuration/<id>
In the body of the PATCH request specify the new values of the changed parameters.
{
"name": "my_deploy_1",
"description": "some deploy task",
"deviceReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
}],
"deviceGroupReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/some-module-group"
}],
"snapshotReference": {
"link": "https://localhost/mgmt/cm/<module>/working-config/snapshots/<snapshot-id>"
},
"skipDistribution": true,
"reevaluate": true,
"skipVerifyConfig": true,
"verificationOptions": {
"skipCrossModuleVerification": true
},
"disableUnusedObjectRemoval": true,
"refreshSharedConfig": true,
"appMode": true
}
Response¶
The JSON in the body of the response to the PATCH can be similar to the following.
{
"name": "my_deploy_1",
"description": "some deploy task",
"deviceReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
}],
"deviceGroupReferences": [{
"link": "https://localhost/mgmt/shared/resolver/device-groups/some-module-group"
}],
"snapshotReference": {
"link": "https://localhost/mgmt/cm/<module>/working-config/snapshots/<snapshot-id>"
},
"skipDistribution": true,
"reevaluate": true,
"skipVerifyConfig": true,
"verificationOptions": {
"skipCrossModuleVerification": true
},
"disableUnusedObjectRemoval": true,
"refreshSharedConfig": true,
"appMode": true,
"objectsToDeployReferences": [{
"link": "https://localhost/mgmt/cm/<module>/working-config/<collection>/<item-id>"
}],
"deploySpecifiedObjectsOnly": true,
"skipCurrentConfigRefresh": true,
"partialModeEnableDeletedObjectRemoval": true,
"differenceTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/difference-config/<task-id>"
},
"differenceReference": {
"link": "https://localhost/mgmt/cm/<module>/reports/config-differences/<report-id>"
},
"discoveryTaskReferences": [{
"link": "https://localhost/mgmt/cm/<module>/tasks/discover-config/<task-id>"
}],
"snapshotTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/snapshot-config/<task-id>"
},
"postDeployTaskReference": {
"link": "https://localhost/mgmt/<some-task-collection>/<task-id>"
},
"distributeTaskReferences": [{
"link": "https://localhost/mgmt/<module-distribute-collection>/<task-id>"
}],
"clusterDistributeTaskReferences": [{
"link": "https://locahost/mgmt/cm/<module>/tasks/cluster-distribute-config/<task-id>"
}],
"configCopyTaskReferences": [{
"link": "https://localhost/mgmt/cm/<module>/tasks/config-copy/<task-id>"
}],
"deviceErrors": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
},
"error": "some error from BIG-IP that is likely completely useless."
}],
"noDifferenceFound": false,
"currentStep": "CLEANUP_PREVIOUS_EVALUATE",
"verifyConfigTaskReference": {
"link": "https://localhost/mgmt/cm/<module>/tasks/verify-config/<task-id>"
},
"verifyConfigReference": {
"link": "https://localhost/mgmt/cm/<module>/reports/config-verifications/<report-id>"
},
"deviceDetails": [{
"status": "SUCCESS",
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/<module-all-bigips>/devices/<device-uuid>"
},
"differenceCount": 42,
"verificationErrorCount": 42,
"verificationCriticalErrorCount": 42,
"postDeploymentErrorCount": 42,
"hostname": "foo.com"
}],
"type": "Full",
"generation": 42,
"lastUpdateMicros": 1565705350970012,
"kind": "cm:adc-core:tasks:deploy-configuration:deployconfigtaskstate",
"selfLink": "https://localhost/mgmt/cm/adc-core/tasks/deploy-configuration/c0f8c6e9-1ea1-4e21-9538-618c90705b6f",
"id": "c0f8c6e9-1ea1-4e21-9538-618c90705b6f",
"status": "STARTED",
"startDateTime": "2019-10-07T17:48:39.499Z",
"errorMessage": "some error message",
"userReference": {
"link": "string"
},
"identityReferences": [{
"link": "string"
}],
"ownerMachineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "string"
},
"futureSchedule": {
"status": "ENABLED",
"timeToStartOn": "2019-10-07"
},
"futureScheduleReference": {
"link": "string"
}
}
You can then send repeated GET requests to poll the task until the value of status updates to “FINISHED” or “FAILED”.
DELETE to delete a discovery task¶
The following example deletes the task identified by id. The <module> is a placeholder representing the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
DELETE https://<BIG-IQ>/mgmt/cm/<module>/tasks/deploy-configuration/<id>
Response¶
The JSON in the response from a DELETE request is similar to a response from a GET request.