Configure Cloud Failover Extension

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

  1. Using a RESTful API client like Postman, send a GET request to the URI https://{{host}}/mgmt/shared/cloud-failover/info to ensure Cloud Failover Extension is running properly. You should receive an expect response of success after you have posted this declaration. For example:

    {
        "message": "success"
    }
    
  2. Copy one of the Example Declarations which best matches the configuration you want to use. See each provider section for additional details and requirements.

  3. Paste the declaration into your API client, and modify names and IP addresses as applicable. The key and value pair 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"
            }
    
  4. POST to the URI https://<BIG-IP>/mgmt/shared/cloud-failover/declare

    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.

  5. To stream the output of restnoded, use the tail command: tail –f /var/log/restnoded/restnoded.log


Components of the Declaration

This section provides more information about the options in a Cloudfailover 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 parameters. If there is a default value, it is shown in bold in the Options column.

Base components

The first few lines of your declaration are a part of the base components and define top-level options. 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.

1
2
3
4
5
6
7
8
 {
     "class": "Cloud_Failover",
     "environment": "aws",
     "externalStorage": {
          "scopingTags": {
              "f5_cloud_failover_label": "mydeployment"
         }
     },

Parameter Options Description/Notes
class Cloud_Failover Describes top-level Cloud Failover options. Do not change this value.
environment aws, gcp, azure This value defines which cloud environment you are using. See the AWS, Google Cloud, and Azure sections for more details.
externalStorage
This is a json object. Do not change this value.
scopingTags
These key/value pairs have to be the same as the tags you assign to the external storage in your cloud environment.

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’. This controls object is sent via a POST /declare.

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

Parameter Options Description/Notes
class Controls Describes top-level Controls options. Do not change this value.
logLevel silly, verbose, debug, info, warning, error 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

As part of floating object mapping validation, this feature is added to have the failover trigger periodically on a specify user-defined interval.

1
2
3
4
   "retryFailover": {
      "enabled": true,
      "interval": 2
    }

Parameter Options Description/Notes
retryFailover
This is a json object. Do not change this value.
enabled true, false The default value is false
interval
Interval unit is in minutes.

Failover Addresses

The next lines of the declaration set the failover addresses.

 9
10
11
12
13
14
15
     "failoverAddresses": {
         "enabled": true,
         "scopingTags": {
             "f5_cloud_failover_label": "mydeployment"
         }
     }
   },

Parameter Options Description/Notes
failoverAddresses
This is a json object. Do not change this value.
enabled true, false Enables or disables the failoverAddress functionality.
scopingTags
These key/value pairs have to be the same as the tags you assign to the addresses in your cloud environment.

Failover Routes

The next lines of the declaration set the failover routes. scopingAddressRanges is used to define which routes (prefixes) to update.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
      "failoverRoutes": {
         "enabled": true,
         "scopingTags": {
            "f5_cloud_failover_label": "mydeployment"
         },
         "scopingAddressRanges": [
            {
               "range": "192.168.1.0/24"
            }
         ],
         "defaultNextHopAddresses": {
            "discoveryType": "routetag"
         }
      }

The route failover feature provides various options for determining which routes or route tables to manage, from discovering them via cloud tags to specifying them directly in the configuration itself.

For example, you can add tags to your routes or route table(s) to determine which ones to operate on and which interfaces (or nexthop Self-IP addresses) to point your routes to. Cloud Failover then uses:

  • scopingTags to search for your routes or route table(s). For example, you add a tag "f5_cloud_failover_label": "mydeployment" to any route table(s) you want to manage.
  • "discoveryType": "routeTag" to look for an additional tag which contains which nexthop Self-IP addresses it should point the routes to.

Alternatively, you can explicitly provide the route tables and nexthop self-IP addresses in the configuration. Starting with Release v1.5.0, the parameter routeGroupDefinitions provides more granular per-route table operations (F5 recommends using this option going forward). In the example below, scopingName is used to specify the exact route table to operate on and static in defaultNextHopAddresses to specify the nexthop Self-IP mappings.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
      "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"
                  ]
               }
            }
         ]
      }
   }

Parameter Options Description/Notes
failoverRoutes
This is a json object. Do not change this value.
enabled true,false Enables or disables the route failover functionality.
scopingTags
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 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 json object is the default list of next hop addresses 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 (Released in v1.5.0 to support advanced routing scenarios). NOTE: 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 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

  • Info: use this endpoint to get information on CFE, such as the version number.
  • Reset: use this endpoint to reset the failover state file.
  • Trigger: use this endpoint to trigger failover.

For more information see the API Reference.


Note

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

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