F5 Beacon API

Important Resources

Authenticate against F5 Cloud Service API

To send an API request to any F5 Cloud Service API, a bearer token must be obtained, see API overviews and example for additional detail.

Specify preferred account header in a multiple accounts/divisions scenario

A user can be associated with multiple accounts or have configured divisions. In these scenarios, to disambiguate the account information, a header named X-F5aaS-Preferred-Account-Id needs to be added with the account ID value.

Account membership information is available via the following APIs.

Retrieve the user ID and primary account ID via:

GET https://api.cloudservices.f5.com/v1/svc-account/user
{
    "id": "u-aaPgo44WXX",
    "email": "user@f5.com",
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+1 (555) 111-1111",
    "primary_account_id": "a-aaT6XYZa9j",
    ...

Retrieve account memberships via:

GET https://api.cloudservices.f5.com/v1/svc-account/users/<USER_ID>/memberships
{
    "memberships": [
        {
            "account_id": "a-aaSXXdAYYY2",
            "account_name": "NW - Zone",
            "role_name": "privileged-user",
            ...

        },
        {
            "account_id": "a-aahXYZLa7H",
            "account_name": "f5",
            "role_name": "privileged-user",
            ...
        },
        {
            "account_id": "a-ahhhZMXXJU",
            "account_name": "HR",
            "role_name": "owner",
            ...
        },
        {
            "account_id": "a-aaT6XYZa9j",
            "account_name": "F5 Networks",
            "role_name": "owner",
            ...
        }
    ]
}

Note

It is recommended to always set the preferred account header to make any future transition to a multiple accounts/divisions scenario easier.

Beacon Declare API

By using the Declare API, you can add and modify, or remove multiple applications and monitors with a single call.

The Declare API path is <https://api.cloudservices.f5.com/beacon/v1/declare>, where you can POST a declaration of your applications and monitors.

Sample Declare API request:

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "deploy",
    "declaration": [{
            "metadata": {
                "version": "v1"
            },
            "application": {
                "name": "AccountingApp",
                "description": "An accounting application",
                "labels": {
                    "department": "Accounting",
                    "location": "Azure"
                },
                "metrics": [
                    {
                        "measurement": "bigip-virtual",
                        "tags": {
                            "name": "virtualServerName",
                            "source": "big-ip1.f5.com"
                        }
                    }
                ]
            }
        }
    ]
}

Declare has two fields:

  • action - the type of operation to apply, with valid values of “deploy” (the default), “get”, “dry-run”, and “remove”
  • declaration - an array of configuration resources

Each declaration resource contains metadata with the following:

  • version - the API version to use to create the resource

Deploy action - Creating and updating resources

The “deploy” action is used to create resources. This action is asynchronous – the response includes a task ID (taskReference) that you can query (GET) get task progress and confirm success or failure.

When the declaration includes existing resources, the “deploy” action will update the resources.

Snippet of a Declare API response showing taskReference:

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "deploy",
    "declaration": [
        {
            "metadata": {
                "Version": "v1",
                "Operation": ""
            },
            "application": {
                "name": "API-Demo-App-5",
                "description": "An example for a Beacon application",
                ...
            }
        }
    ],
    "taskReference": "https://api.cloudservices.f5.com/beacon/v1/declare-task/1234"
}

Get action - Viewing existing resources

The “get” action is used to view existing resources. It returns the full set of configured applications and monitors.

Get action - View resources:

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "get"
}

Remove action - Deleting resources

The “remove” action is used to explicitly delete resources. Resources not included in the declaration using the “remove” action are not impacted.

Full resource definitions are allowed in the declaration when using the “remove” action, though you can also include only the resource name.

Remove action - Delete resources:

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "remove",
    "declaration": [
        {
            "application": {
                "name": "AccountingApp"
            }
        },
        {
            "application": {
                "name": "FinanceApp"
            }
        }
    ]
}

Dry-run action - Validate resources

The “dry-run” action validates the supplied resources and responds with the operation (“add” or “update”) that will occur if a subsequent “deploy” action occurs.

Declare API “dry-run” reply

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "dry-run",
    "declaration": [{
            "metadata": {
                "version": "v1",
                "operation": "update"
            },
            "application": {
                "name": "AccountingApp"
            }
        },
        {
            "metadata": {
                "version": "v1",
                "operation": "add"
            },
            "application": {
                "name": "MarketingApp"
            }
        }
    ]
}

Application Health Metrics

The application health metric defines the component health status. There are two types of application health metrics.

Health metric - Generic Metrics that are sent to Beacon. The “healthSettings” configure how to translate the metric value into component health status.

Health Metrics:

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "deploy",
    "declaration": [{
        "metadata": {
            "Version": "v1"
        },
        "application": {
            "name": "API-Demo-App",
            "description": "An example for a Beacon application",
            "metrics": [{
                "measurement": "Server",
                "tags": {
                    "URL": "server1.example.com"
                },
                "field": "CPU",
                "healthSettings": {
                    "aggregation": "Mean",
                    "timeRange": 1,
                    "operator": "GreaterThan",
                    "criticalThreshold": "80",
                    "warningThreshold": "60",
                    "noMetricData": "KeepState"
                }
            }]
        }
    }]
}

