Declarative Onboarding

Overview

You can use this API to transmit a declarative onboarding declaration to BIG-IQ to use Declarative Onboarding (DO) to configure your BIG-IPs. After you onboard the BIG-IPs, you can start managing them from the BIG-IQ. For more information about declarative onboarding, see the F5 Declarative Onboarding Documentation .

For information about the compatibility of BIG-IQ and BIG-IP with F5 Application Services 3 Extension (AS3) and F5 Declarative Onboarding (DO) releases, please refer to the support article: K54909607: BIG-IQ Centralized Management compatibility with F5 Application Services 3 Extension and F5 Declarative Onboarding .

REST Endpoint: /mgmt/shared/declarative-onboarding

Requests

POST /mgmt/shared/declarative-onboarding

To post a DO declaration you can send a POST request to the declarative-onboarding endpoint with the DO declaration included in the body of the request. The most important part of using Declarative Onboarding is creating the declaration that includes the BIG-IP objects you want the system to configure. See Composing a Declarative Onboarding declaration for a standalone BIG-IP for information on how to create a DO declaration.

Request Parameters

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

Name Type Required Description
class string True “DO”
bigIqSettings object True Settings for the BIG-IQ performing onboarding
     accessModuleProperties string Yes if an APM module is being imported Additional access module properties provided for the import.
     clusterName string True if the BIG-IP is to be managed as part of a cluster Cluster display name of the BIG-IP Device Service Clustering (DSC) group. clusterName must be the same for all the BIG-IPs in a DSC group.
     conflictPolicy string True if failImportOnConflict is false. Conflict policy for the onboarding. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ”, “KEEP_VERSION”
     deployWhenDscChangesPending string boolean Deploy when there are pending DSC changes on BIG-IP.
     deviceConflictPolicy string False Conflict policy for device-specific objects. For Access, a device-specific import can accept “USE_BIGIP” for all device-specific objects. Default is the same value as conflictPolicy. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ”, “KEEP_VERSION”
     failImportOnConflict boolean False True specifies to fail import task if there are conflicts. This can true if you want to resolve the conflicts manually. Default is false.
     snapshotWorkingConfig boolean False True specifies a snapshot of the working configuration for current BIG-IPs before the import. Default is false.
     statsConfig object False Stats configuration details for the BIG-IP
          enabled boolean True statsConfig if is defined True enables collecting statistics for the BIG-IP
          zone string False User-defined names that associate BIG-IPs with one or more data collection device (DCD) systems to provide optimal routing for statistics traffic. This value can be “default”.
     useBigiqSync boolean False True to use BIG-IQ to push changes to cluster BIG-IPs instead of using the BIG-IP cluster sync to synchronize configuration.
     versionedConflictPolicy string False Conflict policy for version-specific objects. For Access, a device-specific import can accept “USE_BIGIP” for all device-specific objects. Default is the same value as conflictPolicy. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ”, “KEEP_VERSION”
declaration object True The Declarative Onboarding declaration that you want to transmit. The DO declaration includes the BIG-IP objects you want the system to configure. For more information about creating a DO declaration, see Composing a Declarative Onboarding declaration for a standalone BIG-IP for information on how to create a DO declaration.
     async boolean True The async field must be true to use DO on BIG-IQ.
     Common object True Sections of the DO declaration.
          admin object True The admin section of Common in the DO declaration is required if making an AWS initial declaration using the targetSshKey.
targetHost string True IP address of the onboarding BIG-IP. Required for the initial or subsequent onboardings of a BIG-IP.
targetPassphrase string True Admin password of the onboarding BIG-IP. Required for the initial or subsequent onboardings of a BIG-IP in Azure or VMware environment. You must specify a targetUsername or targetSshKey when using an Azure or VMware environment. Not required for onboarding BIG-IP VEs in AWS cloud, if you have specified targetSshKey.
targetSshKey object False Required for initial onboarding of a new BIG-IP VE in an AWS cloud. Use targetPassphrase for any subsequent onboarding of the same BIG-IP VE on AWS. targetSshKey is not used in Azure and VMware environments, those environment alway uses targetUsername and targetPassphrase.
     path string False Path to ssh key.
targetUsername string True Admin user name of the onboarding BIG-IP. Required for the initial or subsequent onboardings of a BIG-IP.

Query Parameters

None

Response

HTTP/1.1 200 OK

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

Permissions

Role Allow
Admin Yes

Examples

POST to onboard a BIG-IP VE in AWS for first time

To transmit a DO declaration for the initial onboarding of a BIG-IP VE in an AWS cloud environment, you can send the POST request to the declarative-onboarding endpoint on the BIG-IQ with the declaration in the body. For more information about Declaration Onboarding in an AWS environment, refer to Adding and Configuring BIG-IP VE Devices in an AWS Cloud .

On the BIG-IQ, your POST can look similar to the following example.

POST https://192.0.2.242/mgmt/shared/declarative-onboarding

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

