AS3 Frequently Asked Questions (FAQ)

What is AS3?

See the Introduction for a description of AS3. This entry contains information on what AS3 is and what it is not.

AS3 is:

BUT… it is:

  • not used to on-board or license a BIG-IP device
  • not intended for configuring Route Domains, Routes, Self IPs, VLANs, or other Layer 2/3 objects or components
  • not a mechanism to provide differential authorization or RBAC
  • not an iApp, nor does it configure iApps
  • not created to include a graphical interface (GUI)
  • not a replacement for iWorkflow

Which TMOS versions does AS3 support?

AS3 supports TMOS versions 12.1.x and later.


When is AS3 a good fit and when it is not?

AS3 is a good fit where: - You require a declarative interface to abstract away the complexity of BIG-IP configuration. - BIG-IP capabilities focus on LTM, GTM, and Security Policy attachment. - Organizations need to deploy BIG-IP configs as Infrastructure as Code (IaC) via integration with DevOps pipelines.

AS3 may not be a good fit where: - Declarative interface is not desirable - Organization is unwilling or unable to deploy iControl Extension RPM on BIG-IP - Organization wants to continue using imperative interfaces (GUI, TMSH, iControl REST APIs) to configure BIG-IP (not just monitor or troubleshoot).


Why did F5 create iControl LX and AS3 when there are already TCL iApps?

  • TCL iApps are a great solution for templatizing and simplifying specific application service.
  • Each TCL iApp focuses on the delivery of a single application service.
  • iControl LX gives new flexibility and capabilities not available in traditional TCL iApps.
  • iControl LX / iApps LX enables users to do everything they can do with TCL iApps and much more.
  • iControl LX enables users to deliver AS3 which provides a single declarative interface to enable a wide variety of BIG-IP configurations, not just a single application service.
  • iControl LX enables users to harness the power and flexibility of Node.js to enable new capabilities, 3rd-party integrations, and support DevOps pipelines.

How is AS3 different from Ansible?

  • Ansible is part of a large vendor ecosystem to manage & automate configuration of multiple platform types within the data center.
  • Ansible automates via imperative YAML playbooks which require knowledge of which BIG-IP modules need to run and in which order.
  • Ansible is great for templatizing BIG-IP configuration tasks via Playbooks and Roles.
  • F5 is dependent on Ansible release schedules, whereas F5 controls AS3 release schedule, allowing for a more aggressive release cadence.
  • Note: You can use Ansible as a front-end to AS3’s declarative API.

How do I get started with AS3?

See the Quick Start to jump right into using AS3.


What is an “AS3 Declaration”?

For detailed information on AS3 Declarations, see AS3 Declaration Purpose and Function.

  • AS3 uses a declarative model, meaning you provide a JSON declaration rather than a set of imperative commands.
  • The declaration represents the configuration which AS3 is responsible for creating on a BIG-IP system.
  • You do not need to sequence the declaration in a specific order; AS3 will figure out the steps and order of operations for you, making it declarative.
  • AS3 is well-defined according to the rules of the JSON Schema, and validates declarations according to the JSON Schema.

What is the AS3 Schema?

For detailed information on the AS3 Schema, see F5 AS3 JSON Schema.

Briefly:

  • The JSON Schema document prescribes the syntax of an AS3 declaration.
  • The AS3 declaration schema controls what objects may appear in a declaration, what name they may or must use, what properties they may have, which of those you must supply in the declaration, and which AS3 may fill with default values.
  • The schema also specifies the ranges of values which certain properties may take on.

Do all of my application services need to be named “ServiceMain”? UPDATED FOR AS3 3.20

As of AS3 3.20, if you do not specify a template in the Application Class, AS3 uses the generic template by default. The generic template does not have or enforce any content requirements, so there is no requirement for naming the virtual service serviceMain. When using the generic template (either explicitly or by default in 3.20+) you can still use the Class property in the Service Class to specify a specific service, such as Service_HTTP or Service_TCP.

In versions prior to 3.20, you can still manually specify the generic template to avoid the serviceMain naming requirement. If you do use one of the templates other than generic or shared (http, https, tcp, udp, l4), for each application service in a tenant you must use the name serviceMain for your application service.

Note

All of the example declarations have been updated to remove any template, and the virtual service names have been changed to service, although you can change this name to suit your configuration. If you attempt to use one of these examples on a version prior to 3.20, they will fail.

See this Troubleshooting entry for more information and workarounds.


What is the delivery cadence for AS3?

AS3 is targeted for a 6-week release cycle.


How do I manage “source of truth” with AS3?

  • When you use AS3, the source of truth is the AS3 declaration; the source of truth is no longer on BIG-IP
  • If you use AS3 to create an app service, you must ALWAYS use AS3 to manage it through its app lifecycle
  • When using AS3, do not edit or update your app services configurations outside of AS3 (e.g. via GUI, CLI, iControl REST, TCL iApp)
  • The intent of AS3 is to be an orchestration tool where the orchestration system manages the source of truth (e.g. managing declarations in GitHub).

