Using Service Discovery with AS3

AS3 v3.3.0 introduced the ability to use F5’s service discovery feature for Amazon Web Services (AWS) and Google Cloud Platform. AS3 v3.4.0 adds service discovery for Microsoft Azure. Service discovery enables the BIG-IP system to automatically update members in a load balancing pool based on cloud application hosts. You simply tag your cloud resources with key and value information, and then in the declaration you POST information about your cloud environment, including the cloud tag key and tag value you specified, and the BIG-IP VE programmatically discovers members with those tags (and removes pool members if they do not have the tags).

AS3 v3.4.0 also introduces the ability to have your BIG-IP located anywhere when using service discovery; it does not have to be in a specific location or cloud.

Important: If you are using service discovery, we strongly recommend you use AS3 v3.4.0, which removes the limitations that were present in v3.3.0.

Requirements for using Service Discovery

To use service discovery with AS3, you must:

  • Have installed AS3 v3.3.0 or later. We strongly recommend using AS3 v3.4.0 or later.
  • Important: You must be using BIG-IP version 13.0 or later to use service discovery.
  • Have properly tagged resources in your cloud environment. See your cloud provider documentation for instructions on tagging resources. Important: Make sure the tags and IP addresses you use are unique. You should not tag multiple nodes with the same key/tag combination if those nodes use the same IP address.
    • In AWS, you can tag a VM resource or tag a NIC resource. The system first looks for NIC resources with the tags you specify. If it finds NICs with the proper tags, it does not look for VM resources. If it does not find NIC resources, it looks for VM resources with the proper tags. If you tag a VM resource, the BIG-IP will discover the primary public or private IP address for the primary NIC configured for the tagged VM. If you tag a NIC resource, the BIG-IP will discover the public or private IP address for the tagged NIC. You should use this option if you want to use the secondary NIC of a VM in the pool.
    • In Google, you tag objects using the labels parameter within the virtual machine. The BIG-IP VE will discover the primary public or private IP addresses for the primary NIC configured for the tagged VM.
    • In Azure, you can tag a VM resource, a NIC resource, or a Virtual Machine Scale Set resource. The system first looks for NIC resources with the tags you specify. If it finds NICs with the proper tags, it does not look for VM resources. If it does not find NIC resources, it looks for VM resources with the proper tags. In either case, it then looks for Scale Set resources with the proper tags. If you tag a VM resource, the BIG-IP VE will discover the primary public or private IP addresses for the primary NIC configured for the tagged VM. If you tag a NIC resource, the BIG-IP VE will discover the primary public or private IP addresses for the tagged NIC. Use this option if you want to use the secondary NIC of a VM in the pool. If you tag a Virtual Machine Scale Set resource, the BIG-IP VE will discover the primary private IP address for the primary NIC configured for each Scale Set instance. Note you must select Private IP addresses in AS3 if you are tagging a Scale Set.
  • Include the service discovery lines in the pool member section of your declaration as described in the following section.

Note

Your cloud resources will not appear in the results of an AS3 GET request, but they are visible in the BIG-IP UI.

There are two scenarios in which you can use service discovery:

  • If your BIG-IP VE resides in your cloud provider in the same region as the resources you want to discover (the following example).
  • Using remote service discovery, where your BIG-IP VE can be anywhere.

Including service discovery in your declaration (BIG-IP VE in the cloud provider and same region as the resources)

To include service discovery in your declaration, you add specific parameters to the pool members section of your declaration. See the following snippet from a declaration.

NOTE: This example is for AWS and Google. For Azure, the declaration is the same whether the BIG-IP VE is located in Azure or elsewhere (see see Using remote service discovery).

In this example, the BIG-IP VE MUST be located in the cloud provider, and MUST be in the same region as the BIG-IP VE for AWS and Google. To use remote service discovery where the BIG-IP VE is located in a different location, see Using remote service discovery.

{
    "awsPool": {
        "class": "Pool",
        "members": [
            {
                "servicePort": 80,
                "addressDiscovery": "aws",
                "region": "us-east-1",
                "updateInterval": 20,
                "tagKey": "color",
                "tagValue": "blue",
                "addressRealm": "public"
            },
            {
                "servicePort": 8081,
                "addressDiscovery": "gce",
                "updateInterval": 10,
                "tagKey": "foo",
                "tagValue": "bar",
                "addressRealm": "private",
                "region": "us-west1"
            }
        ]
    }
}

