Prerequisites and Requirements

The following are prerequisites for using F5 BIG-IP Declarative Onboarding:

  • BIG-IP Declarative Onboarding does not function properly when the BIG-IP has Appliance mode enabled. We strongly recommend disabling Appliance mode when using BIG-IP DO.

  • Domain name resolution is used anywhere the declaration accepts a hostname. BIG-IP DO makes sure that any hostnames are resolvable and fails if they are not. The exception is deviceGroup.members, which do not require hostname resolution as they have been added to the trust.

  • You must have an existing BIG-IP device with a management IP address.

  • The BIG-IP must be running version 13.1 or later.

  • BIG-IP Declarative Onboarding is not intended to work on BIG-IP versions that have reached End of Life. See here for more information about BIG-IP versions supported by F5.


    Due to changes in TMOS v13.1.1.5 and v13.1.3.x, the BIG-IP Declarative Onboarding (BIG-IP DO) Extension is not compatible with this specific TMOS version. Versions before and after are compatible.

  • You must have an existing user account with the Administrator role. If you are using 13.1.x, the BIG-IP contains an admin user by default. If you are using 14.x, you must reset the admin password before installing BIG-IP Declarative Onboarding. See If using BIG-IP 14.0 or later for instructions.

  • While Declarative onboarding is supported on F5 vCMP systems, network stitching to vCMP Guests or Hosts is not supported. Furthermore, creating vCMP guests with a BIG-IP DO declaration is not supported.

  • If you are using an F5 BYOL license, you must have a valid F5 Networks License Registration Key to include in your declaration. If you do not have one, contact your F5 sales representative. If you do not use a valid F5 license key, your declaration will fail. This is not a requirement if you are using a BIG-IP with pay-as-you-go licensing.

  • If you are using a single NIC BIG-IP system, you must include port 8443 after the IP address of the BIG-IP in your POST and GET requests, such as https://<BIG-IP>:8443/mgmt/shared/declarative-onboarding

  • You should be familiar with the F5 BIG-IP and F5 terminology. The settings and features BIG-IP Declarative Onboarding uses are well-documented in the product documentation. For general information and documentation on the BIG-IP system, see the F5 Knowledge Center.

Notes and tips


Beginning with DO 1.35.0, the default value for allowService on a self IP address will be changing from default to none Until then, DO will present a warning in the response whenever DO receives a declaration that creates or modifies a self IP.

  • Beginning with DO 1.34, the task ID is included in the DO log output. BIG-IP DO records error messages in /var/log/restnoded/restnoded.log.

  • Beginning with BIG-IP DO 1.8.0, the BIG-IP DO RPM, Postman collection, and checksum files will no longer be located in the /dist directory in the BIG-IP Declarative Onboarding repository on GitHub. These files can be found on the GitHub Release, as Assets.

  • Archival of community supported container solution


    The community-supported solution for BIG-IP DO running in a Docker container is being archived as of BIG-IP DO 1.16. F5 will no longer provide new versions of BIG-IP DO running in a container.

  • BIG-IP Declarative Onboarding gathers non-identifiable usage data for the purposes of improving the product as outlined in the end user license agreement for BIG-IP. To opt out of data collection, disable BIG-IP system’s phone home feature as described in K15000

  • With the release of BIG-IP Declarative Onboarding 1.2.0, the GitHub repository includes a BIG-IP Declarative Onboarding Postman collection with all of the example declarations. For information on importing this collection and using Postman collections, see the Postman documentation.

  • The first time you POST a BIG-IP Declarative Onboarding declaration, the system records the configuration that exists prior to processing the declaration. BIG-IP Declarative Onboarding is meant to initially configure a BIG-IP device. However, if you POST subsequent declarations to the same BIG-IP system, and leave out some of the properties you initially used, the system restores the original properties for those items. Important: No matter what you send in a subsequent declaration, BIG-IP Declarative Onboarding will never unlicense a BIG-IP device, it will never delete a user, and it never break the device trust once it has been established. Thus, while BIG-IP Declarative Onboarding is declarative, it is not idempotent.

  • You can use GET to retrieve a sample declaration. Use GET to https://<BIG-IP>/mgmt/shared/declarative-onboarding/example

  • When you POST a declaration, while the system is processing the declaration, the HTTP connection can be broken, especially when provisioning modules. You can use the property “async”: “true”, in your declaration, and then use GET to poll for status.

  • If you POST a declaration that modifies the password for the admin account, even if the declaration returns an error, the password can be changed. Therefore you may need to update the admin password in the client you are using to send the declaration.

  • After using BIG-IP Declarative Onboarding, if you want to use a declarative model to configure applications and services on a BIG-IP device, see the Application Services 3 (AS3) documentation.