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.