The “healthSetting” fields are:

  • timeRange - time range, in minutes, used to evaluated metric value
  • aggregation - function to apply the metric points in the time range. Valid values are ‘Mean’, ‘Median’, ‘Count’, ‘Sum’, ‘Min’ and ‘Max’
  • operator - Comparison operation used between the metric aggregation value and the threshold. The metric value is used as the first operand. Valid values are ‘Equal’, ‘GreaterThan’, ‘GreaterThanOrEqual’, ‘LessThan’ and ‘LessThanOrEqual’
  • criticalThreshold - Critical threshold value
  • warningThreshold - Warning threshold value
  • noMetricData - Define how to handle cases where no metric data is available. Valid values are ‘SetHealthy’, ‘SetWarning’, ‘SetCritical’, ‘SetNone’ and ‘SetDisable’

Built-In Health Metrics - There are a handful of measurements that have a “healthStatus” field. In these cases, health can be mapped without specifying the field or a “healthSettings” configuration object.

The applicable measurements are:

  • beacon-health-source
  • bigip-virtual
  • bigiq-app
  • bigiq-app-svc
  • dns-monitor
  • monitor
  • uptime-robot

Built-In Health Metrics:

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "deploy",
    "declaration": [{
        "metadata": {
            "Version": "v1"
        },
        "application": {
            "name": "API-Demo-App",
            "description": "An example for a Beacon application",
            "metrics": [{
                "measurement": "bigip-virtual",
                "tags": {
                    "name": "virtualServerName",
                    "source": "big-ip1.f5.com"
                }
            }]
        }
    }]
}

Component Health Roll Up

Health roll-up for metrics or components is configured in the “healthSourceSettings” object with two fields:

  • metricsHealthAggregation - roll-up health status between multiple health metrics that are configured on a single component. Valid values are ‘WorstOf’ and ‘BestOf’
  • dependencyHealthAggregation - roll-up health status between a component and its dependencies health status values components. Valid values are ‘WorstOf’ and ‘BestOf’

The “healthSourceSettings” can be configured on any app component and impact that component and its dependencies.

Application with Health Source Settings Aggregation fields:

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "deploy",
    "declaration": [{
        "metadata": {
            "Version": "v1"
        },
        "application": {
            "name": "API-Demo-App",
            "description": "An example for a Beacon application",
            "healthSourceSettings": {
                "metricsHealthAggregation": "WorstOf",
                "dependencyHealthAggregation": "BestOf"
            },
            "metrics": [{
                    "measurement": "LoadBalancer",
                    "tags": {
                        "URL": "lb1.example.com"
                    },
                    "field": "Latency",
                    "healthSettings": {
                        "aggregation": "Mean",
                        "timeRange": 1,
                        "operator": "GreaterThan",
                        "criticalThreshold": "500",
                        "warningThreshold": "250",
                        "noMetricData": "KeepState"
                    }
                },
                {
                    "measurement": "LoadBalancer",
                    "tags": {
                        "URL": "lb1.example.com"
                    },
                    "field": "Connections",
                    "healthSettings": {
                        "aggregation": "Mean",
                        "timeRange": 1,
                        "operator": "LessThan",
                        "criticalThreshold": "5",
                        "warningThreshold": "20",
                        "noMetricData": "KeepState"
                    }
                }
            ],
            "dependencies": [{
                    "name": "API-Demo-Server1",
                    "metrics": [{
                        "measurement": "Server",
                        "tags": {
                            "URL": "server1.example.com"
                        },
                        "field": "CPU",
                        "healthSettings": {
                            "aggregation": "Mean",
                            "timeRange": 1,
                            "operator": "GreaterThan",
                            "criticalThreshold": "80",
                            "warningThreshold": "60",
                            "noMetricData": "KeepState"
                        }
                    }]
                },
                {
                    "name": "API-Demo-Server2",
                    "metrics": [{
                        "measurement": "Server",
                        "tags": {
                            "URL": "server2.example.com"
                        },
                        "field": "CPU",
                        "healthSettings": {
                            "aggregation": "Mean",
                            "timeRange": 1,
                            "operator": "GreaterThan",
                            "criticalThreshold": "80",
                            "warningThreshold": "60",
                            "noMetricData": "KeepState"
                        }
                    }]
                }
            ]
        }
    }]
}

HTTP monitor example

The following sample declaration creates an HTTP monitor to check for availability of the https://www.example.com endpoint every 30 seconds using an HTTP GET method.

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "deploy",
    "declaration": [
        {
            "metadata": {
                "Version": "v1"
            },
            "monitor": {
                "name": "Example Synthetic Monitor",
                "description": "example.com",
                "url": "https://www.example.com/",
                "method": "GET",
                "interval": 30,
                "type": "MONITOR_TYPE_HEALTH_CHECK",
                "transformUrl": "",
                "requestHeaders": "",
                "transformHeaders": ""
            }
        }
    ]
}

DNS monitor example

The following sample declaration creates a DNS monitor to check the A record of example.com every 30 seconds.

POST https://api.cloudservices.f5.com/beacon/v1/declare
{
    "action": "deploy",
    "declaration": [
        {
            "metadata": {
                "Version": "v1"
            },
            "dnsMonitor": {
                "name": "Example DNS Monitor",
                "description": "example.com",
                "interval": 30,
                "domain": "example.com",
                "recordType": "A",
                "protocol": "UDP",
                "onFailureTo": "ANY",
                "onFailureCount": 3
            }
        }
    ]
}