{
    "class": "DO",
    "declaration": {
            "schemaVersion": "1.5.0",
            "class": "Device",
            "async": true,
            "Common": {
                    "class": "Tenant",
                    "myLicense": {
                            "class": "License",
                            "licenseType": "regKey",
                            "regKey": "xxx-xxx-xxx-xx"
                    },
                    "myProvision": {
                            "class": "Provision",
                            "ltm": "nominal"
                    },
                    "myNtp": {
                            "class": "NTP",
                            "servers": [
                                    "time.nist.gov"
                            ],
                            "timezone": "UTC"
                    },
                    "admin": {
                            "class": "User",
                            "userType": "regular",
                            "partitionAccess": {
                                    "all-partitions": {
                                            "role": "admin"
                                    }
                            },
                            "shell": "tmsh",
                            "password": "adminpassword"
                    },
                    "root": {
                            "class": "User",
                            "userType": "root",
                            "newPassword": "rootpassword",
                            "oldPassword": "adminpassword"
                    }
            }
    },
    "targetHost": "54.10.10.10",
    "targetUsername": "admin",
    "targetSshKey": {
            "path": "/var/ssh/restnoded/privatessh.key"
    },
    "bigIqSettings": {
            "failImportOnConflict": false,
            "conflictPolicy": "USE_BIGIQ",
            "deviceConflictPolicy": "USE_BIGIP",
            "versionedConflictPolicy": "KEEP_VERSION",
            "statsConfig": {
                    "enabled": true,
                    "zone": "default"
            },
            "snapshotWorkingConfig": false
    }
}

POST to onboard a BIG-IP VE in Azure

To transmit a DO declaration in an Azure cloud environment, you can send the POST request to the declarative-onboarding endpoint on the BIG-IQ with the declaration in the body. For more information about Declaration Onboarding in an Azure environment, refer to Adding and Configuring BIG-IP VE Devices in an Azure Cloud .

On the BIG-IQ, your POST can look similar to the following example.

POST https://192.0.2.242/mgmt/shared/declarative-onboarding

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

{
    "class": "DO",
    "declaration": {
            "schemaVersion": "1.5.0",
            "class": "Device",
            "async": true,
            "Common": {
                    "class": "Tenant",
                    "myLicense": {
                            "class": "License",
                            "licenseType": "regKey",
                            "regKey": "xxx-xxx-xxx-xx"
                    },
                    "myProvision": {
                            "class": "Provision",
                            "ltm": "nominal"
                    },
                    "myNtp": {
                            "class": "NTP",
                            "servers": [
                                    "time.nist.gov"
                            ],
                            "timezone": "UTC"
                    },
                    "admin": {
                            "class": "User",
                            "userType": "regular",
                            "partitionAccess": {
                                    "all-partitions": {
                                            "role": "admin"
                                    }
                            },
                            "shell": "tmsh",
                            "password": "adminpassword"
                    },
                    "root": {
                            "class": "User",
                            "userType": "root",
                            "newPassword": "rootpassword",
                            "oldPassword": "adminpassword"
                    }
            }
    },
    "targetHost": "54.10.10.10",
    "targetUsername": "admin",
    "targetPassphrase": "admin",
    "bigIqSettings": {
            "failImportOnConflict": false,
            "conflictPolicy": "USE_BIGIQ",
            "deviceConflictPolicy": "USE_BIGIP",
            "versionedConflictPolicy": "KEEP_VERSION",
            "statsConfig": {
                    "enabled": true,
                    "zone": "default"
            },
            "snapshotWorkingConfig": false
    }
}

POST to onboard a BIG-IP VE in VMware cloud environment

To post a DO declaration in a VMware cloud environment, you can send the POST request to the declarative-onboarding endpoint on the BIG-IQ with the declaration in the body. For more information about Declaration Onboarding in an VMware environment, refer to Adding and Configuring BIG-IP VE Devices in a VMware Environment .

On the BIG-IQ, your POST can look similar to the following example.

POST https://192.0.2.242/mgmt/shared/declarative-onboarding

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

{
    "class": "DO",
    "declaration": {
            "schemaVersion": "1.5.0",
            "class": "Device",
            "async": true,
            "Common": {
                    "class": "Tenant",
                    "myLicense": {
                            "class": "License",
                            "licenseType": "regKey",
                            "regKey": "xxx-xx-xx-xxx"
                    },
                    "myProvision": {
                            "class": "Provision",
                            "ltm": "nominal"
                    },
                    "myNtp": {
                            "class": "NTP",
                            "servers": [
                                    "ntp1.ntp.com"
                            ]
                    },
                    "hostname": "mybigip_no3.mycompany.domain.com"
            }
    },
    "targetHost": "10.10.75.23",
    "targetUsername": "admin",
    "targetPassphrase": "Password",
    "bigIqSettings": {
            "failImportOnConflict": false,
            "conflictPolicy": "USE_BIGIQ",
            "deviceConflictPolicy": "USE_BIGIP",
            "versionedConflictPolicy": "KEEP_VERSION"
    }
}

GET to get information about DO declaration

You can send a GET to the selflink uri returned in the body of the POST response to get the result of a specific DO task.

GET /mgmt/shared/declarative-onboarding/task/<id>