Using AS3 in a Docker Container

F5 Networks has created a Docker Container (currently Community Supported) with AS3 installed. You can use this container to send declarations to BIG-IP systems, even BIG-IPs that do not have AS3 installed. This can be extremely useful for automating BIG-IP configurations.

Important

Note this solution is currently Community Supported and in the F5Devcentral organization on Docker Hub. Once it is fully supported by F5, it will move to f5networks on Docker Hub.

Prerequisites

  1. You must have Docker installed (https://www.docker.com/get-started/) and running.
  2. You must have a target BIG-IP system running version 12.1.x (if using AS3 v3.1.0 or later) or v13.0 or later to use AS3.
  3. If running Docker on Microsoft Windows, you must make sure the drive in which you are working (for example, your C: drive) is shared in the Docker settings.
  4. Once your container is running, you must use the target parameters in your AS3 declaration as described on this page.

Downloading and starting the AS3 Docker container

The first task is to download (pull) the Docker image from Docker Hub. If you plan on adding base authentication, see Adding Base Authentication for guidance on the directory structure for pulling the image.

  1. Download the F5 AS3 Docker image using the following command syntax: docker pull f5devcentral/f5-as3-container:<tag name>. The <tag name> is optional and allows you to include a specific tag using :<tagname> after f5-as3-container. If you do not include a tag, it downloads the latest version (:latest).
    Once the download is complete, you should see a status message stating the image was downloaded.
  2. Run AS3 container using the command: docker run --name as3_container --rm -d -p 8443:443 -p 8080:80 f5devcentral/f5-as3-container:latest
  3. To test the Docker image is functional, you can use one of the following options (the following examples use localhost, you can use an IP address in place of localhost if your client and container are on different devices):
    • From your RESTful client, use GET to send https://localhost:8443/mgmt/shared/appsvcs/info
    • Run the following cURL command: curl -k https://localhost:8443/mgmt/shared/appsvcs/info

You should see a response like the following:

{
    "version": "3.5.0",
    "release": "1",
    "schemaCurrent": "3.5.0",
    "schemaMinimum": "3.0.0"
}

Sending a declaration to a BIG-IP using the Docker container

Typically you use the AS3 container to send a declaration to a BIG-IP system that is not running AS3 (although this is not a requirement). To send a declaration to a BIG-IP system you use the new target parameters in the AS3 class (see the example below). These parameters specify the BIG-IP system where you want to send the configuration, and the user account with permission to access that BIG-IP system.

Again, the following examples use localhost, you can use an IP address in place of localhost if your client and container are on different devices.

To send a declaration with the container using a RESTful client, use https://localhost:8443/mgmt/shared/appsvcs/declare, and then POST a declaration.

To send a declaration with the container using cURL, use curl -sku admin:admin -H "Content-Type: application/json" -X POST https://localhost:8443/mgmt/shared/appsvcs/declare and then include the declaration.

Example declaration snippet using a RESTful client

To send a declaration from the container with a RESTful client like Postman, use the targetHost, targetUsername, and targetPassphrase parameters as shown in the following example (using values from your configuration). In this example, your declaration would continue after the last (schemaVersion) line.

{

     "class": "AS3",
     "action": "deploy",
     "targetHost": "192.0.2.76",
     "targetPort": 8443
     "targetUsername": "admin",
     "targetPassphrase": "admin",
     "declaration": {
         "class": "ADC",
         "schemaVersion": "3.0.0",
         ...
     }
}

Container-specific parameters

Parameter Options Required? Description/Notes
targetHost string YES IP address or host name of the target BIG-IP system to which you want to send the configuration.
targetPort integer NO TCP port number of management service on targetHost. If you do not specify a targetPort, AS3 uses a default of 0, meaning it will auto-discover the target port.
targetTokens object NO One or more HTTP headers (each a property, like ‘X-F5-Auth-Token’: ‘MF6APSRUYKTMSDBEOOEWLCNSO2’) you want to send with queries to the targetHost management service as authentication/authorization tokens
targetUsername string YES Username of the principal authorized to modify configuration of targetHost (may not include the character ‘:’). NOTE: This is generally not required to configure ‘localhost’ because client authentication and authorization precede invocation of AS3. It is also not required for any targetHost if you populate targetTokens.
targetPassphrase string YES Passphrase for targetUsername account. This is generally not required to configure ‘localhost’ and is not required when you populate targetTokens.

Example declaration snippet using cURL

To send a declaration from the container with cURL, use the same parameters as described in the preceding table. The rest of your declaration would continue after the last (schemaVersion) line.

curl -sku admin:admin -H "Content-Type: application/json" -X POST https://localhost:8443/mgmt/shared/appsvcs/declare ‘{
    "class": "AS3",
    "action": "deploy",
    "targetHost": "192.0.2.76",
    "targetUsername": "admin",
    "targetPassphrase": "admin",
    "declaration": {
        "class": "ADC",
        "schemaVersion": "3.0.0",
…}

Adding Base Authentication

To enable base authentication, which allows you to protect your container running AS3, you can COPY or MOUNT the conf and password files to the running container using the following instructions.

Notes and requirements for adding base authentication

  • You should be at least somewhat familiar with the Docker command line.
  • You should have knowledge of Apache .htpasswd for adding base authentication. See https://httpd.apache.org/docs/2.4/howto/auth.html.
  • While we include commands for Microsoft Windows in this section, getting paths and directories set up in Windows can be tricky, so we recommend using a Linux-based system to add basic authentication.
  • In our example, we are using hashed value for the password admin. We strongly recommend you use a different password. Use a htpasswd generator (such as http://www.htaccesstools.com/htpasswd-generator/) to generate a value for a stronger password.

  1. Choose a local directory that will be mounted as a volume for the container to handle authentication. From that directory, pull the AS3 image from Docker hub (see Downloading and starting the AS3 Docker container)

  2. Inside that root directory, create a new directory named basic-auth. You will create two sub-directories in this directory. If you want to use different names for your directories, you must modify the command to use the appropriate directories when you run the container.

    1. Inside the basic-auth directory you created, create a directory named auth directory.

    2. In the auth directory, create a file named basic.conf with the following content:

      AuthType basic
      AuthName "private area"
      AuthUserFile /etc/www/pass/.htpasswd-users
      Require valid-user
      
    3. In the basic-auth directory, create another directory named pass.

    4. In the auth directory, create a file named .htpasswd-users your user name and a hashed password. Again, this example uses admin for the password, use http://www.htaccesstools.com/htpasswd-generator/ to generate a hash for a stronger password.:

      admin:$apr1$DTbcp1qi$vJ2AXcB.Ma8zznKJLEXKv.
      
  3. Run AS3 container at the root directory. This maps the two directories you created to two directories inside the container for Apache.

    • If you are using a Linux-based system, use the following command: docker run -d -p 8443:443 -p 8080:80 -v `pwd`/basic-auth/auth/:/usr/local/apache2/conf/auth/ -v `pwd`/basic-auth/pass/:/etc/www/pass/ f5devcentral/f5-as3-container
    • If you are using Windows, use the following command: docker run -d -p 8443:443 -p 8080:80 -v %cd%/basic-auth/auth/:/usr/local/apache2/conf/auth/ -v %cd%/basic-auth/pass/:/etc/www/pass/ f5devcentral/f5-as3-container
  4. Open your RESTful API client such as Postman, and log with the basic Auth you just configured, in our example, using admin for the username and password.

  5. Test your docker container to get info from BIG-IP using step 3 of Downloading and starting the AS3 Docker container.

Full declaration using the AS3 container

This example uses a simple example declaration using the AS3 container.

{

    "class": "AS3",
    "action": "deploy",
    "targetHost": "192.0.2.76",
    "targetUsername": "admin",
    "targetPassphrase": "admin",
    "declaration": {
        "class": "ADC",
        "schemaVersion": "3.0.0",
        "id": "container",
        "label": "Sample 1 in a container",
        "remark": "Simple HTTP application with RR pool",
        "Sample_container": {
            "class": "Tenant",
            "A1": {
                "class": "Application",
                "template": "http",
                "serviceMain": {
                "class": "Service_HTTP",
                "virtualAddresses": [
                    "10.0.1.10"
                ],
                "pool": "web_pool"
                },
                "web_pool": {
                "class": "Pool",
                    "monitors": [
                        "http"
                    ],
                "members": [{
                    "servicePort": 80,
                    "serverAddresses": [
                        "192.0.1.10",
                        "192.0.1.11"
                    ]
                }]
                }
            }
        }
    }
}