Using AS3 with BIG-IQ

BIG-IQ v6.1.0 adds AS3 support, which includes AS3 v3.7.0. When you use AS3 on BIG-IQ, declarations you send through BIG-IQ enable applications to appear in the UI of BIG-IQ (Applications tab > Applications menu), with support for BIG-IQ’s analytics and RBAC capabilities. For information on viewing applications and analytics in the BIG-IQ UI, see the BIG-IQ Monitoring and Managing Application Services documentation.

Important

If your BIG-IP does not have AS3 installed or if an older version of AS3 is installed, BIG-IQ installs its version of AS3 onto the target BIG-IP system. This means if you have a BIG-IP running the current LTS version of AS3 (3.5.1), and use that BIG-IP as a target for BIG-IQ, the LTS version will be overwritten by the AS3 version on BIG-IQ (3.7.0 at launch).

With BIG-IQ, declarations can use an AS3 template which is defined in BIG-IQ. See Using declarations with AS3 templates for an example of an AS3 declaration that uses an AS3 template, and the BIG-IQ API documentation for details related to creating AS3 templates.

You use the same method to post a declaration to AS3 on BIG-IQ as for BIG-IP. To submit an AS3 declaration, use a specialized RESTful API client such as Postman or a universal client such as cURL. To transmit the declaration, you POST the declaration to the URI <BIG-IQ IP address>/mgmt/shared/appsvcs/declare. The way you interact with AS3 on BIG-IQ is largely the same as on BIG-IP, so the instructions on using AS3 apply to both. The main differences for BIG-IQ are Updating declarations to specify the target BIG-IP, and optionally Using declarations with AS3 templates.

This page contains information specific to running AS3 on BIG-IQ. BIG-IQ is well-documented in the BIG-IQ documentation.

Requirements for using AS3 with BIG-IQ

To use AS3 with BIG-IQ, you must perform the following. For specific instructions on these tasks, see the BIG-IQ online help or documentation (BIG-IQ) or the BIG-IP documentation.

  • Install BIG-IQ v6.1.0 or later.
  • Manage one or more BIG-IP devices in BIG-IQ. LTM and any other relevant services should be discovered/imported.
  • Specify the target BIG-IP in your AS3 declarations on BIG-IQ. BIG-IQ can manage multiple BIG-IP devices, so declarations must specify the applicable BIG-IP.

In order to make use of BIG-IQ’s analytics capabilities, you must also:

  • Connect at least one (data collection device) to BIG-IQ.
  • Use BIG-IP version 13.1.0.5 or newer.
  • Provision Analytics (PDF) (Analytics) on BIG-IP.
  • Enable stats for the BIG-IP within BIG-IQ.
  • Configure an analytics profile for your service in the declaration.

Additionally, we recommend that:

  • You use AS3’s asynchronous mode (by POSTing with the query parameter ?async=true). AS3 waits for applications to be configured in BIG-IQ, which can result in timeouts when using AS3’s synchronous mode. See Method POST for more information.

    IMPORTANT: AS3 3.7.0 introduces new behavior for asynchronous mode. Even if you have asynchronous mode set to false, after 45 seconds AS3 sets asynchronous mode to true (API swap), and returns an async response. This allows you to use GET to poll for status (you should see a 202 status until the declaration is complete). This typically occurs for most declarations to BIG-IQ (and only very large declarations to BIG-IP); if the declaration completes in less than 45 seconds, AS3 does not modify asynchronous mode.

  • You only use AS3 running on BIG-IQ. BIG-IQ does not support cases where AS3 runs externally (in a container for example).

To make use of the RBAC capabilities on BIG-IQ:

  • Use BIG-IQ’s auth token for authentication (see the BIG-IQ auth documentation for specific instructions).
  • For application creation, add users to a custom Application Creator role, with access to any relevant AS3 templates.
  • For each application created, a manager and viewer role are created automatically.

Important

Currently, the PATCH and DELETE methods are not supported when using BIG-IQ and AS3 with the target field.

