• 1. Overview
  • 1.1. NGINX Controller Agent Inside Docker Container
  • 1.2. Standalone Mode
  • 1.3. Current Limitations
• 2. How to Build and Run a Controller enabled NGINX image
  • 2.1. Building a Controller-enabled image with NGINX
  • 2.2. Running a Controller-enabled NGINX Docker Container
  • 3.0 Adding agent during container run
• Support

We are actively working on improving support for Docker with NGINX Controller. The following is a set of guidelines that you can use today as we enhance the experience.

1. Overview

NGINX Controller is a centralized monitoring and management control-plane solution for the NGINX data plane. Controller is developed and maintained by Nginx Inc. — the company behind the NGINX software.

With Controller it is possible to collect and aggregate metrics across NGINX instances and your applications however they run. Presenting a coherent set of visualizations of the key NGINX performance data, such as active connections or requests per second. It is also easy to quickly check for any performance degradations, traffic anomalies, and get a deeper insight into the NGINX configuration in general.

In order to use Controller, a small Python-based agent software Controller Agent should be installed inside the container alongside NGINX Plus.

The official documentation for Controller is available here.

Guidance around NGINX Plus is available here. Note: When building NGINX Plus into a container, be certain to remove repository credentials from your container.

1.1. NGINX Controller Agent Inside Docker Container

The Controller Agent can be deployed in a Docker environment to monitor and / or configure NGINX processes inside Docker containers. The agent can collect most of the metrics.

The "agent-inside-the-container" is currenly the only mode of operation. In other words, the agent should be running in the same container as the NGINX process being managed / monitored. For more information, please refer to our Controller Dockerfile repository.

1.2. Standalone Mode

By default the agent will try to determine the OS hostname on startup. The hostname is used to generate a UUID to uniquely identify the NGINX instance in NGINX Controller. When the Agent is run inside of a container the hostname is the shortened Docker Container ID on the host where the container is running.

This means that each new container started from a Controller-enabled Docker image will be reported as a standalone system in the Controller Console. This is the recommended configuration, as Controller will aggregate metrics across your instances based on the application, application component, location, environment, and so on.

or environment settings can be passed at contianer launch time:

• Use the -e option with docker run as in

  docker run --name mynginx1 -e ENV_API_KEY=1234567890 -e hostname=my-instance-123 -d nginx-agent
  

1.3. Current Limitations

The following list summarizes existing limitations of monitoring containers with NGINX Controller:

• The agent can only monitor NGINX from inside the container. It is not currently possible to run the agent in a separate container and monitor the neighboring containers running NGINX.

2. How to Build and Run a Controller enabled NGINX image

2.1. Building a Controller-enabled image with NGINX

(Note: If you are new to Docker, here's how to install Docker Engine on various OS.)

Note Before proceeding, you must: install NGINX Controller, download your certificate and key for NGINX Plus, obtain the api key for your NGINX Contoller instance.

Here's how you can build the Docker image with the Contorller Agent inside, based on the official NGINX image:

git clone https://github.com/nginxinc/docker-nginx-controller.git

cd docker-nginx-controller

copy your NGINX Plus repositry certificate and key to the cloned folder.
Edit the Dockerfile with your API_KEY and ENV_CONTROLLER_URL

docker build --build-arg CONTROLLER_URL=<url>/1.4 --build-arg API_KEY='abcdefxxxxxx' -t nginx-agent .

After the image is built, check the list of Docker images:

docker images

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
nginx-agent       latest              d039b39d2987        3 minutes ago       241.6 MB

2.2. Running a Controller-enabled NGINX Docker Container

To start a container from the new image, use the command below:

docker run --name mynginx1 -e ENV_API_KEY=1234567890 -d nginx-agent

After the container has started, you may check its status with docker ps:

docker ps

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
7d7b47ba4c72        nginx-agent       "/entrypoint.sh"    3 seconds ago       Up 2 seconds        80/tcp, 443/tcp     mynginx1

and you can also check docker logs:

docker logs 7d7b47ba4c72

starting nginx ...
updating /etc/controller-agent/agent.conf ...
---> using api_key = 1234567890
starting controller-agent ...

Check what processes have started:

docker exec 7d7b47ba4c72 ps axu

USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.1   4328   676 ?        Ss   19:33   0:00 /bin/sh /entrypoint.sh
root         5  0.0  0.5  31596  2832 ?        S    19:33   0:00 nginx: master process nginx -g daemon off;
nginx       11  0.0  0.3  31988  1968 ?        S    19:33   0:00 nginx: worker process
nginx       65  0.6  9.1 111584 45884 ?        S    19:33   0:06 controller-agent

If you see the controller-agent process, it all went smoothly, and you should see the new container in the Controller interface in a minute or so.

Check the Controller Agent log:

docker exec 7d7b47ba4c72 tail /var/log/contorller-agent/agent.log

2016-08-05 19:49:39,001 [65] supervisor agent started, version=0.37-1 pid=65 uuid=<..>
2016-08-05 19:49:39,047 [65] nginx_config running nginx -t -c /etc/nginx/nginx.conf
2016-08-05 19:49:40,047 [65] supervisor post https://<controller url>:8443/<..>/ffeedd0102030405060708/agent/ 200 85 4 0.096
2016-08-05 19:50:24,674 [65] bridge_manager post https://<controller url>:8443/<..>/ffeedd0102030405060708/update/ 202 2370 0 0.084

When you're done with the container, you can stop it like the following:

docker stop 7d7b47ba4c72

To check the status of all containers (running and stopped):

docker ps -a

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                        PORTS               NAMES
7d7b47ba4c72        nginx-agent       "/entrypoint.sh"         22 minutes ago      Exited (137) 19 seconds ago                       mynginx1

3.0 Adding agent during container run

An alternate way to handle agent within Containers is to include the necessary Controller Agent commands in the run command for the container. This way you don't have to build the agent into your Container prior to running.

Alternate Dockerfile

# Start container with environment variables for CTRL_HOST and API_KEY
#
# docker build -t nginx-ctrl .
# docker run --name apigw --hostname apigw -e CTRL_HOST=10.20.30.40 -e API_KEY=deadbeef -d -P nginx-ctrl
 
FROM nginx-plus
 
# Install everything we will need to install the Controller Agent so that the container can start quickly
RUN apt-get update && apt install -y curl python gnupg2 procps dh-python distro-info-data libmpdec2 libpython3-stdlib libpython3.5-minimal libpython3.5-stdlib lsb-release python3 python3-minimal python3.5 python3.5-minimal
 
EXPOSE 80 443 8080
STOPSIGNAL SIGTERM
 
WORKDIR /controller
RUN printf "curl -skSL https://\$CTRL_HOST:8443/1.4/install/controller/ | bash -s - -y\nnginx -g 'daemon off;'" > start
CMD ["sh", "/controller/start"]

It takes 1-2 minutes to start the container. After docker run � use docker logs --follow CONTAINER to watch install/startup progress.

Support

This project is not covered by the NGINX Plus support contract

This is currently considered experimental it has been validated with Controller 2.8+ agent and was adapted from the Amplify guidance.