Configure Cloud Failover Extension¶

Once the Package is installed, you will use the REST endpoints to configure the Cloud Failover Extension.

Using a RESTful API client, send a GET request to the URI https://{{host}}/mgmt/shared/cloud-failover/info to ensure Cloud Failover Extension is installed and running.

For illustration purposes, the examples below use curl on the BIG-IP itself and the utililty jq to pretty print the JSON output:
```
[admin@bigip-A:Active:In Sync] config # curl -su admin: -X GET http://localhost:8100/mgmt/shared/cloud-failover/info | jq .
{
   "version": "1.2.3",
   "release": "0",
   "schemaCurrent": "1.2.3",
   "schemaMinimum": "1.2.3"
}
```
Copy one of the example declarations from the individual cloud provider sections or one of the Example Declarations which best matches the desired configuration. See each provider section for additional details and requirements.
Paste or copy the declaration into your API client, and modify any names, addresses, routes, or properties as applicable. If the configuration requires tags, the key and value pair in the configuration can be arbitrary but they must match the tags or labels that you assign to the infrastructure within the cloud provider. You can craft your declaration with any key and value pair as long as it matches what is in the configuration. For example:
```
"failoverAddresses": {
   "scopingTags": {
      "i_am_an_arbitrary_key": "i_am_an_arbitrary_value"
   }
```
POST to the URI https://<BIG-IP>/mgmt/shared/cloud-failover/declare.

Below is an example where cfe.json is the name of the file that has been uploaded or edited locally to contain the contents of your CFE declaration.
```
[admin@bigip-A:Active:In Sync] config # vim cfe.json
[admin@bigip-A:Active:In Sync] config # curl -su admin: -X POST -d @cfe.json http://localhost:8100/mgmt/shared/cloud-failover/declare | jq .
[admin@bigip-B:Standby:In Sync] config # curl -su admin: -X POST -d @cfe.json http://localhost:8100/mgmt/shared/cloud-failover/declare | jq .
```
You should receive an expected response of success after you have posted this declaration. For example:
```
{
  "message": "success",
      "declaration": {
          "class": "Cloud_Failover",
  ...
  <output shortened for illustration purposes>
  ...
}
```
Important

You must POST the initial configuration to each device at least once for the appropriate system hook configuration to enable failover via CFE. After that, additional configuration operations can be sent to a single device.
Validate.
- See the Validation section below.
- Review the logs: tail –f /var/log/restnoded/restnoded.log.

Validation¶

On any initial configuration or re-configuration, F5 recommends that you validate Cloud Failover Extension’s configuration to confirm it can properly communicate with the cloud environment and what actions will be performed.

On the Standby instance:

Inspect the configuration to confirm all the BIG-IPs interfaces have been identified.

Use the /inspect endpoint to list associated cloud objects.

For example:
```
curl -su admin: http://localhost:8100/mgmt/shared/cloud-failover/inspect | jq .
```
Peform a Dry-Run of the Failover to confirm what addresses or routes have been identified and will be remapped.

Use the /trigger endpoint with '{"action":"dry-run"}' payload.

For example:
```
curl -su admin: -X POST -d '{"action":"dry-run"}' http://localhost:8100/mgmt/shared/cloud-failover/trigger | jq .
```

If you run into any issues or errors, see the Troubleshooting section for more details.

Components of the Declaration¶

This section provides more information about the options in a Cloud Failover configuration, and breaks down the example declaration into each class so you can understand the options when composing your declaration. The tables below the code snippets contain descriptions and options for the properties. If there is a default value, it is shown in bold in the Options column.

Important

Beginning with version v1.7.0, there are two options for configuring CFE. At a high level, they include:
- Discovery via Tags: This involves discovering external cloud resources to manage by a set of tags (a deployment scoping tag and/or a configuration related tag) on the resources. This requires minimal configuration on the BIG-IP side and dynamically discovers external resources to manage.
- Explicit Configuration: This involves defining external resources to manage by name, address, etc. in the CFE configuration itself. This requires additional configuration on the BIG-IP side but facilitates advanced configurations and some automation workflows. Although Cloud Failover no longer requires tags on external resources, it may still require them on its own NICs or instance in some environments. See the AWS, Azure, and Google Cloud sections for more details.

Base components¶

The first few lines of your declaration are a part of the base components and are required.

First, you define the environment in which Cloud Failover will be running.

