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.

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"
                }
            }
        }
    }
}

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"
                }
            }
        }
    }
}