DNS Self Service¶

Overview¶

Use the DNS Self Service API to create and check the status of tasks to enable or disable DNS objects, such as DNS listener, pool, server or DataCenter objects. You must create a data center, a server, and a listener before you can answer any DNS queries or establish a DNS sync group. If you are an owner of a enterprise technology application, you may want to use the DNS Self Service API when deploying a Global Server Load Balancing (GSLB) configuration. This API can enable you to deploy a GSLB configuration without having to access the deployment screen in the UI, which can reduce overhead and allow faster changes to the DNS configuration.

Note that some objects can be for a specific BIG-IP, whereas other objects can be for a synchronization group.

REST Endpoint: /mgmt/cm/dns/tasks/self-service¶

Requests¶

POST /mgmt/cm/dns/tasks/self-service¶

To create a task to enable or disable a DNS listener or a DataCenter object, you can send a POST request to the tasks/self-service endpoint.

Request Parameters¶

The JSON in the body of the POST request can contain the following parameters.

Name	Type	Required	Description
name	string	True	Name of the task
resourceReference	object	True	Reference link to the resource for self service. It can point to an object in DNS working-config
link	string	True	URL
operation	string	True	Possible values: “enable” or “disable”.

Query Parameters¶

None

Response¶

The JSON in the response can contain the following parameters.

HTTP/1.1 200 OK

Name	Type	Description
id	string	The UUID identifier of the task.
name	string	Name of the task
status	string	The 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”.
selfLink	string	The URL to access the endpoint of this task directly.
operation	string	Specifies whether this task enables or disables the object. Possible values: “enable” or “disable”.
customOptions	object	Custom properties and options.
customProperties	object	Properties object for sub-tasks
<selfLink URL of parent task>	object	The UUID identifier for the BIG-IP targeted by the request.
step	string	The state of the child tasks. Possible values: “INITIAL”, “GET_DEVICES”, “GET_DEVICES_GLOBAL_SETTINGS”, “CALCULATE_DEVICES”, “SUBSCRIBE_TO_SELFSERVICE”, “START_SUB_TASKS”, “UPDATE_TASK_WITH_SUB_TASKS” and “DONE”.
childTaskList	object	List of URLs to access the child tasks directly.
optionsForTroubleshooting	object	Options for troubleshooting
userReference	object	The user that initiated the task.
link	string	URL for the user
ownerMachineId	string	In a high-availability environment, the machineId of the host running the task.
resourceReference	object	Reference link to the resource for self service
link	string	URL for the resource
identityReferences	object	References to users provided as links.
link	string	URL for user

Permissions¶

Role	Allow
admin	Yes
Application_Editor	Yes
DNS_Viewer	No
DNS_Deployer	Yes
Service_Catalog_Viewer	No
DNS_Editor	Yes
Service_Catalog_Editor	Yes
Application_Manager	Yes
Application_Viewer	No
Trust_Discovery_Import	Yes
DNS_Manager	Yes

GET /mgmt/cm/dns/tasks/self-service/{task_id}¶

To retrieve information about a task, you can send a GET request specified by the task’s identifier, id.

Request Parameters¶

None

Query Parameters¶

None

Response¶

The JSON in the GET response can look similar to the response from the POST request.

Permissions¶

Role	Allow
admin	Yes
Application_Editor	Yes
DNS_Viewer	Yes
DNS_Deployer	Yes
Service_Catalog_Viewer	Yes
DNS_Editor	Yes
Service_Catalog_Editor	Yes
Application_Manager	Yes
Application_Viewer	Yes
Trust_Discovery_Import	Yes
DNS_Manager	Yes

GET /mgmt/cm/dns/tasks/self-service/{sub_task_id}¶

To retrieve information about a task, you can send a GET request specified by the sub task’s identifier, id.

Request Parameters¶

None

Query Parameters¶

None

Response¶

The JSON in the response can contain the following parameters.

HTTP/1.1 200 OK

Name	Type	Description
id	string	The UUID identifier of the sub-task.
name	string	Name of the sub-task
status	string	The status of the parent 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”.
selfLink	string	The URL to access the endpoint of the sub-task directly.
operation	string	Specifies whether this task enables or disables the object. Possible values: “enable” or “disable”.
customOptions	object	Custom properties and options.
customProperties	object	Properties object for sub-tasks
parentTask	object	URL of the parent task
optionsForTroubleshooting	object	Options for troubleshooting
startDateTime	string	Date and time the task was started. For example, “2020-09-09T09:33:48.745-0700”
userReference	object	The user that initiated the task.
link	string	URL for the user
ownerMachineId	string	In a high-availability environment, the machineId of the host running the task.
deviceReference	object	Reference link to the BIG-IP
link	string	URL for the BIG-IP
resourceReference	object	Reference link to the resource for self service
link	string	URL for the resource
identityReferences	object	References to users provided as links.
link	string	URL for user

