How Do I Install the Application Study Tool in an Air-Gapped Environment?

The Application Study Tool (AST) from F5 is a powerful tool to help you with monitoring and observability of your BIG-IP ecosystem. It provides valuable insights into the performance of your BIG-IP, the applications it delivers, potential threats, and traffic patterns. 

AST runs as a set of containers, and most deployments simply use "docker pull" to download the required container images from the Internet and run them locally (on “the AST host”). However, some customer environments have firewall restrictions that block most Internet destinations and only whitelist specific sites. For these environments, whitelisting github.com, docker.io, and ghcr.io (all on port 443) will allow you to download the configuration and container images you need to run the Application Study Tool. 

However, other environments are completely "air-gapped" with no connectivity to the outside world whatsoever. To run the tool in an environment like these, you'll need another way to get the container images onto the AST host. 

The following steps will guide you through this process. This guide assumes Docker (or another compatible container engine, such as Podman) is already installed on the AST host, and it requires access to another machine that does have connectivity to the Internet, at least to github.com, docker.io, and ghcr.io. You will also need a way to get files from this Internet-connected machine to the air-gapped AST host. This could be a local network connection, a shared network file system, or even a USB drive that can plug into both systems with read and write permissions.

Note: this guide includes several Docker commands as examples. All assume you have permission to run Docker directly. If your access requires “sudo” before the command, add this to the beginning of all Docker commands when running the command examples below.

 

Determining Whether Your Environment is Air-Gapped

You may already know what Internet connectivity you have in place from your environment, but if you need to confirm access to the specific container registries used by the Application Study Tool, you can test by running the following commands: 

$ curl https://docker.io

This will determine basic connectivity to Docker Hub, the container repository used for the Grafana and Prometheus images. 

$ docker pull grafana:latest

This tests your environment’s ability to download (or "pull") a container image from Docker Hub. Certain firewall configurations permit the prior step (curl) but block this one since it is attempting to download binary content. 

$ docker pull ghcr.io/f5devcentral/application-study-tool/otel_custom_collector:latest

This tests your environment’s ability to download a container image from the GitHub Container Registry. This is a different registry from Docker Hub and is where the AST Otel Collector container image is hosted. 

If all the above commands succeed, you already have the Internet connectivity you need and, most likely, do not need the guidance in this article. Simply running "docker compose up" should download the needed images from their respective Internet-based repositories and run them on your target system.

If one of more of the above commands fail, you must either establish the required connectivity so the above commands succeed (which, depending on your network configuration, organizational policies, level of effort required, personal preferences, etc. might be unfeasible) or use the steps outlined below to run AST in an air-gapped environment.

 

What is a Container Image?

Before we go any further, let's quickly cover what a container image is. It is not simply a self-contained file that can be moved around with simple copy commands; it is a multi-part collection of data with assets stored in various places on the host’s storage system. A container requires a container engine, such as Docker, Podman, Containerd, etc., to list it in a container CLI (i.e., Docker) and run it.

• For a more in-depth understanding of this concept, see Where Are Docker Images Stored? 
• For a more general explanation of container images, their contents, advantages, etc., see What is an image?

 

Step 1: Clone the Git Repo from an Internet-Connected System

Now that we've covered some basic concepts and established your need to run the Application Study Study Tool in an air-gapped environment, you’ll need a local copy of the Git repository. This contains all the configuration files and text-based assets required to run the tool. You can retrieve this using the Internet-connected system and then move it over to the air-gapped machine. 

From the web browser, go to the Application Study Tool repo page, click on the green “<> Code” button and select “Download ZIP” to download repo as a .zip file.

If a web browser is not available and you only have command line access from the Internet-connected system, you can clone the repo from the command line by running the following command:

$ git clone https://github.com/f5devcentral/application-study-tool.git

Next, use tar or zip to compress it into a single file. There are several ways to do this, including the steps found in this guide: https://www.redhat.com/en/blog/taming-tar-command

 

Step 2: Download the Required Container Images from the Internet-Connected System

If Docker is not already installed on this system, first perform the following steps to install it: https://docs.docker.com/engine/install/ 

Now, run the following commands to download the required images to this machine: 

$ docker pull prom/prometheus:v2.54.1
$ docker pull grafana/grafana:11.2.0
$ docker pull ghcr.io/f5devcentral/application-study-tool/otel_custom_collector:v0.9.4
$ docker pull python:3.12.6-slim-bookworm

(The above instructions specify current versions of the Prometheus, Grafana, Otel Collector , and Python containers as of the writing of this article. Your deployment may use different versions of these packages.)

 

Step 3: Export the Container Images as TAR Files

Export the container images as tar files using the below commands: 

$ docker save prom/prometheus > prometheus.tar
$ docker save grafana/grafana > grafana.tar
$ docker save ghcr.io/f5devcentral/application-study-tool/otel_custom_collector > application-study-tool_otel-collector_1.tar
$ docker save python > python.tar

 

Step 4: Move the ZIP and TAR Files to the AST Host

All of these files (the Git repository zip file and the three container image tar files) now need to be moved to the machine that will run the Application Study Tool. As discussed earlier, this could be accomplished by network file transfer, shared storage, a USB drive, or any other method of moving files from the Internet-connected host to the AST host.

The Git repo zip file should be copied to your preferred location on the AST host. This will be the directory containing the application's configuration files and will be your working directory for launching the tool.

The three container tar files can be copied to any directory on the AST host where you have write access, but be sure to note their new location.

 

Step 5: Import the TAR Files as Container Images on the AST Host

Import the tar files to Docker by running the following commands: 

$ docker load -i /path/to/tarfile/grafana.tar
$ docker load -i /path/to/tarfile/prometheus.tar
$ docker load -i /path/to/tarfile/application-study-tool_otel-collector_1.tar
$ docker load -i /path/to/tarfile/python.tar

You are now ready to run these container images on your AST host. Navigate to the Application Study Tool directory and follow the Application Study Tool installation instructions to configure and run the Application Study Tool.