Warnings, Notes, & Tips

Warnings

Warning

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

  • 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

  • NEW: 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 video on using AS3 at https://www.youtube.com/watch?v=bOEJ6SwhsJs.

  • For example declarations that you can copy paste, see Example declarations and Appendix B: Additional Example 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.

  • Currently, AS3 installs and runs on the BIG-IP system only.

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