Composing a BIG-IP Declarative Onboarding declaration for a cluster of BIG-IPs¶
BIG-IP Declarative Onboarding can also create a clustered configuration (Device Service Cluster) between two or more BIG-IP systems. You must install BIG-IP Declarative Onboarding and submit a declaration on each device in the cluster, and all BIG-IP devices must be on the same BIG-IP version. You specify one BIG-IP system as the ‘owner’ and the other BIG-IPs as ‘members’ (see Device Group class).
BIG-IP clustering is well-documented in the product documentation; for detailed information about clustering on the BIG-IP system, see BIG-IP Device Service Clustering: Administration.
Tip
You can use GET to the URI https://<BIG-IP>/mgmt/shared/declarative-onboarding to track whether a declaration is successful or get information on why it failed.
Additionally, see JSON Pointers for information on using JSON/BIG-IP Declarative Onboarding pointers in your declaration.
Declaration classes for a cluster of BIG-IPs¶
In this example, we include the classes that are specific to clustering. For a complete declaration, you could add the classes shown in Composing a BIG-IP Declarative Onboarding declaration for a standalone BIG-IP to configure DNS, NTP, VLANs, Routes and more. For the full clustering example declaration, see Clustered declaration.
Note
Some classes are only available in certain versions of BIG-IP Declarative Onboarding. See the individual class sections for any version notices.
For some of the clustering components, like ConfigSync and failoverAddress, you can use JSON pointers to reference objects/properties in declarations.
Note
The DeviceTrust and DeviceGroup sections in both declarations should be identical. For DeviceTrust, if the remoteHost matches the management IP or one of the self IPs of the host on which it is running, that DeviceTrust section is ignored. If it does not match, then the device processing the declaration will send a request to the remote host to be added to trust. There is similar logic regarding the DeviceGroup owner. The owning device just creates the group, the other device requests to be added to the group.
The following declaration snippet could continue after the Route class in the standalone BIG-IP example.
1 "configsync": {
2 "class": "ConfigSync",
3 "configsyncIp": "/Common/external-self/address"
4 },
5 "failoverAddress": {
6 "class": "FailoverUnicast",
7 "address": "/Common/external-self/address"
8 },
9 "failoverGroup": {
10 "class": "DeviceGroup",
11 "type": "sync-failover",
12 "members": ["bigip1.example.com", "bigip2.example.com"],
13 "owner": "/Common/failoverGroup/members/0",
14 "autoSync": true,
15 "saveOnAutoSync": false,
16 "networkFailover": true,
17 "fullLoadOnSync": false,
18 "asmSync": false
19 },
20 "trafGroup": {
21 "class": "TrafficGroup",
22 "autoFailbackEnabled": false,
23 "autoFailbackTime": 50,
24 "failoverMethod": "ha-order",
25 "haLoadFactor": 1,
26 "haOrder": [
27 "do.example.com"
28 ]
29 },
30 "trust": {
31 "class": "DeviceTrust",
32 "localUsername": "admin",
33 "localPassword": "pass1word",
34 "remoteHost": "/Common/failoverGroup/members/0",
35 "remoteUsername": "admin",
36 "remotePassword": "pass2word"
37 },
38 "myMirror": {
39 "class": "MirrorIp",
40 "primaryIp": "10.1.0.20",
41 "secondaryIp": "any6"
42 }
Components of the declaration¶
The following sections break down the example into parts so you can understand the options and how to compose a declaration. The tables below the examples contains descriptions and options for the parameters included in the example only.
If there is a default value, it is shown in bold in the Options column.
Use the index in the left pane if you want to go directly to a particular section.
Tip
There may be additional properties available in some of the classes. Be sure to see the schema-reference and Example Declarations for detailed information on each class and their associated properties.
Configsync class¶
The first class specific to clustering is the configsync class. This class contains the properties responsible for propagating BIG-IP configuration changes, including device trust information, to all devices in a device group. For more information on configsync on the BIG-IP, see Configsync documentation. Because this example assumes we are using this class together with the standalone declaration, we can use a JSON pointer to the self IP address we defined.
Note
As of BIG-IP DO 1.7.0, none is a valid value for configsyncIP.
1 "configsync": {
2 "class": "ConfigSync",
3 "configsyncIp": "/Common/external-self/address"
4 },
Parameter |
Options |
Required*? |
Description/Notes |
|---|---|---|---|
class |
ConfigSync |
Yes |
Indicates that this property contains config sync IP configuration |
configsyncIp |
string (IPv4/IPv6 address or JSON pointer) |
Yes |
This is the IP address on the local device that other devices in the device group will use to synchronize their configuration objects to the local device. |
* The required column applies only if you are using this class.
Failover Unicast class¶
The next class specific to clustering is the failover unicast class. The unicast self IP address you specify is the main address that other devices in the device group use to communicate continually with the local device to assess the health of that device. For more information on failover on the BIG-IP, see Failover documentation. Because this example assumes we are using this class together with the standalone declaration, we can use a JSON pointer to the self IP address we defined in that declaration.
1 "failoverAddress": {
2 "class": "FailoverUnicast",
3 "address": "/Common/external-self/address"
4 },
Parameter |
Options |
Required*? |
Description/Notes |
|---|---|---|---|
class |
FailoverUnicast |
Yes |
Indicates that this property contains failover unicast address configuration. |
address |
string (IPv4/IPv6 address or JSON pointer) |
Yes |
This is the local IP address the system uses to listen on for failover heartbeats. |
* The required column applies only if you are using this class.
Device Group class¶
The next class specific to clustering is the device group class. A device group is a collection of BIG-IP devices that trust each other and can synchronize (and fail over if you choose sync-failover), their BIG-IP configuration data. For more information on Device Groups on the BIG-IP, see Device Group documentation. In this example, for the owner parameter, we are using a JSON pointer. The value in the example means that the first object in the members array.
Important: You cannot use autoSync and fullLoadOnSync together.
Note
In BIG-IP Declarative Onboarding v1.11.0 and later, the member and owner parameters can be IP addresses. See Example 17 for an example declaration.
1 "failoverGroup": {
2 "class": "DeviceGroup",
3 "type": "sync-failover",
4 "members": ["bigip1.example.com", "bigip2.example.com"],
5 "owner": "/Common/failoverGroup/members/0",
6 "autoSync": true,
7 "saveOnAutoSync": false,
8 "networkFailover": true,
9 "fullLoadOnSync": false,
10 "asmSync": false
11 },
Parameter |
Options |
Required*? |
Description/Notes |
|---|---|---|---|
class |
DeviceGroup |
Yes |
Indicates that this property contains Device Group configuration. |
type |
sync-failover, sync-only |
Yes |
Specifies the type of device group. With sync-failover, devices synchronize their configuration data and fail over to one another when a device becomes unavailable. With sync-only, devices only synchronize their configuration. |
members |
array of strings |
No |
Members to add to the device group if they are already in the trust domain. In 1.10 and earlier, must be a hostname; in 1.11 and later, can be hostname or IP address. |
owner |
string (hostname, IP address, JSON pointer) |
Yes |
Specifies the owning device. The configuration will be pushed from this device. A device group will only be created if the current device is the owner and the device group does not exist. In DO 1.11+ only, can be IP address |
autoSync |
true, false |
No |
Specifies whether the Device Group should synchronize automatically. Important: You cannot use autoSync and fullLoadOnSync together. |
saveOnAutoSync |
true, false |
No |
Specifies whether the Device Group should save the configuration when it auto synchronizes. |
networkFailover |
true, false |
No |
Specifies whether the Device Group supports network failover. |
fullLoadOnSync |
true, false |
No |
Specifies whether the system synchronizes the entire set of BIG-IP configuration data whenever a config sync operation. Important: You cannot use autoSync and fullLoadOnSync together. |
asmSync |
true, false |
No |
Specifies whether or not the device group should sync ASM properties |
* The required column applies only if you are using this class.
Traffic Group class¶
The next class specific to clustering is the traffic group class. A traffic group is a collection of related configuration objects (such as a virtual IP address and a self IP address) that run on a BIG-IP and process a particular type of application traffic. When a BIG-IP becomes unavailable, a traffic group can float to another device in a device group to ensure that application traffic continues to be processed with little to no interruption in service.
For detailed information about Traffic Groups and clustering on the BIG-IP, see BIG-IP Device Service Clustering: Administration. See Traffic Groups for an example declaration.
Important
The HA Score failover method is not currently supported. BIG-IP DO uses the HA Order failover method.
Because BIG-IP DO uses HA Order for failover, the declaration must include a hostname, located inside of a deviceGroup. In the example, the declaration defines a Device Group with a host name.
1 "trafGroup": {
2 "class": "TrafficGroup",
3 "autoFailbackEnabled": false,
4 "autoFailbackTime": 50,
5 "failoverMethod": "ha-order",
6 "haLoadFactor": 1,
7 "haOrder": [
8 "do.example.com"
9 ]
10 },
Parameter |
Options |
Required*? |
Description/Notes |
|---|---|---|---|
class |
TrafficGroup |
Yes |
Indicates that this property contains Traffic Group configuration. |
autoFailbackEnabled |
true, false |
No |
Specifies whether the traffic group fails back to the default device. |
autoFailbackTime |
integer |
No |
Specifies the time required to fail back. |
failoverMethod |
ha-order |
No |
Specifies the method to failover the traffic-group to another device. Currently only ha-order is supported, where a list of devices and their respective HA load is used to decide the next one to take over if the current devices fails. |
haLoadFactor |
integer |
No |
Specifies a number for this traffic group that represents the load this traffic group presents to the system relative to other traffic groups. This allows the failover daemon to load balance the active traffic groups amongst the devices. |
haOrder |
array |
No |
List of devices that specifies the order in which the devices will become active for the traffic group when a failure occurs. May contain from zero up to the number of devices in the failover device group. |
* The required column applies only if you are using this class.
Device Trust class¶
The next class specific to clustering is the device trust class. Device trust establishes trust relationships between BIG-IP devices on the network, through mutual certificate-based authentication. For more information on Device Trust on the BIG-IP, see Device Trust documentation.
1 "trust": {
2 "class": "DeviceTrust",
3 "localUsername": "admin",
4 "localPassword": "pass1word",
5 "remoteHost": "/Common/failoverGroup/members/0",
6 "remoteUsername": "admin",
7 "remotePassword": "pass2word"
8 }
Parameter |
Options |
Required? |
Description/Notes |
|---|---|---|---|
class |
DeviceTrust |
Yes |
Indicates that this property contains Device Trust configuration. |
localUsername |
string |
Yes |
The username for the local device. |
localPassword |
string |
No |
The password for the local device. |
remoteHost |
string (IPv4/IPv6, hostname, JSON pointer) |
No |
The remote hostname or IP address. If the remoteHost is the current device, this has no affect. Otherwise, the current device will request the remote host to add the current device to its trust domain and synchronize to it. |
remoteUsername |
string |
No |
The username for the remote device |
remotePassword |
string |
No |
The password for the remote device. |
* The required column applies only if you are using this class.
MirrorIp class¶
The next class specific to clustering is the MirrorIP class, introduced in BIG-IP DO v1.16. The MirrorIP class allows you to configure connection and persistence mirroring information in a BIG-IP Declarative Onboarding declaration. This allows you to configure clustered BIG-IPs to duplicate connection and persistence information to peer members of the BIG-IP device group, providing higher reliability but may affect system performance.
For more information and BIG-IP DO usage, see MirrorIp. See Configuring connection and persistence mirroring for an example declaration.
1 "myMirror": {
2 "class": "MirrorIp",
3 "primaryIp": "10.1.0.20",
4 "secondaryIp": "any6"
5 }
Parameter |
Options |
Required*? |
Description/Notes |
|---|---|---|---|
class |
MirrorIp |
Yes |
Indicates that this property contains connection and persistence mirroring information. |
primaryIp |
string |
No |
IP address of the primary mirror. Specify any6 to disable (the default is any6). |
secondaryIp |
string |
No |
IP address of the secondary mirror. Specify any6 to disable (the default is any6). |
* The required column applies only if you are using this class.