Warnings, Notes, & Tips

Warnings

Warning

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

• IMPORTANT: The community-supported solution for AS3 running in a Docker container is being archived as of AS3 3.23. F5 will no longer provide new versions of AS3 running in a container.

• AS3 3.24 adds the ability to update APM policies. Updating Access Policy Management objects can be a slow process and may cause AS3 declarations to take longer to apply.

• You must use the admin user (and not just a user with administrator privileges) to install AS3.

• In AS3 3.16.0 and later, AS3 now saves the BIG-IP configuration (tmsh save sys config) even when the operation result is no change, unless persist is set to false (persist is set to true by default). This could affect performance for BIG-IP devices with a large number of configuration objects.
  
  

• 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 introduced 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 a POP3 profile in partition T1. POP3 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

• In AS3 3.20 and later, if a declaration includes a destination 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.
• Beginning with AS3 3.15, the AS3 RPM, Postman collection, and checksum files will no longer be located in the /dist directory in the AS3 repository on GitHub. These files can be found on the GitHub Release, as Assets. You can find historical files on GitHub by using the Branch drop-down, clicking the Tags tab, and then selecting the appropriate release.
  
  
• There are some changes to the way AS3 names BIG-IP objects in AS3 3.16.0 and later. See Updates to object naming in AS3 version 3.16.0 and later for details.
  
  
• To disable persistence on an application service, use "persistenceMethods": []. See Troubleshooting for more information.
  
  
• 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.
  
  

• The GitHub repository 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.
  
  
• 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 endpoint to see the status of the processing (and the results if it is finished). See AS3 API Reference 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 Appendix B: 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).