Is there a migration path for AS3 releases?

F5 intends to ensure all AS3 releases schemas/APIs are backwards compatible, so we recommend migrating to the newest supported version of AS3. Because F5 guarantees AS3 schema backwards-compatibility, upgrades to newer versions of AS3 should be seamless.


What if I upgrade my BIG-IP system, how to I migrate my AS3 configuration?

When you upgrade your BIG-IP system, you simply install AS3 on the upgraded BIG-IP system and re-deploy your declaration. For example, you installed AS3 on your BIG-IP running version 12.1.1 and deployed a declaration. You decide to upgrade your BIG-IP system to 13.1. Once the upgrade to 13.1 is complete, you must install AS3 on the BIG-IP. After you install AS3, you send the same declaration you used pre-upgrade to the 13.1 BIG-IP system. Your upgraded BIG-IP will then have the same configuration as the previous version.


What happens on the front-end and back-end of AS3?

  • Front-end: AS3 exposes a declarative iControl LX REST API on the front-end: /mgmt/shared/appsvcs/declare.
  • Back-end: AS3 uses iControl REST APIs on the back-end to communicate with BIG-IP. AS3 can use 3rd party REST APIs to communicate with 3rd party systems, enabling integration opportunities.

Does AS3 support multi-tenancy?

  • Yes, AS3 creates and uses additional partitions to enable multi-tenancy
  • AS3 ONLY writes to the Common partition when you specifically use the Common tenant with the Shared application (/Common/Shared); see the next FAQ entry
  • AS3 writes to the Common partition as required for some GSLB configurations
  • AS3 does NOT have access to tenants/partitions other than those it creates and /Common

When does AS3 write to the Common partition for LTM configurations?

  • As noted above, AS3 only writes to the Common partition when you specifically use /Common/Shared. Otherwise, AS3 does not write to the Common partition for LTM configurations to ensure there is no impact to an existing device configuration where both AS3 and legacy configuration methods are being used
  • While use of separate partitions may be new behavior for some users, F5 has designed AS3 in this manner in order to deliver the safest possible deployment mechanism on BIG-IP
  • The use of separate partitions also prevents possible naming collisions and maintains a logical object hierarchy that allows AS3 to deliver stable transactions (atomicity) and idempotency

Which existing objects can AS3 reference in the Common partition?

Some properties in AS3 are polymorphic, allowing you to choose among predefined resources selected by name, a declared resource, or a BIG-IP resource defined outside AS3. When a value in this category is an object, it must have exactly one property, either use or bigip.

use indicates a reference to another class object in the declaration. bigip indicates a component pathname to an object that was created outside of AS3 (typically in /Common).

Using the bigip clause allows you to specify pre-existing objects, such as pools, SNATs, iRules, HTTP profiles, HTTP Compression profiles, HTTP Acceleration profile, TCP profiles, UDP profiles, Multiplex profiles, WAF policies, IAM policies, Firewall policies, NAT policies, Endpoint policies, Server TLS profiles, client TLS profiles, SSL certificates, and SSL keys.

To reference these objects, you simply include a line in your declaration such as:

"profileTCP": {
   "bigip": "/Common/mptcp-mobile-optimized"
}

Some of the example declarations in Appendix B: Additional Declarations contain these references. For more information on referencing objects, see the reference documentation. Also see our video about referencing objects on the BIG-IP: https://www.youtube.com/watch?v=b55noytozMU.


Does AS3 replace iWorkflow?

  • AS3 does not replace iWorkflow
  • An iWorkflow-like GUI-based Service Catalog is not built into AS3
  • You can build GUI-based Service Catalog capabilities with third-party tools like Ansible Tower

Is AS3 backwards-compatible with AS2.x API calls?

No.


How do I report issues, feature requests, and get help with AS3?

  • You can use GitHub Issues to submit feature requests or problems with AS3.
  • Because F5 Networks created and fully tested AS3, it is fully supported by F5. This means you can get assistance if necessary from F5 Technical Support.
  • Community Help:
    We encourage you to use our Slack channel for discussion and assistance on AS3 (click the f5-appsvcs-extension channel). Some F5 employees are members of this community, and they typically monitor the channel Monday-Friday 9-5 PST and will offer best-effort assistance. You should not consider this Slack channel community support as a substitute for F5 Technical Support. See the Slack Channel Statement for guidelines on using this channel.

What is the difference between AS3 Selective and Complete updates and why is this important?

  • Selective is the default behavior in which tenants not explicitly referenced in declaration rePOSTing are NOT modified.
  • When you enable Complete update, AS3 WILL delete tenants not explicitly referenced in declaration rePOSTing (e.g. if the tenant is no longer in the declaration, that is an implicit instruction to delete the tenant so that the resulting config truly represents what you requested).
  • It is important to know the difference to prevent you from accidentally deleting tenants if you don’t reference them when updating a declaration. See ADC Class for usage.