Updating declarations to specify the target BIG-IP

This example shows specifying the target BIG-IP hostname. You can also specify the address instead of hostname (the address should be the BIG-IP discovery address).

{
    "class": "AS3",
    "declaration": {
        "class": "ADC",
        "schemaVersion": "3.0.0",
        "id": "fghijkl7890",
        "label": "Sample 1",
        "remark": "HTTP with custom persistence",
        "target": {
            "hostname": "bigip.example.com"
        },
        "Sample_http_01": {
            "class": "Tenant",
            "A1": {
                "class": "Application",
                "template": "http",
                "serviceMain": {
                    "class": "Service_HTTP",
                    "virtualAddresses": [
                        "10.0.2.10"
                    ],
                    "pool": "web_pool",
                    "persistenceMethods": [{
                        "use": "jsessionid"
                    }]
                },
                "web_pool": {
                    "class": "Pool",
                    "monitors": [
                        "http"
                    ],
                    "members": [{
                    "servicePort": 80,
                    "serverAddresses": [
                        "192.0.2.10",
                        "192.0.2.11"
                    ]
                    }]
                },
                "jsessionid": {
                    "class": "Persist",
                    "persistenceMethod": "cookie",
                    "cookieMethod": "hash",
                    "cookieName": "JSESSIONID"
                }
            }
        }
    }
}

Deleting the configuration on the target BIG-IP device

If you want delete any of the configuration you previously created on the target BIG-IP device, you simply use POST to send the declaration again, but remove the object(s) you want to delete (see the following examples).

Note

Make sure to use the POST method and not DELETE as described in this section.

For instance, using the previous example, if we want to use AS3 on BIG-IQ to delete the pool (web_pool) that was created, we would use the following declaration which sends the declaration without the pool.

{
    "class": "AS3",
    "declaration":{
         "class": "ADC",
         "schemaVersion": "3.0.0",
         "id": "fghijkl7890",
         "label": "Sample 1",
         "remark": "HTTP with custom persistence",
         "target": {
             "hostname": "bigip.example.com"
         },
         "Sample_http_01": {
             "class": "Tenant",
             "A1": {
                 "class": "Application",
                 "template": "http",
                 "serviceMain": {
                     "class": "Service_HTTP",
                     "virtualAddresses": [
                         "10.0.2.10"
                     ],
                     "persistenceMethods": [{
                         "use": "jsessionid"
                     }]
                 },
                 "jsessionid": {
                     "class": "Persist",
                     "persistenceMethod": "cookie",
                     "cookieMethod": "hash",
                     "cookieName": "JSESSIONID"
                 }
             }
         }
     }
 }
 

If we want to use AS3 on BIG-IQ to delete everything in the Sample_http_01 tenant, we would POST the following declaration.

{
    "class": "AS3",
    "declaration":{
         "class": "ADC",
         "schemaVersion": "3.0.0",
         "id": "fghijkl7890",
         "label": "Sample 1",
         "remark": "HTTP with custom persistence",
         "target": {
             "hostname": "bigip.example.com"
         },
         "Sample_http_01": {
             "class": "Tenant"
         }
     }
 }
 

Using declarations with AS3 templates

This example shows a declaration that uses an AS3 template (the schemaOverlay) which is defined in BIG-IQ. In this case, all but the virtualAddress are defined in the template. See the BIG-IQ API documentation for details related to creating AS3 templates.

{
    "class": "AS3",
    "declaration": {
        "class": "ADC",
        "target": {
            "hostname": "bigip.example.com"
        },
        "schemaVersion": "3.6.0",
        "id": "TEST_Service_HTTP",
        "TestApp1": {
            "class": "Tenant",
            "testHttpApp1": {
                "class": "Application",
                "schemaOverlay": "template1",
                "template": "http",
                "serviceMain": {
                    "class": "Service_HTTP",
                    "virtualAddresses": ["192.0.2.10"],
                    "pool": "pool"
                },
                "pool": {
                    "class": "Pool"
                }
            }
        }
    }
}