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. You can also see our BIG-IQ and AS3 video.
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.
Note
See K54909607 for information on BIG-IQ and AS3 compatibility, and how to upgrade AS3 on a BIG-IQ.
- 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.
- NOTE: BIG-IQ does not yet implement dry-run (see AS3 Class), and if you POST with dry-run the changes will not be made. However, if you look at the declaration on BIG-IQ, it will show the new config as though it were applied.
Important
When using the BIG-IQ UI to deploy an AS3 application service, the BIG-IQ uses IP address to deploy the app service. We have updated the examples on this page to use a target address instead of hostname
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 DELETE method is not supported when using BIG-IQ and AS3 with the target field. Additionally, the PATCH method when using BIG-IQ and AS3 with the target field is only supported using BIG-IQ 7.0 or later and AS3 3.10.0 and later; previous versions are not supported.
Warning
While AS3 allows AS3 allows you to creates objects under /Common/Shared when using the Shared template, BIG-IQ does not support the creation of AS3 objects in /Common. We recommend you use a partition other than /Common, such as /CommonAS3/Shared. See Shared in the Reference Guide for information on using /Shared in AS3.
Note
When AS3 is running on BIG-IQ, dry-run (see Post Actions) is not supported. Also see https://support.f5.com/csp/article/K23452283.
Note
Sending a GET request to /mgmt/shared/appsvcs/declare is supported on BIG-IQ
Updating declarations to specify the target BIG-IP¶
This example shows specifying the target BIG-IP IP address (the address should be the BIG-IP discovery address). You can also specify the hostname instead of address.
Important
AS3 declarations deployed via the BIG-IQ web interface, or sent to a device that is a part of an HA cluster will always use the IP address as the target.
{
"class": "AS3",
"declaration": {
"class": "ADC",
"schemaVersion": "3.7.0",
"id": "fghijkl7890",
"label": "Sample 1",
"remark": "HTTP with custom persistence",
"target": {
"address": "192.0.2.200"
},
"Sample_http_01": {
"class": "Tenant",
"A1": {
"class": "Application",
"service": {
"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.7.0",
"id": "fghijkl7890",
"label": "Sample 1",
"remark": "HTTP with custom persistence",
"target": {
"address": "192.0.2.200"
},
"Sample_http_01": {
"class": "Tenant",
"A1": {
"class": "Application",
"service": {
"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": {
"address": "192.0.2.200"
},
"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": {
"address": "192.0.2.200"
},
"schemaVersion": "3.6.0",
"id": "TEST_Service_HTTP",
"TestApp1": {
"class": "Tenant",
"testHttpApp1": {
"class": "Application",
"schemaOverlay": "template1",
"service": {
"class": "Service_HTTP",
"virtualAddresses": ["192.0.2.10"],
"pool": "pool"
},
"pool": {
"class": "Pool"
}
}
}
}
}
Using POST with an action of patch and a patchbody¶
This example shows how you can use POST with an action of patch to include additional configuration objects in an existing tenant on a BIG-IQ device (which would subsequently be pushed out to BIG-IP devices). Most of the information is in patchBody, which contains the target BIG-IQ device information, and an add operation with some additional BIG-IP configuration objects.
Note that when using this feature, the BIG-IQ allows the same tenant on different targets (bigiqTenant in this example), but the application in the tenant must be unique. Using the following example, you could use the same bigiqTenant for two different target BIG-IQs, but there can be only one myapp2 application.
Important
This operation is only valid using the POST method, and not the PATCH method.
Note
The target MUST be the same as the one used in the initial declaration.
AS3 declarations deployed via the BIG-IQ web interface, or sent to a device that is a part of an HA cluster will always use the IP address as the target.
See patchBody in the AS3 Class and AS3_Patch_Item in the schema reference for details and usage.
{
"class": "AS3",
"action": "patch",
"patchBody": [
{
"target": {
"address": "192.0.2.200"
},
"path": "/bigiqTenant/myapp2",
"op": "add",
"value": {
"class": "Application",
"vs_myapp2": {
"class": "Service_HTTP",
"virtualAddresses": [
"10.42.10.113"
],
"snat": "auto",
"pool": "pool_myapp2",
"virtualPort": 8080
},
"pool_myapp2": {
"class": "Pool",
"monitors": [
"http"
],
"members": [
{
"servicePort": 8090,
"serverAddresses": [
"10.1.20.130",
"10.1.20.131",
"10.1.20.132"
]
}
]
}
}
}
]
}