Parameter Options Description/Notes
servicePort integer The port number you want the system to assign to newly discovered members in the BIG-IP load balancing pool.
addressDiscovery aws, gce, azure This class specifies the cloud vendor you are using: aws for Amazon Web Services, gce for the Google Cloud Platform, and azure for Microsoft Azure.
region string (aws, gce) The AWS or Google cloud region in which the BIG-IP should attempt to discover tagged resources. Important You must take care to include the proper region exactly as specified by your cloud vendor. AS3 does not validate the region, so posting a declaration with an invalid region will succeed according to AS3, however the tagged resources will not be discovered.
updateInterval integer (seconds) The rate at which the system attempts to discover changes in the tagged resources in the cloud.
tagKey string The tag Key you specified on the cloud resource (see the requirements section for information on what can be tagged). For specific instructions on tagging resources, see the documentation from your cloud vendor.
tagValue string The tag Value you specified on the cloud resource (see the requirements section for information on what can be tagged). For specific instructions on tagging resources, see the documentation from your cloud vendor.
addressRealm public, private The realm (either public or private) of your cloud resources. The BIG-IP only looks for resources in the realm you specify.
roleARN string (AWS only) roleARN and externalId allow you to assume a role in AWS. Assuming a role is typically used for cross-account access (for example if your Application servers are in one account and the BIG-IP VE is in another). See the AWS documentation for details. For roleARN, this is the Amazon Resource Name for the role you want the system to assume.
externalId string (AWS only) This is the externalID associated with the role you want the system to assume.
resourceGroup string (Azure only) The Name of the Azure Resource Group where your resources reside.
subscriptionId string (Azure only) Your Azure Subscription ID.
directoryId string (Azure only) Your Azure Active Directory ID (tenant ID)
applicationId string (Azure only) Azure registered application ID (AKA client ID)
apiAccessKey string (Azure only) Azure registered application API access key (AKA service principal secret). Will be stored in the declaration in an encrypted format.
credentialUpdate true, false (Azure) This only applies to Azure for this non-remote scenario. Specifies whether or not you are updating your credentials in this declaration.

To see a full example of a declaration that includes non-remote service discovery, see Example 16.

Version Notice:

Remote Service Discovery is available in AS3 v3.4.0 and later

Using remote service discovery

Remote service discovery allows your BIG-IP VE to be located anywhere, not necessarily in a specific cloud or region. For this feature to work properly, you must provide credentials for your cloud provider as shown in the following example.

This snippet is from a declaration contains examples for AWS, Google, and Azure.

{
    "webPool": {
        "class": "Pool",
        "members": [
            {
                "servicePort": 8082,
                "addressDiscovery": "aws",
                "updateInterval": 10,
                "tagKey": "foo",
                "tagValue": "bar",
                "addressRealm": "private",
                "region": "us-west-1",
                "accessKeyId": "<your key id>",
                "secretAccessKey": "<your secret access key>",
                "credentialUpdate": false
            },
            {
                "servicePort": 8081,
                "addressDiscovery": "gce",
                "updateInterval": 10,
                "tagKey": "foo",
                "tagValue": "bar",
                "addressRealm": "private",
                "region": "us-west1",
                "encodedCredentials": "<base 64 encoded credentials>",
                "credentialUpdate": false
            },
            {
                "servicePort": 8080,
                "addressDiscovery": "azure",
                "updateInterval": 10,
                "tagKey": "foo",
                "tagValue": "bar",
                "addressRealm": "private",
                "resourceGroup": "as3_dev",
                "subscriptionId": "7c3214a0-6a8c-41ad-9220-59f1da46883f",
                "directoryId": "d106871e-7b91-4733-8423-f98586303b68",
                "applicationId": "8851f8e2-3e00-4752-bbce-4bdf007ed34d",
                "apiAccessKey": "<your api access key>",
                "credentialUpdate": false
            }
        ]
    }
}

Parameter Options Description/Notes
servicePort integer The port number you want the system to assign to newly discovered members in the BIG-IP load balancing pool.
addressDiscovery aws, gce, azure This class specifies the cloud vendor you are using: aws for Amazon Web Services, gce for the Google Cloud Platform, and azure for Microsoft Azure.
region string (aws, gce) The AWS or Google cloud region in which the BIG-IP should attempt to discover tagged resources. Important You must take care to include the proper region exactly as specified by your cloud vendor. AS3 does not validate the region, so posting a declaration with an invalid region will succeed according to AS3, however the tagged resources will not be discovered.
updateInterval integer (seconds) The rate at which the system attempts to discover changes in the tagged resources in the cloud.
tagKey string The tag Key you specified on the cloud resource (see the requirements section for information on what can be tagged). For specific instructions on tagging resources, see the documentation from your cloud vendor.
tagValue string The tag Value you specified on the cloud resource (see the requirements section for information on what can be tagged). For specific instructions on tagging resources, see the documentation from your cloud vendor.
addressRealm public, private The realm (either public or private) of your cloud resources. The BIG-IP only looks for resources in the realm you specify.
roleARN string (AWS only) roleARN and externalId allow you to assume a role in AWS. Assuming a role is typically used for cross-account access (for example if your Application servers are in one account and the BIG-IP VE is in another). See the AWS documentation for details. For roleARN, this is the Amazon Resource Name for the role you want the system to assume.
externalId string (AWS only) This is the externalID associated with the role you want the system to assume.
accessKeyID string (AWS only) Your AWS Access Key, used for discovering AWS nodes that are not in the same region as your BIG-IP (also requires the secretAccessKey field). See https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys for more information.
SecretaccessKey string (AWS only) Your AWS Secret Access Key. This is stored in the declaration as an encrypted string.
encodedCredentials string (GCE only) Your AWS Access Key, used for discovering AWS nodes that are not in the same region as your BIG-IP (also requires the secretAccessKey field). See https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys for more information.
resourceGroup string (Azure only) The Name of the Azure Resource Group where your resources reside.
subscriptionId string (Azure only) Your Azure Subscription ID.
directoryId string (Azure only) Your Azure Active Directory ID (tenant ID)
applicationId string (Azure only) Azure registered application ID (AKA client ID)
apiAccessKey string (Azure only) Azure registered application API access key (AKA service principal secret). Will be stored in the declaration in an encrypted format.
credentialUpdate true, false Specifies whether or not you are updating your credentials in this declaration.

To see a full example of a declaration that includes non-remote service discovery, see Example 16a.