Permissions¶

Role	Allow
Application_Editor	Yes
DNS_Viewer	Yes
DNS_Deployer	Yes
Service_Catalog_Viewer	Yes
DNS_Editor	Yes
Service_Catalog_Editor	Yes
Application_Manager	Yes
Application_Viewer	Yes
Trust_Discovery_Import	Yes
DNS_Manager	Yes

Examples¶

POST to enable or disable a DNS listener or DataCenter object¶

The following example sends a POST request to enable or disable a DNS listener or DataCenter object.

POST https://<BIG-IQ>/mgmt/mgmt/cm/dns/tasks/self-service

The JSON in the body of the POST can look similar to the following example. The value of operation can be “enable” or “disable”. The value of link in the resourceReference field can be the of an object in the DNS working-config.

{
    "name": "myTest01",
    "resourceReference": {
            "link": "https://localhost/mgmt/cm/dns/working-config/listener/ae1f274f-8e04-3ac6-821b-3158eec4b231"
    },
    "operation": "enable"
}

Response¶

The response to the POST can contain the id, selfLink and status of the task. The initial value of status can be “STARTED” the initial value of step can be “INITIAL”. The JSON in the body of the initial response to the POST can look similar to the following.

{
    "id": "5ba55f57-dbb1-4fdd-a216-05d822e71d49",
    "kind": "cm:dns:tasks:self-service:selfservicetaskitemstate",
    "name": "test-359",
    "status": "STARTED",
    "selfLink": "https://localhost/mgmt/cm/dns/tasks/self-service/5ba55f57-dbb1-4fdd-a216-05d822e71d49",
    "operation": "enable",
    "generation": 10,
    "customOptions": {
            "customProperties": {
                    "https://localhost/mgmt/cm/dns/tasks/self-service/5ba55f57-dbb1-4fdd-a216-05d822e71d49": {
                            "step": "INITIAL",
                            "childTaskList": [
                                    "https://localhost/mgmt/cm/dns/tasks/self-service/35604227-ddb5-49d5-b2bd-2917ae255035",
                                    "https://localhost/mgmt/cm/dns/tasks/self-service/582d36fa-edf1-4bdd-8ef7-70e6de586045"
                            ]
                    }
            },
            "optionsForTroubleshooting": {}
    },
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "ownerMachineId": "a8fa253b-5b29-49b7-9be1-b54d772681bd",
    "lastUpdateMicros": 1599669231945366,
    "resourceReference": {
            "link": "https://localhost/mgmt/cm/dns/working-config/datacenter/eb8c1e48-eb8a-30bf-91e0-e7152cd4ed27"
    },
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }]
}

You can then poll to check for completion of the task by sending repeated GET requests to the endpoint specified by id until the value of status in the response changes to “FINISHED” and the value of step changes to “DONE”. For this example, the placeholder {id} for the task can be replaced by the value 5ba55f57-dbb1-4fdd-a216-05d822e71d49.

GET https://<BIG-IQ>/mgmt/cm/dns/tasks/self-service/{id}

Note that in a sync-group workflow, BIG-IQ can launch multiple sub-tasks to perform a series of actions. The URL links to these sub-tasks are specified by the values in the childTaskList array. To get the status of a sub-task, you can send a GET request to the URL which specifies the child task.

For example, to get the status of the first child task in the list, the GET

GET https://<BIG-IQ>/mgmt/cm/dns/tasks/self-service/35604227-ddb5-49d5-b2bd-2917ae255035

The JSON in the body of the response to the GET can look similar to the following.

{
    "id": "35604227-ddb5-49d5-b2bd-2917ae255035",
    "kind": "cm:dns:tasks:self-service:selfservicetaskitemstate",
    "name": "test-359-child-1",
    "status": "FINISHED",
    "selfLink": "https://localhost/mgmt/cm/dns/tasks/self-service/35604227-ddb5-49d5-b2bd-2917ae255035",
    "username": "admin",
    "operation": "enable",
    "generation": 2,
    "endDateTime": "2020-09-09T09:33:51.828-0700",
    "customOptions": {
            "customProperties": {
                    "parentTask": "https://localhost/mgmt/cm/dns/tasks/self-service/5ba55f57-dbb1-4fdd-a216-05d822e71d49"
            },
            "optionsForTroubleshooting": {}
    },
    "startDateTime": "2020-09-09T09:33:48.745-0700",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "ownerMachineId": "a8fa253b-5b29-49b7-9be1-b54d772681bd",
    "deviceReference": {
            "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-dns-allBigIpDevices/devices/a92dd6ca-498d-4a25-b3b8-f92b174c4493"
    },
    "lastUpdateMicros": 1599669231880330,
    "resourceReference": {
            "link": "https://localhost/mgmt/cm/dns/working-config/datacenter/eb8c1e48-eb8a-30bf-91e0-e7152cd4ed27"
    },
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }]
}

Previous Next