{
    "class": "Cloud_Failover",
    "environment": "aws",

Property	Options	Description/Notes
class	Cloud_Failover	Top-level Cloud Failover class. Do not change this value.
environment	aws, azure, gcp	Provide the cloud environment you are using. See the AWS, Azure, and Google Cloud sections for more details.

Next, you define the external storage Cloud Failover will use for its state file.

Discovery via Tag example:

"externalStorage": {
   "scopingTags": {
      "f5_cloud_failover_label": "mydeployment"
   }
},

Explicit Configuration example:

"externalStorage":{
   "scopingName": "CloudFailoverBucket"
},

Property	Options	Description/Notes
externalStorage		Provide scopingTags or scopingName object to define Cloud Failover’s storage. See the AWS, Azure, and Google Cloud sections for more details of what storage objects are used.
scopingTags		Provide the key/value pair that match the cloud tags you assigned to the external storage in your cloud environment.
scopingName		Provide the name of external storage in your cloud environment.

Note

When you POST a declaration, depending on the complexity of your declaration and the modules you are provisioning, it may take some time before the system returns a success message.

The following base components are optional.

Logging¶

Cloud Failover Extension logs to /var/log/restnoded/restnoded.log. The logging level is set in the controls class with possible values of silly, verbose, debug, info, warning, and error.

"controls": {
   "class": "Controls",
   "logLevel": "info"
}

Property	Options	Description/Notes
controls		Provide various controls options.
class	Controls	Controls class. Do not change this value.
logLevel	silly, verbose, debug, info, warning, error	Provide the logging level to use. The default value is info although “silly” is highly recommended for first use, troubleshooting, and debugging.

See Logging for more details and example output levels.

Retry Failover Interval¶

This feature is optional and, as part of floating object mapping validation, allows you to trigger failover periodically at an interval of your choosing.

"retryFailover": {
   "enabled": true,
   "interval": 2
}

Property	Options	Description/Notes
retryFailover		Provide retry options.
enabled	true, false	Specify if retrying failover is enabled. The default value is false
interval		Provide the failover retry interval. The interval unit is in minutes.

Failover Addresses¶

The next lines of the declaration set the address failover functionality.

"failoverAddresses": {
    "enabled": true,

Property	Options	Description/Notes
failoverAddresses		Provide address failover configurations.
enabled	true, false	Enables or disables the address failover functionality.

Discovery via Tag example:

"failoverAddresses": {
   "enabled": true,
   "scopingTags": {
      "f5_cloud_failover_label": "mydeployment"
   }
},

Explicit Configuration example:

"failoverAddresses":{
   "enabled":true,
   "scopingTags": {
      "f5_cloud_failover_label": "mydeployment"
   }
   "addressGroupDefinitions": [
      {
         "type": "networkInterfaceAddress",
         "scopingAddress": "10.0.1.100"
      },
      {
         "type": "networkInterfaceAddress",
         "scopingAddress": "10.0.1.101"
      }
   ]
},

Property	Options	Description/Notes
scopingTags		Provide a key/value pair that you have assigned to the resources in your cloud environment. This serves as the general “deployment” scoping tag. This property is required for AWS configurations. See the AWS, Azure, and Google Cloud sections for more details on required additional tags.
addressGroupDefinitions		Provide address objects to failover. If you use this, you do not need to tag external address resources. See the AWS, Azure, and Google Cloud sections for more details of address types.

Important

In AWS, the scopingTags property is required in all configurations (for example, even when failoverAddresses is disabled and only failing over routes) as it is leveraged internally to map the peer BIG-IP’s NICs.

"failoverAddresses":{
    "scopingTags": {
        "f5_cloud_failover_label": "mydeployment"
    }

Failover Routes¶

The next lines of the declaration set the route failover functionality.

"failoverRoutes": {
   "enabled": true,

Property	Options	Description/Notes
failoverRoutes		Provide route failover configurations.
enabled	true, false	Enables or disables the route failover functionality. If the failoverAddresses section is provided, the default is true.

Discovery via Tag example:

"failoverRoutes": {
   "enabled": true,
   "scopingTags": {
     "f5_cloud_failover_label": "mydeployment"
     },
     "scopingAddressRanges": [
        {
           "range": "192.168.1.0/24"
        },
        {
           "range": "192.168.1.1/24"
        }
     ],
     "defaultNextHopAddresses": {
        "discoveryType": "routetag"
     }
  }

Explicit Configuration example:

"failoverRoutes": {
   "enabled": true,
   "routeGroupDefinitions": [
      {
         "scopingName": "rtb-11111111111111111",
         "scopingAddressRanges": [
            {
               "range": "192.168.1.0/24",
            },
            {
               "range": "192.168.1.1/24"
            }
         ],
         "defaultNextHopAddresses": {
            "discoveryType": "static",
            "items": [
               "192.0.2.10",
               "192.0.2.11"
            ]
         }
      }
   ]
}

The property routeGroupDefinitions provides more granular per-route table operations (F5 recommends using this option going forward). In the example above, scopingName is used to specify the exact route table to operate on and static in defaultNextHopAddresses to specify the nexthop Self-IP mappings.

Property	Options	Description/Notes
scopingTags		Provide a key/value pair used to discover route tables to perform updates on. The route table(s) are required to have this tag regardless of the `discoveryType` method used for the `nextHopAddresses` (or self IP mappings). NOTE: Although it can be used for simple deployments, the scope of this tag in the first example is global to the cluster/deployment and may discover multiple route tables. If you have routes that you specificially want to update in one table vs. another table (ex. 0.0.0.0 for an internal routing table and not on an external routing table), use the `routeGroupDefinitions` option.
scopingAddressRanges		A list of destination routes (prefixes) to update in the event of failover.
defaultNextHopAddresses		This is the default list of BIG-IP’s Self IPs to point the routes (prefixes) to for any routes listed in `scopingAddressRanges` that do not have a more specific set of `nextHopAddresses` defined. See Multiple Next Hop addresses for an example declaration for multiple routing tables pointing to different nexthops.
discoveryType	static, routeTag	In cases where BIG-IP has multiple NICs, CFE needs to know which interfaces it needs to re-map the routes to. It does this by using the Self IPs associated with those NICs. You can either define the Self IPs statically in the configuration OR in an additional cloud tag on the route table and have CFE discover them via tag. If you use `static`, you will need to provide the Self-IPs in the `items` area of the CFE configuration. If you use `routeTag`, you will need to add another tag to the route table in your cloud environment with the reserved key `f5_self_ips`. For example, `f5_self_ips:192.0.2.10,192.0.2.11`. See Route Failover Using Route Tags for an example configuration.
items		List the Self IP address of each instance to route traffic to. This is only required when discoveryType is `static`.
routeGroupDefinitions		List of route tables or route groups to update in the event of failover. This feature is available in CFE v1.5.0+ to support advanced routing scenarios. In AWS and Azure, `routeGroupDefintions` translates to route tables. GCP does not have route tables so it translates to groups or collections of routes. This option is intended for use in shared services and/or sandwich architectures with multiple BIG-IP clusters (which may share networks) and require per-route table granularity. For example, if you have routes that you specificially want update in one table vs. another (ex. 0.0.0.0 for only the internal routing table and not on the external routing table). See Advanced Routing: Multiple Route Tables, Routes, Nexthops and Subscriptions for example declarations.
scopingName		String containing the name or ID of routing table to update. If you use this, you do not need to tag the route tables. See Advanced Routing: Multiple Route Tables, Routes, Nexthops and Subscriptions for example declarations.

Endpoints¶

declare: user this endpoint to configure CFE
info: use this endpoint to get information on CFE, such as the version number.
inspect: use this endpoint to list associated cloud objects.
reset: use this endpoint to reset the failover state file.
trigger: use this endpoint to trigger failover.

For more information see the API Reference.

Using a Proxy¶

This extension supports making API calls through a proxy server for most cloud providers. It looks at the BIG-IP proxy configuration defined in system db variables. These can be viewed by running tmsh list sys db proxy.

AWS: All API calls will use the proxy.
Azure: All control plane API calls will use the proxy. Storage upload/download (data-plane) calls will not use the proxy.
GCP: No API calls will use the proxy. Please open an issue if this is required in your environment.

Configuring BIG-IP proxy configuration:

modify sys db proxy.host value 192.0.2.10
modify sys db proxy.port value 3128
modify sys db proxy.username value proxyuser
modify sys db proxy.password value apassword
modify sys db proxy.protocol value https

Cloud Environments¶

Choose the cloud environment you are working in to continue implementing CFE:

Note

To provide feedback on Cloud Failover Extension or this documentation, you can file a GitHub Issue.

Previous Next