AS3 Declare

Overview

Use this API to post an Application Services 3 Extension (AS3) declaration, with an AS3 template defined on BIG-IQ, to a BIG-IP from BIG-IQ. With BIG-IQ, declarations use an AS3 template which is defined in BIG-IQ. For an example of an AS3 declaration that uses an AS3 template, see the AS3 documentation: Using declarations with AS3 templates . You can use AS3 on BIG-IQ in largely the same way as on BIG-IP and described in the AS3 documentation: Using AS3 with BIG-IQ. You can use the AS3 Template API to define your AS3 templates on BIG-IQ.

For information about the compatibility of BIG-IQ and BIG-IP with F5 Application Services 3 Extension (AS3) and F5 Declarative Onboarding (DO) releases, please refer to the support article: K54909607: BIG-IQ Centralized Management compatibility with F5 Application Services 3 Extension and F5 Declarative Onboarding .

For an example of composing a declaration, see the AS3 documentation at Composing an AS3 Declaration .

Note that an AS3 application service created using the AS3 Declare API appears with the Unknown Applications in the BIG-IQ. You can move it using the UI or by using the AS3 Move/Merge API.

REST Endpoint: /mgmt/shared/appsvcs/declare

Requests

GET /mgmt/shared/appsvcs/declare

To retrieve an AS3 declaration you can send a GET request to the declare endpoint.

Request Parameters

None

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
schemaOverlay string This is the name BIG-IQ uses for a supplemental validation schema that is applied to the Application class definition before the main AS3 schema. The subfields of schemaOverlay depend upon the particular application. The AS3 application service declarations are validated using the contents of this field and the contents must be a valid JSON Schema draft 7 .

Permissions

Role Allow
Application_Creator Yes
Application_Manager Yes

POST /mgmt/shared/appsvcs/declare

To post an AS3 declaration you can send the POST request to the declare endpoint.

Request Parameters

The request parameters in a POST request includes the following parameters.

Name Type Required Description
schemaOverlay string False. The name BIG-IQ uses for a supplemental validation schema that is applied to the Application class definition before the main AS3 schema. The subfields of schemaOverlay depend upon the particular application. The AS3 application service declarations are validated using the contents of this field and the contents must be a valid JSON Schema draft 7 . Omitting schemaOverlay means that the default template will be used and any of the classes in AS3 are available to the user. If no template has been attached to the AS3 app using schemaOverlay, users are unable to modify the AS3 app from the UI. For more information about using a template, see Using AS3 with BIG-IQ.
target object True A target is required in the declaration if using AS3 with BIG-IQ.
          address string True The address of the BIG-IP.

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
schemaOverlay string This is the name BIG-IQ uses for a supplemental validation schema that is applied to the Application class definition before the main AS3 schema. The subfields of schemaOverlay depend upon the particular application. The AS3 application service declarations are validated using the contents of this field and the contents must be a valid JSON Schema draft 7 .

Permissions

Role Allow
Application_Creator Yes
Application_Manager Yes

Examples

POST an AS3 declaration for a virtual service referencing an external security policy

To post an AS3 declaration for a virtual service referencing an external security policy, you can send the POST request to the declare endpoint on the BIG-IQ with the declaration in the body. For more information about AS3 declarations used to secure your BIG-IP, refer to the Application Security in the AS3 documentation.

On the BIG-IQ, your POST can look similar to the following example.

POST https://192.0.2.242/mgmt/shared/appsvcs/declare

The JSON in the body of the POST can look similar to the following. This example declaration creates an HTTP service, and attaches a Web Application Firewall (WAF) security policy hosted in an external location. Note the URL in the following example does not resolve, you would need to use a valid URL where you have uploaded the ASM policy you exported from a BIG-IP system.

{
    "class": "ADC",
    "schemaVersion": "3.12.0",
    "id": "5489432",
    "label": "ASM_policy_external_URL",
    "remark": "ASM_policy_external_URL",
    "target": {
            "address": "10.192.75.195"
    },
    "Sample_app_sec_02": {
            "class": "Tenant",
            "HTTP_Service": {
                    "class": "Application",
                    "template": "http",
                    "serviceMain": {
                            "class": "Service_HTTP",
                            "virtualAddresses": [
                                    "192.0.10.107"
                            ],
                            "snat": "auto",
                            "pool": "Pool1",
                            "policyWAF": {
                                    "use": "My_ASM_Policy"
                            }
                    },
                    "Pool1": {
                            "class": "Pool",
                            "monitors": [
                                    "http"
                            ],
                            "members": [{
                                            "servicePort": 8001,
                                            "serverAddresses": [
                                                    "10.10.10.143"
                                            ]
                                    },
                                    {
                                            "servicePort": 8002,
                                            "serverAddresses": [
                                                    "10.10.10.144"
                                            ]
                                    }
                            ]
                    },
                    "My_ASM_Policy": {
                            "class": "WAF_Policy",
                            "url": "https://example.com/asm-policy.xml",
                            "ignoreChanges": true
                    }
            }
    }
}

Note that if the external resource url is using a self-signed certificate, you can receive an error message similar to the following example, which indicates you need to add the certificate to the certificate store on the BIG-IQ.

Failed to execute step GET_PROTECTION_MODE: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target:

If you receive this error message, perform the following manual steps to add the self-signed certificate to the certificate store on the BIG-IQ.

First, get the certificate chain. If using OpenSSL, the command can look similar to the following.

echo "" | openssl s_client -host example.com -port 443 -showcerts | awk '/BEGIN CERT/ {p=1} ; p==1; /END CERT/ {p=0}' > ~/example.com.pem

Second, add the certificate to the java keystore on the BIG-IQ. If using the java keytool, the command can look similar to this example.

mount -o remount,rw /usr
/usr/lib/jvm/jre-1.8.0-openjdk.x86_64/bin/keytool -import -trustcacerts -keystore /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.212.b04-0.el6_10.x86_64/jre/lib/security/cacerts -alias example.com -file ~/example.com.pem
mount -o remount,ro /usr

Third, you must restart restjavad on the BIG-IQ before sending the POST request to /mgmt/shared/appsvcs/declare to post the AS3 declaration. You can use the following command to restart restjavad.

bigstart restart restjavad

Declare an AS3 template defined in BIG-IQ

For an example of an AS3 template (the schemaOverlay) which is defined in BIG-IQ see Using declarations with AS3 templates in the Application Services 3 Extension Documentation documentation.

POST to delete an AS3 application defined in BIG-IQ

To delete parts of an AS3 application’s configuration you have previously defined using BIG-IQ, use POST to send the declaration again, but remove the objects you want to delete. Note that to delete the configuration, send a POST and not a DELETE request. The following example uses BIG-IQ to delete the entire configuration for the Sample_http_01 tenant.

POST https://<BIG-IQ>/mgmt/shared/appsvcs/declare

The JSON in the body of the POST can be similar to the following example.

{
    "class": "AS3",
    "declaration": {
            "class": "ADC",
            "schemaVersion": "3.12.0",
            "id": "fghijkl7890",
            "label": "Sample 1",
            "remark": "HTTP with custom persistence",
            "target": {
                    "address": "10.1.1.3"
            },
            "Sample_http_01": {
                    "class": "Tenant"
            }
    }
}