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.
Requests¶
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"
}
}
}