Warnings, Notes, & Tips

Warnings

Warning

You should review the following items before using AS3 in production environments.

  • IMPORTANT: When using GSLB features, you must be aware of the following:

    • Because AS3 manages topology records globally in /Common, it is required that records only be managed through AS3, as it will treat the records declaratively. If a record is added outside of AS3, it will be removed if it is not included in the next AS3 declaration for topology records (AS3 completely overwrites non-AS3 topologies when a declaration is submitted).
    • Likewise, using AS3 to delete a tenant (for example, sending DELETE to the /declare/<TENANT> endpoint) that contains GSLB topologies will completely remove ALL GSLB topologies from the BIG-IP.

  • When you are using AS3 on a BIG-IP system that is part of a Device Group for high availability, if you want AS3 on all devices, you must manually install it on each BIG-IP in the group. Synchronizing the configuration between devices in a Device Group does NOT install AS3 on devices that do not have AS3 installed.

  • When posting a large declaration (hundreds of application services in a single declaration), you may experience a 500 error stating that the save sys config operation failed. If you experience this issue, see Troubleshooting.

  • 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.

  • 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 only with very large declarations or most declarations to BIG-IQ; if the declaration completes in less than 45 seconds, AS3 does not modify asynchronous mode.

  • Be sure to review this page, and also check the known issues on GitHub (https://github.com/F5Networks/f5-appsvcs-extension/issues) to review any known issues before you attempt to deploy AS3.

  • When creating a new tenant using AS3, it must not use the same name as a partition you separately create on the target BIG-IP system. If you use the same name and then post the declaration, AS3 overwrites (or removes) the existing partition completely, including all configuration objects in that partition.

  • After you use AS3 to create a tenant (which creates a BIG-IP partition), manually adding configuration objects to the partition created by AS3 can have unexpected results. For example:

    1. You post the a declaration using AS3 containing a single Virtual Server. You then use the BIG-IP Configuration Utility (GUI) to add another Virtual Server and Pool in the same Partition/Tenant manually. When you delete the Tenant using AS3, the system deletes both virtual servers.

    2. You post the same declaration, and then use the BIG-IP Configuration utility to add an SCTP profile in partition T1. SCTP profiles are not currently supported by AS3, therefore when you attempt to use AS3 to delete Partition T1, it fails with an error such as:

      "response":"0107082a:3: You must remove all objects from a partition before removing the partition (T1), type ID (4032)"

      This scenario fails because AS3 does not support the entire scope of BIG-IP operations. It can only act on a subset of configurations.

  • If you have not installed AS3, attempts to access it will result in a 400 HTTP Status Code. If you have just installed AS3, a request for a non-existent declaration results in a 204 HTTP Status Code. You may also see other HTTP status codes.

Notes and Tips

Note

The following are general tips and notes to keep mind when using AS3

  • As of AS3 3.10.0, if a Firewall_Address_List contains zero addresses, a dummy IPv6 address of ::1:5ee:bad:c0de is added in order to maintain a valid Firewall_Address_List. If an address is added to the list, the dummy address is removed.
  • With the release of AS3 3.8.0, the GitHub repository now includes a AS3 Postman collection with all of the example declarations. For information on importing this collection and using Postman collections, see the Postman documentation.

  • While a dash/hyphen (-) is a valid characters for naming objects directly on a BIG-IP system, it is not a valid character in a declaration object name so we can always parse declaration-object names out from BIG-IP object names. Likewise a dot (.) is not a valid character in a declaration object name, as the dot character is often used as an object separator in Javascript, NodeJS, and JSON tools, so allowing it in object names might satisfy one group of users while causing integration problems for others.
  • If using AS3 3.5.0 or later, you can use /mgmt/shared/appsvcs/declare?async=true if you have a particularly large declaration which will take a long time to process. AS3 returns a Task ID. You can later use a GET request to the Task ID end point to see the status of the processing (and the results if it is finished). See AS3 API Methods Details for more information.

  • If you are using BIG-IP v12.1.x with AS3 version 3.1.0 or later:
    AS3 creates a new TCP profile f5_tcp_progressive_12_1, which we designed to imitate one of the improved profiles released with BIG-IP v13.0. AS3 creates this profile in the /Common/Shared directory, so all AS3 tenants can use it. After submitting a declaration using BIG-IP v12.1.x, in the REST response, you’ll notice three Message blocks, two in “tenant” Common, and one in the tenant you specified in the declaration. The two in Common are a result of the new TCP profile, and you can safely ignore them. If you send a GET with ?show=expanded after submitting the declaration, you can see the settings of this profile.

  • We strongly recommend reviewing the Sizing BIG-IP Virtual Editions section (page 7) of Deploying BIG-IP VEs in a Hyper-Converged Infrastructure to ensure your BIG-IP system has sufficient CPU and memory for your needs.

  • If you are familiar with the BIG-IP system, and generally familiar with REST and using APIs, you can jump right to the Quick Start after reading the warnings and reviewing the known issues on GitHub (https://github.com/F5Networks/f5-appsvcs-extension/issues).

  • See our AS3 Overview video at https://www.youtube.com/watch?v=cMl3AOtMcUo, and the video on using AS3 at https://www.youtube.com/watch?v=NJjcUUtjnJU.

  • For example declarations that you can copy paste, see Example declarations and Additional Declarations.

  • To test whether your system has AS3 installed or not, use GET with the /mgmt/shared/appsvcs/info URI.

  • AS3 does not on-board a BIG-IP VE system, but works alongside the on-boarding functionality found in Ansible, AWS CloudFormation templates, Azure ARM templates, and others.

  • JSON (JavaScript Object Notation, rfc8259) is a text-based format. You may create and modify AS3 declarations with a JSON editor or a simple text editor.

  • The F5 BIG-IP Application Services 3 Extension is an iControl LX extension that provides a RESTful API which exchanges JSON messages over an HTTPS channel.

  • You may find it more convenient to put multi-line texts such as iRules into AS3 declarations by first encoding them in Base64.

  • To use a bulky configuration resource such as an F5 WAF security policy in a declaration, you may want to store it on a webserver under your control then put a URL reference to it into the declaration. For many resource types, AS3 can “pull in” the actual contents of the resource from a URL source.

  • To transmit your AS3 declarations you may use a specialized RESTful API client such as Postman or a universal client such as cURL.

  • Currently, no matter your BIG-IP user account name, audit logs show all messages from admin and not the specific user name.

  • From any client external to the BIG-IP, the AS3 RESTful API is only accessible using HTTPS (HTTP over TLS).