Does AS3 support token authentication? This is critical to support remote authentication roles (TACACS).

  • AS3 relies on the iControl LX framework for auth, and takes either Basic Auth credentials or iControl REST tokens (X-F5-Auth-Token) to authenticate to target devices.
  • The AS3 user must supply one or the other; AS3 does not convert Basic Auth (name + passphrase) credentials to iControl REST tokens itself.

Given AS3’s tenancy model uses administrative partitions, does this mean I need to explicitly specify my SSL certificates and keys in each tenant partition?

No. While AS3 does not write to the Common partition, AS3.3.0 introduces the ability to reference SSL certificates and keys defined in the clientssl profile in the Common partition. This simplifies your AS3 declarations enabling you to accelerate secure deployments of your app services.


What can I do with the Service Discovery capability introduced in AS3.3.0?

AS3.3 introduces the ability to use F5’s Service Discovery feature for Amazon Web Services (AWS) and Google Cloud Platform. Service Discovery enables the BIG-IP system to automatically update members in a load balancing pool based on cloud application hosts. You simply tag your cloud resources with key and value information, and then in the declaration you POST information about your cloud environment, including the cloud tag key and tag value you specified, and the BIG-IP VE programmatically discovers (or removes) members with those tags.


How do I include Service Discovery in my AS3 declaration?

See Service Discovery Examples for information.


I used a TLS_Server object in my AS3 declaration, why did it create a Client SSL profile on the BIG-IP?

The AS3 naming convention for TLS Server and TLS Client differs from traditional BIG-IP terminology to better comply with industry usage, but may be slightly confusing for long-time BIG-IP users. The AS3 TLS_Server class is for connections arriving to the BIG-IP, which creates a “client SSL profile” object on the BIG-IP. The AS3 TLS_Client class if for connections leaving the BIG-IP, which creates a “server SSL profile” on the BIG-IP. See TLS_Server and TLS_Client in the Schema Reference for more information.


How do I synchronize configurations (configsync) across BIG-IP devices in a Device Group with AS3?

To use AS3 to synchronize configurations across BIG-IP devices in an *existing* Device Group use the AS3 Class with the syncToGroup property in your declaration.

The syncToGroup value is the name (such as /Common/my_dg) of the config-sync Device group TO which the system should synchronize the targetHost configuration after (and only if) this request deploys any changes. If you do not use the syncToGroup property, or leave it empty (default), this request will not affect config-sync at all. Leave undefined or empty whenever you use auto-sync or manage configuration synchronization separately.


Does AS3 collect any usage data?

The Application Services Extension (AS3) gathers non-identifiable usage data for the purposes of improving the product as outlined in the end user license agreement for BIG-IP. To opt out of data collection, disable BIG-IP system’s phone home feature as described in K15000.


What is F5’s Automation Toolchain API Contract?

The API Contract for the F5 Automation Toolchain (AS3, Declarative Onboarding, and Telemetry Streaming) is our assurance that we will not make arbitrary breaking changes to our API. We take this commitment seriously. We semantically version our declarative API schemas (“xx.yy.zz”) and do not make breaking changes within a minor (“yy”) or patch (“zz”) releases. For example, early declarations using AS3 schema “3.0.0” are accepted by all subsequent minor releases including “3.16.0.”

As of January 2020, no breaking changes have been made to AS3, Declarative Onboarding, or Telemetry Streaming since inception. None are anticipated at this time. A breaking change, if any, will be noted by a change to the major release number (“xx”). For example, the AS3 schema version would become “4.0.0.”


What BIG-IP modules does AS3 support?

As of AS3 3.17.0, AS3 provides feature support for LTM, GTM/DNS, APM, AFM, ASM, and PEM modules. Please refer to the product documentation (https://support.f5.com/csp/knowledge-center/software) for details on the capabilities supported in these modules.

What is the difference between the AS3 Container and the F5 API Services Gateway?

AS3 Container is specifically for AS3 use cases, and the F5 API Services Gateway is specifically for custom iControl LX extension use cases.

Both are community-supported and are in the f5Devcentral organization on Docker Hub. Once either is fully supported by F5, it will move to f5networks on Docker Hub.

See Using AS3 in a Docker Container for more information.

Can I use the same virtual IP address in an AS3 declaration as an existing virtual address on the target BIG-IP?

In versions prior to 3.20, AS3 would create a new virtual IP address for the address specified in the declaration, even if there was an existing virtual IP address.

In version 3.20 and later, if a declaration includes a virtual address that conflicts with an existing virtual-address object in the Common tenant/partition on the target BIG-IP system, AS3 no longer attempts to create a new virtual address and will use the existing address on the BIG-IP.