Creating a Docker Container to Run AS3 Declarations

This guide will take you through some very basic docker, Python, and  F5 AS3 configuration to create a single-function container that will update a pre-determined BIG-IP using an AS3 declaration stored on Github.

While it’s far from production ready, it might serve as a basis for more complex configurations, plus it illustrates nicely some technology you can use to automate BIG-IP configuration using AS3, Python and  containers.

I'm starting with a running BIG-IP - in this case a VE running on the Google Cloud Platform, with the AS3 wroker installed and provisioned, plus a couple of webservers listening on different ports. 

First we’re going to need a host running docker. Fire up an instance in on the platform of your choice – in this example I’m using Ubuntu 18.04 LTS  on  the Google Cloud platform – that’s purely from familiarity – anything that can run Docker will do. 

The install process is well documented but looks a bit like this:

$ sudo apt-get update

$ sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

$ sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

$sudo apt-get update

$ sudo apt-get install docker-ce docker-ce-cli containerd.io

It's worth adding your user to the docker  group to avoid repeadly forgetting to type sudo (or is that just me?)

$ sudo usermod -aG docker $USER

Next let's test it's all working:

$ docker run hello-world

Next let’s take a look at the AS3 declaration, as you might expect form me by now, it’s the most basic version – a simple HTTP app, with two pool members. The beauty of the AS3  model, of course,  is that it doesn’t matter how complex your declaration is, the implementation is always the same. So you could take a much more involved declaration and just by changing the file the python script uses, get a more complex configuration.

{
     "class": "AS3",
     "action": "deploy",
     "persist": true,
     "declaration": {
         "class": "ADC",
         "schemaVersion": "3.0.0",
         "id": "urn:uuid:33045210-3ab8-4636-9b2a-c98d22ab915d",
         "label": "Sample 1",
         "remark": "Simple HTTP Service with Round-Robin Load Balancing",
         "Sample_01": {
             "class": "Tenant",
             "A1": {
                 "class": "Application",
                 "template": "http",
                 "serviceMain": {
                     "class": "Service_HTTP",
                     "virtualAddresses": [
                         "10.138.0.4"
                     ],
                     "pool": "web_pool"
                 },
                 "web_pool": {
                     "class": "Pool",
                     "monitors": [
                         "http"
                     ],
                     "members": [
                         {
                             "servicePort": 8080,
                             "serverAddresses": [
                                 "10.138.0.3"
                             ]
                         },
             {
                             "servicePort": 8081,
                             "serverAddresses": [
                                 "10.138.0.3"
                             ]
                         }
                     ]
                 }
             }
         }
     }
 }

Now we need some python code to fire up our request. The code below is absolutely a minimum viable set that’s been written for simplicity and clarity and does minimal error checking. There are more ways to improve it that lines of code in it, but it will get you started.


#Python Code to run an as3 declaration
#
import requests
import os
from requests.auth import HTTPBasicAuth

# Get rid of annoying insecure requests waring
from requests.packages.urllib3.exceptions import InsecureRequestWarning
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

# Declaration location
GITDRC = 'https://raw.githubusercontent.com/RuncibleSpoon/as3/master/declarations/payload.json'
IP = '10.138.0.4'
PORT = '8443'
USER = os.environ['XUSER']
PASS = os.environ['XPASS']
URLBASE = 'https://' + IP + ':' + PORT
TESTPATH = '/mgmt/shared/appsvcs/info'
AS3PATH = '/mgmt/shared/appsvcs/declare'

print("########### Fetching Declaration ###########")
d = requests.get(GITDRC)

# Check we have connectivity and AS3 is installed
print('########### Checking that AS3 is running on ', IP ,' #########')
url = URLBASE + TESTPATH

r = requests.get(url, auth=HTTPBasicAuth(USER, PASS), verify=False)



if r.status_code == 200: 
   data = r.json() 
   if data["version"]: 
      print('AS3 version is ', data["version"]) 
      print('########## Runnig Declaration #############') 
      url = URLBASE + AS3PATH 
      headers = { 'content-type': 'application/json', 
              'accept': 'application/json' } 
      r = requests.post(url, auth=HTTPBasicAuth(USER, PASS), verify=False, 
         data=d.text, headers=headers) 
      print('Status Code:', r.status_code,'\n', r.text) 
   else:
      print('AS3 test to ',IP, 'failed: ', r.text)

