Device Discovery¶
Overview¶
Use the Device Discovery API to create a super-task to determine what module objects exist on a specific BIG-IP and then create corresponding copies of these module objects in the BIG-IQ’s current-config. This process is referred to as ‘discovery’. To discover multiple modules from a single BIG-IP, send a POST request to the device-discovery task collection on the BIG-IQ. Specify the modules of interest in moduleList (firewall, security_shared, asm, adc_core, access, dns, fps or sslo). The API’s response can include the status for the super-task and for each individual module because the system runs a separate removal task for each module. If the required LTM (ADC) module is missing the entire super-task fails. Missing any other module does not cause failure and the super-task continues to discover the specified modules. Use the Device Import API to import copies of the module objects from the current-config to the working-config of the BIG-IQ. Use the Device RMA API to remove module objects from the working-config of the BIG-IQ.
REST Endpoint: mgmt/cm/global/tasks/device-discovery¶
Requests¶
To create a super-task to determine what module objects exist on a single BIG-IP and create corresponding copies of these module objects in the BIG-IQ’s current-config, send a POST request to the device-discovery endpoint.
POST mgmt/cm/global/tasks/device-discovery¶
Request Parameters¶
The JSON in the body of the POST request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
description | string | False | An optional description for the super-task. |
deviceReference | object | True | The deviceReference is a link object for the BIG-IP targeted by this discovery request. |
link | string | True | URL of deviceReference |
moduleList | object array | True | A list identifying the module objects to discover. The status fields of the module objects are not required in the POST request. Provide the module object identifier in module. |
module | string | True | Module object identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
name | string | False | An optional name for the super-task. |
Query Parameters¶
None
Response¶
The JSON in the body of the POST response can contain the following parameters. The super-task’s status in the initial response to the POST request can be “STARTED”, and to poll for the updated status you can send repeated GET requests to the selfLink of the task. The moduleList in the response to POST or GET can also contain information about the status of each individual module.
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the discovery task. |
allModuleStatus | object | List of discovered modules and status, whether being discovered in this run or previously discovered. Format is the same as moduleList. |
currentConfigConsistencyCheckReference | object | Reference to the current-config consistency-check task run by discovery. |
link | string | URL of currentConfigConsistencyCheckReference |
currentStep | string | Current step of the discovery task. Possible values: “INIT”, “CHECK_BULK_RPM_SUPPORT”, “INSTALL_BULK_RPM_ON_BIG_IP”, “FIND_OR_CREATE_MODULE_GROUPS”, “FIND_OR_CREATE_DEVICE_IN_MODULE_GROUPS”, “CHECK_RUNNING_TASKS”, “PROCESS_MODULE_TASKS”, “FAILED” or “DONE”. |
description | string | An optional description for the super-task. |
deviceReference | string | The value of deviceReference is a link object for the BIG-IP targeted by this discovery request. |
link | string | URL of deviceReference |
endDateTime | string | The time the super-task stopped running. |
errorMessage | string | An error encountered while the super-task was running. There can be errors even when the task’s status is not “FAILED”. |
id | string | The id of the super-task. |
moduleList | object | List of modules being discovered, with status. |
endTime | string | End time for module processing (UTC). |
errorMsg | string | Error message from module discovery task. |
module | string | Module object identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
startTime | string | Start time for module processing (UTC). |
status | string | Final status of module-specific task. Possible values: “QUEUED”, “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
statusQual | string | If the module status is “FAILED”, this value can be “TASK_BUSY”, which indicates that the module discovery task was already active. |
taskReference | string | Reference to module discovery task. |
link | string | URL of the reference to module discovery task. |
name | string | An optional name for the super-task. |
ownerMachineId | string | In a high-availability environment, the machine Id of the host running the super-task. |
selfLink | string | The URL to access this item directly. |
startDateTime | string | The time the super-task was started. |
status | string | Standard task status of the super-task, updated during execution. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
userReference | string | The user that initiated the super-task. |
link | string | URL for userReference |
identityReferences | array | A list of user identities that initiated the super-task. |
link | string | URL for an user identity |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker. |
parentTaskReference | object | The task API that initiated the task. |
link | string | URL for the task API that initiated the task. |
username | string | The user that initiated the super-task. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
GET /cm/global/tasks/device-discovery/<id>¶
To check the status of a super-task you can send a GET request to the endpoint and specify the super-task’s id. The super-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 super-task. The status of the individual module tasks are returned in moduleList.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the discovery task. |
allModuleStatus | object | List of discovered modules and status, whether being discovered in this run or previously discovered. Format is the same as moduleList. |
currentConfigConsistencyCheckReference | object | Reference to the current-config consistency-check task run by discovery. |
link | string | URL of currentConfigConsistencyCheckReference |
currentStep | string | Current step of the discovery task. Possible values: “INIT”, “CHECK_BULK_RPM_SUPPORT”, “INSTALL_BULK_RPM_ON_BIG_IP”, “FIND_OR_CREATE_MODULE_GROUPS”, “FIND_OR_CREATE_DEVICE_IN_MODULE_GROUPS”, “CHECK_RUNNING_TASKS”, “PROCESS_MODULE_TASKS”, “FAILED” or “DONE”. |
description | string | An optional description for the super-task. |
deviceReference | string | The value of deviceReference is a link object for the BIG-IP targeted by this discovery request. |
link | string | URL of deviceReference |
endDateTime | string | The time the super-task stopped running. |
errorMessage | string | An error encountered while the super-task was running. There can be errors even when the task’s status is not “FAILED”. |
id | string | The id of the super-task. |
moduleList | object | List of modules being discovered, with status. |
endTime | string | End time for module processing (UTC). |
errorMsg | string | Error message from module discovery task. |
module | string | Module object identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
startTime | string | Start time for module processing (UTC). |
status | string | Final status of module-specific task. Possible values: “QUEUED”, “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
statusQual | string | If the module status is “FAILED”, this value can be “TASK_BUSY”, which indicates that the module discovery task was already active. |
taskReference | string | Reference to module discovery task. |
link | string | URL of the reference to module discovery task. |
name | string | An optional name for the super-task. |
ownerMachineId | string | In a high-availability environment, the machine Id of the host running the super-task. |
selfLink | string | The URL to access this item directly. |
startDateTime | string | The time the super-task was started. |
status | string | Standard task status of the super-task, updated during execution. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
userReference | string | The user that initiated the super-task. |
link | string | URL for userReference |
identityReferences | array | A list of user identities that initiated the super-task. |
link | string | URL for an user identity |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker. |
parentTaskReference | object | The task API that initiated the task. |
link | string | URL for the task API that initiated the task. |
username | string | The user that initiated the task. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
PATCH mgmt/cm/global/tasks/device-discovery/<id>¶
To cancel a running super-task, or restart a super-task with a “FINISHED” or “FAILED” status, you can send a PATCH request to the endpoint and specify the super-task’s id. To cancel a running super-task, send a PATCH request to change the value of status to “CANCEL_REQUESTED”. Then send a GET request to poll the super-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 super-task. To restart a super-task having a status of “FINISHED” or “FAILED”, send a PATCH request to change the value of status to “STARTED” and optionally change moduleList.
Request Parameters¶
The JSON in the body of the PATCH request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
moduleList | array | False | When restarting a super-task in the “FINISHED” or “FAILED” state, you can optionally change the list of modules being discovered by changing moduleList. |
module | string | False | Module object identifier. Possible values are “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
status | string | True | Standard task status of the super-task, updated during execution. To cancel the super-task, this value can be changed to “CANCEL_REQUESTED”. To restart the super-task, this value can be “STARTED”. |
Response¶
HTTP/1.1 200 OK
The JSON in the body of the PATCH response can be similar to the GET response.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
DELETE /cm/global/tasks/device-discovery/<id>¶
To delete a super-task you can send a DELETE request to the endpoint and specify the super-task’s id. The super-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 super-task.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
The JSON in the body of the DELETE response can be similar to the GET response.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
Examples¶
POST to discover multiple modules¶
POST https://<BIG-IQ>/mgmt/cm/global/tasks/device-discovery
The following example creates a super-task to discover a module on the specified BIG-IP and create a corresponding copy of the specified module object in the BIG-IQ’s current-config. The JSON in the body of the POST can be similar to the following.
{
"name": "discovery_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"moduleList": [{
"module": "firewall"
}]
}
Response¶
The JSON in the response to the POST can look similar to the following. The value of selfLink is the URL for the super-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 super-task’s selfLink. Note that the status of the module is returned in moduleList.
{
"name": "discovery_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"currentStep": "INIT",
"currentConfigConsistencyCheckReference": {
"link": "https://localhost/mgmt/cm/global/tasks/current-config-consistency-check/6870028a-73a1-48d8-8b98-d408f1e13d6e"
},
"moduleList": [{
"module": "firewall",
"status": "STARTED",
"errorMsg": "Task https://localhost/mgmt/cm/firewall/tasks/discover-config/57e32353-5a91-470a-be34-a5ce1a17973a is still in process, wait for this task to complete.",
"startTime": "2019-08-26T19:04:13.722Z",
"endTime": "2019-08-26T19:04:16.769Z",
"taskReference": {
"link": "https://localhost/mgmt/cm/adc-core/tasks/discover-config/f5b4bb89-f6c6-400a-a24d-c6ee6db5138f"
}
}],
"allModuleStatus": [{}],
"generation": 42,
"lastUpdateMicros": 1566831675472009,
"kind": "cm:global:tasks:device-discovery:discoverysupertaskitemstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery/5c666846-e283-41cf-96f8-4b2e32360048",
"id": "5c666846-e283-41cf-96f8-4b2e32360048",
"status": "STARTED",
"startDateTime": "2019-08-28T09:38:25.097-0400",
"endDateTime": "2019-08-28T09:38:44.608-0400",
"errorMessage": "Failed to find or create module groups",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "24275453-2670-4acd-ac33-875aabcfc4bf",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/7e853383-4e8a-4e4b-93d8-7f117195223c"
}
}
GET to check the task’s status¶
The following example gets the updated status for the super-task identified by id and selfLink. You can send repeated GET requests to check the status of the super-task, which can eventually update to “DONE” and “FINISHED”.
GET https://<BIG-IQ>/mgmt/cm/global/tasks/device-discovery/<id>
Response¶
The JSON in the response to the GET when the task is done can look similar to the following. Note that the status of the module-specific task is included in moduleList.
{
"name": "discovery_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"currentStep": "INIT",
"currentConfigConsistencyCheckReference": {
"link": "https://localhost/mgmt/cm/global/tasks/current-config-consistency-check/6870028a-73a1-48d8-8b98-d408f1e13d6e"
},
"moduleList": [{
"module": "firewall",
"status": "FINISHED",
"errorMsg": "Task https://localhost/mgmt/cm/firewall/tasks/discover-config/57e32353-5a91-470a-be34-a5ce1a17973a is still in process, wait for this task to complete.",
"startTime": "2019-08-26T19:04:13.722Z",
"endTime": "2019-08-26T19:04:16.769Z",
"taskReference": {
"link": "https://localhost/mgmt/cm/adc-core/tasks/discover-config/f5b4bb89-f6c6-400a-a24d-c6ee6db5138f"
}
}],
"allModuleStatus": [{}],
"generation": 42,
"lastUpdateMicros": 1566831675472009,
"kind": "cm:global:tasks:device-discovery:discoverysupertaskitemstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery/5c666846-e283-41cf-96f8-4b2e32360048",
"id": "5c666846-e283-41cf-96f8-4b2e32360048",
"status": "FINISHED",
"startDateTime": "2019-08-28T09:38:25.097-0400",
"endDateTime": "2019-08-28T09:38:44.608-0400",
"errorMessage": "Failed to find or create module groups",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "24275453-2670-4acd-ac33-875aabcfc4bf",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/7e853383-4e8a-4e4b-93d8-7f117195223c"
}
}
PATCH to cancel a running super-task¶
You can send a PATCH request to cancel a running super-task specified by the task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-discovery/<id>
In the body of the PATCH request specify the value of status as “CANCEL_REQUESTED”.
{
"status": "CANCEL_REQUESTED"
}
Response¶
You can then send repeated GET requests to poll the super-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 super-task.
PATCH to restart a super-task¶
You can send a PATCH request to restart a super-task having a status of “FINISHED” or “FAILED”. Specify the super-task to restart by the super-task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-discovery/<id>
In the body of the PATCH request specify the value of status as “STARTED”, and you can optionally change the value of moduleList.
{
"moduleList": [{
"module": "firewall"
}],
"status": "STARTED"
}
Response¶
You can then send repeated GET requests to poll the super-task until the value of status updates to “FINISHED” or “FAILED”.
DELETE to delete a discovery task¶
The following example deletes the super-task identified by id.
DELETE https://<BIG-IQ>/mgmt/cm/global/tasks/device-discovery/<id>
Response¶
The JSON in the response from a DELETE request is similar to a response from a GET request.