NGINX Agent in a Container Environment
Learn how to use the NGINX Agent in a containerized environment.
Container Support
The NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances and must run in the same container to work. The NGINX Agent repository includes Dockerfiles that can be used to build custom container images. Images are created with an NGINX Open Source or NGINX Plus instance and are available for various Operating Systems.
The NGINX Agent bundled with NGINX Open Source Dockerfiles is available for the following base images:
- Alma Linux (8, 9)
- Alpine (3.14, 3.15, 3.16, 3.17)
- Amazon Linux (2)
- Oracle Linux (7, 8, 9)
- Rocky Linux (8, 9)
- Ubuntu (18.04, 20.04, 22.04)
The NGINX Agent bundled with NGINX Plus Dockerfiles is available for the following base images:
- Alpine Linux (3.13, 3.14, 3.15, 3.16)
- Amazon Linux (2)
- CentOS (7)
- Debian (bullseye-slim, buster-slim)
- Oracle Linux (7, 8)
- RHEL (7, 8, 9)
- SUSE (sles12sp5, sle15)
- Ubuntu (18.04, 20.04, 22.04)
Clone the NGINX Agent Repository
Using your preferred method, clone the NGINX Agent repository into your development directory. See Cloning a GitHub Repository for additional help.
Use the following command to clone the repository using the HTTPS method.
git clone https://github.com/nginx/agent.git
cd agent
Prepare your Environment
To build container images using scripts available in the NGINX Agent repository, you will need to install several packages. The steps outlined in this document provide installation instructions for distributions that use the apt
package manager (for example, for Debian, Ubuntu, etc.). For installations on other operating systems, please refer to the documentation within each prerequisite package. In some cases, it may help to update package source lists in your operating system before proceeding.
sudo apt update
Install make
Package
Start by installing the make
package, which will enable you to execute build targets within the Makefile
included in the NGINX Agent source code repository.
sudo apt install make
Install a Container Engine
A container engine will enable you to build images and run containers. NGINX Agent supports the Docker
and Podman
container engines. You will need to install the container engine that you plan to use. Most examples in this document are provided using the Docker
container engine, with the exception of example under the Rootless Containers section.
To install the Docker engine run the following command:
sudo apt install docker.io
To install the Podman engine run the following command:
sudo apt install podman
Build Container Images
Dockerfiles defining container images are located in the NGINX Agent Github repository. Note that docker build
commands must be run from the repository’s root directory. The NGINX Agent repository provides Makefile targets simplifying the image-building process. On some Operating Systems, make
commands must be executed with root privileges (running them with sudo
).
Build Images with NGINX Agent and NGINX Open Source
Prior to building an NGINX Agent bundled with NGINX Open Source image, an NGINX Agent binary must be built or downloaded.
You can download an appropriate binary from NGINX Agent Releases on GitHub. Copy the binary to the [PATH_TO_NGINX_AGENT_SRC_ROOT]/build
directory. If the directory doesn’t exist, you’ll need to create it. This is done automatically when choosing to build the binary from source.
The following command produces an Ubuntu base image. Setting the PACKAGE_NAME
environment variable is not necessary if you built the binary from source. When using a downloaded binary, do not include the extension of the package file name in the environment variable definition. Example PACKAGE_NAME=nginx-agent-2.26.2.jammy_amd64
.
PACKAGE_NAME=[NAME-OF-PACKAGE] make oss-image
To build the image using a different base image, replace the values for OS_RELEASE
and OS_VERSION
with the options from the following table:
OS_RELEASE | OS_VERSION |
---|---|
almalinux | 8, 9 |
alpine | 3.14, 3.15, 3.16, 3.17 |
amazonlinux | 2 |
oraclelinux | 7, 8, 9 |
rockylinux | 8, 9 |
ubuntu | 18.04, 20.04, 22.04 |
For example, to build an image for RockyLinux 9, use the following command. Replace OS_VERSION=9
with the desired version tag. See Supported Tags for version options.
PACKAGE_NAME=[NAME-OF-PACKAGE] OS_RELEASE=rockylinux OS_VERSION=9 make oss-image
Optional: Rather than specifying PACKAGE_NAME
or OS_RELEASE
on the command line, you may set these environment variables directly by editing the Makefile.
Build Images with NGINX Agent and NGINX Plus
Building an NGINX Agent bundled with NGINX Plus image requires an NGINX Plus license. NGINX Plus licenses are provided as .crt
and .key
files and must be renamed to nginx-repo.crt
and nginx-repo.key
, respectively. Begin by creating the build
directory under the NGINX Agent source root directory ([PATH_TO_NGINX_AGENT_SRC_ROOT]/build
).
In the NGINX Agent source root, run the following command:
mkdir build
mkdir build/certs
Copy the license and key files into the [PATH_TO_NGINX_AGENT_SRC_ROOT]/build/certs
directory.
cp [PATH_TO_LICENSE_CRT] build/certs/nginx-repo.crt
cp [PATH_TO_LICENSE_KEY] build/certs/nginx-repo.key
From the NGINX Agent source root directory, run the following command to build the image with an Ubuntu 22.04 LTS base
make image
To build the image using a different base image, substitute values for OS_RELEASE
and OS_VERSION
from the following table:
OS_RELEASE | OS_VERSION |
---|---|
amazonlinux | 2 |
ubuntu | 18.04, 20.04, 22.04 |
debian | bullseye-slim, buster-slim |
centos | 7 |
redhatenterprise | 7, 8, 9 |
alpine | 3.13, 3.14, 3.15, 3.16 |
oraclelinux | 7, 8 |
suse | sles12sp5, sle15 |
OS_RELEASE=[NAME_OF_OS] OS_VERSION=[VERSION_OF_OS] make image
Rootless Containers
NGINX Agent images can be built and run as rootless containers, which run without root privileges to the host Operating System.
To build a Podman image with an Ubuntu 22.04 base, execute the following command from the NGINX Agent source root directory. Altering the OS_RELEASE
and OS_VERSION
variables with values from the table above will build images using other supported Operating Systems.
CONTAINER_CLITOOL=podman make image
Unprivileged Containers
Certain system architectures, like F5 Distributed Cloud and OpenShift, require that processes run in containers that don’t allow root privileges. Dockerfiles in the NGINX Agent repository can be modified to support such environments.
Modify Dockerfile to Support Unprivileged Use
To modify a Dockerfile to run NGINX and NGINX Agent in an unprivileged manner, paste the following RUN
directly below the Dockerfile’s primary RUN
statement.
RUN sed -i 's,listen 80,listen 8080,' /etc/nginx/conf.d/default.conf \
&& sed -i '/user nginx;/d' /etc/nginx/nginx.conf \
&& sed -i 's,/var/run/nginx.pid,/tmp/nginx.pid,' /etc/nginx/nginx.conf \
&& sed -i "/^http {/a \ proxy_temp_path /tmp/proxy_temp;\n client_body_temp_path /tmp/client_temp;\n fastcgi_temp_path /tmp/fastcgi_temp;\n uwsgi_temp_path /tmp/uwsgi_temp;\n scgi_temp_path /tmp/scgi_temp;\n" /etc/nginx/nginx.conf \
&& chown -R nginx:nginx /var/cache/nginx \
&& chmod -R go+rw /var/cache/nginx \
&& chown -R nginx:nginx /etc/nginx \
&& chmod -R go+rw /etc/nginx \
&& chown -R nginx:nginx /var/log/nginx \
&& chmod -R go+rw /var/log/nginx \
&& chown -R nginx:nginx /var/run/nginx-agent \
&& chmod -R go+w /var/run/nginx-agent \
&& ln -sf /dev/stdout /var/log/nginx-agent/agent.log
This command alters the Dockerfile in the following ways:
- Changes the listen port from
80
to8080
. - Removes the
user nginx;
directive from nginx.conf. - Moves the
nginx.pid
file from/var/run
to/tmp
. - Moves all nginx temporary directories from
/var/run
to/tmp
. - Changes ownership and read/write permissions for several directories that NGINX and NGINX Agent need to write to.
- Links the
agent.log
file to stdout, while allowingaccess.log
anderror.log
to stay in/var/log/nginx
to be read by NGINX Agent.
Standalone NGINX Unprivileged Dockerfiles
Standalone NGINX (Without NGINX Agent) unprivileged container images can be built using Dockerfiles available in this GitHub repository.
Configure NGINX Agent
Once you have successfully built the image, you need to run a container to configure NGINX Agent.
docker run -d --name nginx-agent-container <NAME-OF-PACKAGE>
Once your container is running, follow the steps in our Install and Configure guide.
Supported Environments
Images built with NGINX Agent Dockerfiles can run in the following container environments:
- containerd
- CRI-O
Container Metrics
To collect container-related metrics, NGINX Agent uses available cgroup files to calculate statistics like CPU and memory usage.
Supported cgroups
NGINX Agent supports both versions of cgroups.
- https://www.kernel.org/doc/Documentation/cgroup-v1/
- https://www.kernel.org/doc/Documentation/cgroup-v2.txt
Unsupported Metrics
The following system metrics are not supported in container environments. NGINX Agent returns no values for these metrics when run within a container.
- system.cpu.idle
- system.cpu.iowait
- system.cpu.stolen
- system.mem.buffered
- system.load.1
- system.load.5
- system.load.15
- system.disk.total
- system.disk.used
- system.disk.free
- system.disk.in_use
- system.io.kbs_r
- system.io.kbs_w
- system.io.wait_r
- system.io.wait_w
- system.io.iops_r
- system.io.iops_w
Memory Metrics
If no memory limit is set when starting a container, the memory limit shown in metrics for the container will equal the total memory of the host system.
Swap Memory Metrics
If a warning message similar to the following is seen in the NGINX Agent logs, the swap memory limit for the container is greater than the swap memory for the host system:
Swap memory limit specified for the container, ... is greater than the host system swap memory ...
The system.swap.total
metric for the container matches the total swap memory in the host system instead of the swap memory limit specified when starting the container.
If a warning message similar to the following example is seen in the NGINX Agent logs, the host system does not have cgroup swap limit capabilities enabled.
Unable to collect Swap metrics because the file ... was not found
When using Docker, follow these steps to enable swap memory metrics:
Check if cgroup swap limit capabilities are enabled:
$ docker info | grep swap
WARNING: No swap limit support
Enable cgroup swap limit capabilities by referring to this guide.