This simple python code will pull down an S3 declaration from GitHub using the 'requests' Python library, and the GITDRC variable, connect to a specific BIG-IP, test  it’s running AS3 (see here for AS3 setup instructions), and then apply the declaration. It will give you some tracing output, but that’s about it. 

There are couple of things to note about IP’s, users, and passwords:


IP = '10.138.0.4'
PORT = '8443'
USER = os.environ['XUSER']
PASS = os.environ['XPASS'

As you can see, I’ve  set the IP and port statically and the username and passwords are pulled in from environment variables in the container.  We’ll talk more about the environment variables below, but this is more a way to illustrate your options than design advice. 

Now we need to build a container to run it in. Containers are relatively easy to build with just a Dockerfile and a few more test files in a directory. Here's the docker file:


FROM python:3
WORKDIR /usr/src/app
ARG Username=admin
ENV XUSER=$Username
ARG Password=admin
ENV XPASS=$Password
# line bleow is not actually used - see comments - but oy probably is a better way 
ARG DecURL=https://raw.githubusercontent.com/RuncibleSpoon/as3/master/declarations/payload.json
ENV Declaration=$DecURL
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
ENTRYPOINT [ "python", "./as3.py" ]

You can see a couple of ARG and ENV statements , these simple set the environment variables that we’re (somewhat arbitrarily) using in the python script. Further more we’re going to override them in then build command later. It’s worth noting this isn’t a way to obfuscate passwords, they are exposed by a simple

$ docker image history

command that will expose all sorts of things about the build of the container, including the environment variables passes to it.

This can be overcome by a multi-stage build – but proper secret management is something you should explore – and comment below if you’d like some examples.

What’s this requirements.txt file mentioned in the Dockerfile it’s just a manifest to the install of the python package we need:

# This file is used by pip to install required python packages
# Usage: pip install -r requirements.txt
# requests package
requests==2.21.0

With our Dockerfile, requirements.txt and as3.py files in a directory we're ready to build a container - in this case I'm going to pass some environment variables into the build to be incorporated in the image - and replace the ones we have set in the Dockerfile: 

$ export XUSER=admin
$ export XPASS=admin

Build the container (the -t flag names and tags your container, more of which later):

$ docker build  -t runciblespoon/as3_python:A --build-arg Username=$XUSER --build-arg Password=$XPASS   .

The first time you do this there will be some lag as files for the python3 source container are downloaded and cached, but once it has run you should be able to see your image:

$ docker image list
REPOSITORY                 TAG                 IMAGE ID            CREATED              SIZE

runciblespoon/as3_python   A                   819dfeaad5eb        About a minute ago   936MB

python                     3                   954987809e63        42 hours ago         929MB

hello-world                latest              fce289e99eb9        3 months ago         1.84kB

Now we are ready to run the container  maybe a good time for a 'nothing up my sleeve' moment - here is the state of the BIG-IP before hand

Now let's run the container from our image.  The -tty flag attached a pseudo terminal for output and --rm deletes the container afterwards:

$ docker run  --tty --rm  runciblespoon/as3_python:A

########### Fetching Declaration ###########

########### Checking that AS3 is running on  10.138.0.4  #########

AS3 version is  3.10.0

########## Runing Declaration #############

Status Code: 200

 {"results":[{"message":"success","lineCount":23,"code":200,"host":"localhost","tenant":"Sample_01","runTime":929}],"declaration":{"class":"ADC","schemaVersion":"3.0.0","id":"urn:uuid:33045210-3ab8-4636-9b2a-c98d22ab915d","label":"Sample 1","remark":"Simple HTTP Service with Round-Robin Load Balancing","Sample_01":{"class":"Tenant","A1":{"class":"Application","template":"http","serviceMain":{"class":"Service_HTTP","virtualAddresses":["10.138.0.4"],"pool":"web_pool"},"web_pool":{"class":"Pool","monitors":["http"],"members":[{"servicePort":8080,"serverAddresses":["10.138.0.3"]},{"servicePort":8081,"serverAddresses":["10.138.0.3"]}]}}},"updateMode":"selective","controls":{"archiveTimestamp":"2019-04-26T18:40:56.861Z"}}}

Success, by the looks of things. Let's check the BIG-IP:

running our container has pulled down the AS3 declaration, and applied it to the BIG-IP. This same container can now be run repeatedly - and only the AS3 declaration stored in git (or anywhere else your container can get it from) needs to change. 

So now you have this container running locally you might want ot put it somewhere. Docker hub is a good choice and lets you create  one private repository for free. Remember this container image has credentials, so keep it safe and private. 

Now the reason for the -t runciblespoon/as3_python:A  flag earlier. My docker hub user is "runciblespoon" and my private repository is as3_python. So now all i need ot do is login to Docker Hub and push my image there:

$ docker login
$ docker push runciblespoon/as3_python:B

Now I can go to any other host that runs Docker, login to Docker hub and run my container:

$ docker login
$ docker run --tty --rm runciblespoon/as3_python:A
Unable to find image 'runciblespoon/as3_python:A' locally
B: Pulling from runciblespoon/as3_python
...
########### Fetching Declaration ###########

Docker will pull down my container form my private repo and run it, using the AS3 declaration I've specified. If I want to change my config, I just change the declaration and run it again.

Hopefully this article gives you a starting point to develop your own containers, python scripts, or AS3 declarations, I'd be interested in what more you would like to see, please ask away in the comments section.

Updated Jun 06, 2023
Version 2.0

Was this article helpful?

4 Comments

  • Hi,

    Very nice article! Not easy to figure out for beginner like me, so have few questions.

    I am maybe wrong but there are some missing pieces and small errors:

    In installation section after

    sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
    it seems that
    sudo apt-get update
    is missing. Without this step Docker install failed on my side (but I am using Ubuntu 16.0.4)

    In Python script there is typo (at least without correction I was not able to run this script)

     Check we have connectivity and AS3 is installed
    print(' Checking that AS3 is running on ', IP ,' ')
    url = URLBASE + TESTPATH>
    

    I changed it to:

    url = URLBASE + TESTPATH
    - so > should be removed?

    I was not as well sure how to perform docker build command. My steps were:

    • Created as3 folder in home
    • Placed as3.py, Dockerfile and requirements.txt in this folder
    • cd as3
    • Run your version of command - it failed with message about missing arguments (if I can recall) So I used this version (added dot):
      docker build . -t runciblespoon/as3_python:A --build-arg Username=$XUSER --build-arg Password=$XPASS

    Wonder if my corrections are OK?

    I have as well few questions about how your example can be modified. Just would like to make it more generic/universal:

    Passing BIG-IP MGMT IP:port to the Python script. I think it can be done using similar approach as for Username and Password via

    --build-arg
    , just not sure what needs to be modified. My guess is I should add something like that in Dockerfile:

    ARG Mgmntip=10.10.10.10

    ENV XIP=$Mgmntip

    then in python script:

    IP = os.environ['XIP']

    and finally in

    docker build
    command add
    --build-arg Mgmtip=192.168.10.1

    I am not sure if this is necessary to use

    export XIP=192.168.10.1
    and then in
    --build-arg Mgmtip=$XIP
    ?

    If above is correct then I assume that same approach can be taken to pass GITDRC? Something like (in python script):

    GITDRC = 'https://raw.githubusercontent.com/RuncibleSpoon/as3/master/declarations/' + os.environ['XJSON']

    of course after XJSON is set in Dockerfile and passed via

    --build-arg

    Last but not least, in Dockerfile there is:

    ARG DecURL=https://raw.githubusercontent.com/RuncibleSpoon/as3/master/declarations/payload.json
    ENV Declaration=$DecURL
    

    Is that used anywhere?

    Sorry for so many questions but as I said it's all new to me.

    EDIT: You can disregard my questions about passing values at

    docker build
    stage - checked and it's working 🙂

    But it is not as universal as I expected, so question is if there is a way to pass arguments at the

    docker run
    stage?

    EDIT 2: Quite stupid to answer own questions 🙂 Figured out how to pass all necessary vars at

    docker run
    stage, just used
    --env-file
    , working like a charm!

    Piotr

  • Hey - thanks for this comment. I'm travelling right now but will take a proper look and amend the article where needed.

     

  • Hey Piotr, I've fixed the errors you spotted - and you are right, one of the AS3 URL declarations is redundant.

     

    I think that actually it would be better to have the URL of the AS3 declaration as an argument in the docker file - even if the source is from an environment variable or an argument passed in at the docker build stage.

     

    I've left it in but commented it out with an explanation - as otherwise future readers will be really confused.

     

    Thanks for taking the time on this.