Put it simple, AS3 is a way to configure a BIG-IP once a BIG-IP is already provisioned. Full stop!
We can also use AS3 to maintain that configuration over time.
The way it works is we as a client send a JSON declaration via REST API and AS3 engine is supposed to work out how to configure BIG-IP the way it's been declared.
AS3 internal components (parser and auditor) are explained further ahead.
For non-DEV audience, AS3 is simply the name we give to an intelligent listener which acts as an interpreter that reads our declaration and translate it to proper commands to be issued on the BIG-IP.
AS3 engine may or may not reside on BIG-IP (more on that on section entitled "3 ways of using AS3").
Yes, AS3 is declared in a structured JSON file and there are many examples on how to configure your regular virtual server, profiles, pools, etc, on clouddocs.
AS3 uses common REST methods to communicate such as GET, POST and DELETE under the hood.
For example, when we send our AS3 declaration to BIG-IP, we're sending an HTTP POST with the AS3 JSON file attached.
AS3 is part of the Automation Toolchain which includes Declarative Onboarding and Telemetry Steaming.
AS3 doesn't support RBAC in a way that you can allow one user to configure certain objects and another user to configure other objects.
AS3 has to use admin username/password with full access to BIG-IP resources.
There's currently no native GUI built on top of AS3.
AS3 won't and doesn't work out how to connect to different BIG-IPs and automatically figure out which box it needs to send which configuration to.
All it does is receive a declaration, forwards it on and configure BIG-IP.
We can't currently use AS3 to pull BIG-IP configuration and generate an AS3 configuration but I hope this functionality should be available in the future.
We can't use AS3 for doing things like configuring VLANs or NTP servers.
We use AS3 to configure BIG-IP once it's been already initially provisioned.
For BIG-IP's initial set up, we use Declarative Onboarding.
To configure and maintain BIG-IPs across multiple versions using the same automated workflow.
A simple JSON declaration becomes the source of Truth with AS3, where configuration edits should only be made to the declaration itself.
If multiple BIG-IP boxes use the same configuration, a single AS3 declaration can be used to configure the entire fleet.
It can also be easily integrated with external automation tools such as Ansible and Terraform.
AS3 targets and supports BIG-IP version 12.1 and higher.
Say we have an AS3 declaration that was previously used to configure BIG-IP v12.1, right?
Regardless if we're upgrading or moving config to another box, we can still use the same declaration to configure BIG-IP v15.1 box in the same way.
I'm not joking!
Back in the F5 Engineering Services days, I still remember when I used to grab support tickets where the issue was a configuration from an earlier version that was incompatible with newer version, e.g. a profile option was moved to a different profile, or new feature was added that requires some other option to be selected, etc.
This is supposed to be a thing of the past with AS3.
If you're a DBA, you've certainly heard of the term ACIDIC (atomicity, consistency, isolation, and durability).
Let's say we send an AS3 declaration with 5 objects.
AS3 will either apply the entire declaration or not apply at all.
What that means is that if there's one single error, AS3 will never apply part of the configuration and leave BIG-IP in an unknown/inconsistent state.
There's no in-between state.
Either everything gets configured or nothing at all.
It's either PASS or FAIL.
Say we send a declaration where there's nothing to configure on BIG-IP.
In that case, AS3 will come back to client and inform that there's nothing for it to do.
Essentially, AS3 won't remove BIG-IP's entire config and then re-apply it.
It is smart enough to determine what work it needs to do and it will always do as little work as possible.
AS3 enforces multi-tenancy by default, i.e. AS3 only creates objects in partitions (known as "tenants" in AS3 jargon) other than /Common.
If we look at the AS3 declaration examples, we can see that a tenant (partition) is specified before we declare our config.
AS3 does not create objects in the /Common partition.
The exception to that is /Common/Shared when objects are supposed to be shared among multiple partitions/tenants.
An example is when we create a pool member and a node gets automatically created on BIG-IP.
Such node is created on /Common/Shared partition because that node might be a pool member in another partition, for example.
Nevertheless, AS3 scope is and must always be bounded.
In this case here, we install AS3 RPM on each BIG-IP.
BIG-IP is the box that has the "AS3 listener" waiting for us to send our AS3 JSON config file.
All we need to do is to download AS3's binary and install it locally.
There's a step by step guide for babies (with screenshots) here using BIG-IP's GUI.
There's also a way to do it using curl if you're a geek like me here.
In this case, we don't need to manually install AS3 RPM on each BIG-IP box like in previous step.
BIG-IQ does it for us.
BIG-IQ v6.1.0+ supports AS3 and we can directly send declarations through BIG-IQ.
Apart from installing, BIG-IQ also upgrades AS3 in the target box (or boxes) if they're using an older version.
Analytics and RBAC are also supported.
This is where AS3 is completely detached from BIG-IP.
In the Docker container set up, AS3 engine resides within a Docker container decoupled from BIG-IP.
Say your environment have Docker containers running, which is not something uncommon nowadays.
We can install AS3 in a Docker container and use that container as the entry-point to send our AS3 declaration to BIG-IP.
Yes, we as Cluent send our AS3 JSON file to where the Docker container is running and as long as the Docker container can reach our BIG-IP, then it will connect and configure it.
Notice that in this case our AS3 engine runs outside of BIG-IP so we don't have to install AS3 on our BIG-IP fleet here.
Docker container communicates with BIG-IP using iControl REST sending tmsh commands directly.
AS3 engine is comprised of an AS3 parser and AS3 auditor:
This is the front-end part of AS3 that communicates with the client and is responsible for client's declaration validation.
After receiving validated declaration from AS3 parser, AS3 auditor's job is to compare desired validated declaration with BIG-IP's current configuration.
It then determines what needs to be added/removed and forwards the changes to BIG-IP.
The way it works is Client sends a declaration to AS3 parser and config validation process kicks in.
If declaration is not valid, it throws an error back to client along with an error code.
If valid, declaration is forwarded on to AS3 auditor which then compares declaration with current BIG-IP's config and determines what needs to change.
Only the configuration changes are supposed to be sent to BIG-IP, not the whole config.
AS3 auditor then converts AS3 declaration to tmsh commands and send converted tmsh config to BIG-IP via iControl REST.
BIG-IP then pushes the changes via tmsh commands and returns success/error to AS3 auditor.
If changes are not successful, an error is returned all the way to the client.
Otherwise, successful code is returned to client and changes are properly applied to BIG-IP.
Here's the visual description of what I've just said:
AS3 schema validation errors are returned in HTTP Response with a message pointing to the specific error:
This includes typos in property names and so on.
Logs on BIG-IP are stored on /var/log/restnoded/restnoded.log and by default only errors are logged.
Log level can be changed through the Controls object in AS3 declaration itself.
This is usually source of confusion so I'd like to clarify that a bit.
AS3 is the way we configure BIG-IP once it's already up and running.
Declarative Onboarding (DO) is for the initial configuration of BIG-IP, i.e. setting up licence, users, DNS, NTP and even provisioning modules.
Just like AS3, DO is API-only so no GUI on top of it.
We can also have AS3 and DO in the same BIG-IP, so that's not a problem at all.
Currently, there's no option to run it in a container like AS3 so as far as I'm concerned, it's only RPM based.
I'd like to thank F5 Software Engineers Steven Chadwick and Garrett Dieckmann from AS3 team for providing a brilliant reference material.