NGINX Full Version

Building a Docker Image of NGINX Plus with NGINX Agent for Kubernetes

2 people working together to build a Docker Image of NGINX Plus with NGINX Agent for Kubernetes

F5 NGINX Management Suite is a family of modules for managing the NGINX data plane from a single pane of glass. By simplifying management of NGINX Open Source and NGINX Plus instances, NGINX Management Suite simplifies your processes for scaling, securing, and monitoring applications and APIs.

You need to install the NGINX Agent on each NGINX instance you want to manage from NGINX Management Suite, to enable communication with the control plane and remote configuration management.

For NGINX instances running on bare metal or a virtual machine (VM), we provide installation instructions in our documentation. In this post we show how to build a Docker image for NGINX Plus and NGINX Agent, to broaden the reach of NGINX Management Suite to NGINX Plus instances deployed in Kubernetes or other microservices infrastructures.

There are three build options, depending on what you want to include in the resulting Docker image:


We provide a GitHub repository of the resources you need to create a Docker image of NGINX Plus and NGINX Agent, with support for version 2.8.0 and later of the Instance Manager module from NGINX Management Suite.

To build the Docker image, you need:

To run the Docker image, you need:

Building the Docker Image

Follow these instructions to build the Docker image.

  1. Clone the GitHub repository:

    $ git clone 
    Cloning into 'NGINX-Demos'... 
    remote: Enumerating objects: 126, done. 
    remote: Counting objects: 100% (126/126), done. 
    remote: Compressing objects: 100% (85/85), done. 
    remote: Total 126 (delta 61), reused 102 (delta 37), pack-reused 0 
    Receiving objects: 100% (126/126), 20.44 KiB | 1.02 MiB/s, done. 
    Resolving deltas: 100% (61/61), done.
  2. Change to the build directory:

    $ cd NGINX-Demos/nginx-agent-docker/
  3. Run docker ps to verify that Docker is running and then run the script to include the desired software in the Docker image. The base options are:

    • ‑C – Name of the NGINX Plus license certificate file (nginx-repo.crt in the sample commands below)
    • ‑K – Name of the NGINX Plus license key file (nginx-repo.key in the sample commands below)
    • ‑t – The registry and target image in the form


      (registry.ff.lan:31005/nginx-plus-with-agent:2.7.0 in the sample commands below)

    • ‑n – Base URL of your NGINX Management Suite instance (https://nim.f5.ff.lan in the sample commands below)

    The additional options are:

    • ‑d – Add data‑plane support for the developer portal when using NGINX API Connectivity Manager
    • ‑w – Add NGINX App Protect WAF

    Here are the commands for the different combinations of software:

    • NGINX Plus and NGINX Agent:

      $ ./scripts/ -C nginx-repo.crt -K nginx-repo.key \
      -t registry.ff.lan:31005/nginx-plus-with-agent:2.7.0 \
      -n https://nim.f5.ff.lan
    • NGINX Plus, NGINX Agent, and NGINX App Protect WAF (add the ‑w option):

      $ ./scripts/ -C nginx-repo.crt -K nginx-repo.key \
      -t registry.ff.lan:31005/nginx-plus-with-agent:2.7.0 -w \
      -n https://nim.f5.ff.lan
    • NGINX Plus, NGINX Agent, and developer portal support (add the ‑d option):

      $ ./scripts/ -C nginx-repo.crt -K nginx-repo.key \ 
      -t registry.ff.lan:31005/nginx-plus-with-agent:2.7.0 -d \ 
      -n https://nim.f5.ff.lan
  4. Here’s a sample trace of the build for a basic image. The Build complete message at the end indicates a successful build.

    $ ./scripts/ -C nginx-repo.crt -K nginx-repo.key -t registry.ff.lan:31005/nginx-plus-with-agent:2.7.0 -n https://nim.f5.ff.lan 
    => Target docker image is nginx-plus-with-agent:2.7.0 
    [+] Building 415.1s (10/10) FINISHED 
    => [internal] load build definition from Dockerfile
    => transferring dockerfile: 38B
    => [internal] load .dockerignore 
    => transferring context: 2B 
    => [internal] load metadata for
    => [auth] library/centos:pull token for
    => CACHED [1/4] FROM /centos:7@sha256:be65f488b7764ad3638f236b7b515b3678369a5124c47b8d32916d6487418ea4
    => [internal] load build context 
    => transferring context: 69B 
    => [2/4] RUN yum -y update  && yum install -y wget ca-certificates epel-release curl  && mkdir -p /deployment /etc/ssl/nginx  && bash -c 'curl -k $NMS_URL/install/nginx-agent | sh' && echo "A  299.1s 
    => [3/4] COPY ./container/ /deployment/
    => [4/4] RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt  --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key  set -x  && chmod +x /deployment/ &  102.4s  
    => exporting to image 
    => exporting layers 
    => writing image sha256:9246de4af659596a290b078e6443a19b8988ca77f36ab90af3b67c03d27068ff 
    => naming to registry.ff.lan:31005/nginx-plus-with-agent:2.7.0 
    => Build complete for registry.ff.lan:31005/nginx-plus-with-agent:2.7.0

    Running the Docker Image in Kubernetes

    Follow these instructions to prepare the Deployment manifest and start NGINX Plus with NGINX Agent on Kubernetes.

    1. Using your favorite editor, open manifests/1.nginx-with-agent.yaml and make the following changes:

      • In the spec.template.spec.containers section, replace the default image name (your.registry.tld/nginx-with-nim2-agent:tag) with the Docker image name you specified with the ‑t option in Step 3 of the previous section (in our case, registry.ff.lan:31005/nginx-plus-with-agent:2.7.0):

              - name: nginx-nim
                image: your.registry.tld/nginx-with-nim2-agent:tag
      • In the spec.template.spec.containers.env section, make these substitutions in the value field for each indicated name:

        • NIM_HOST – (Required) Replace the default nginx-nim2.nginx-nim2 with the FQDN or IP address of your NGINX Management Suite instance (in our case nim2.f5.ff.lan).
        • NIM_GRPC_PORT – (Optional) Replace the default 443 with a gRPC port number.
        • NIM_INSTANCEGROUP – (Optional) Replace the default lab with the instance group to which the NGINX Plus instance belongs.
        • NIM_TAGS – (Optional) Replace the default preprod,devops with a comma‑delimited list of tags for the NGINX Plus instance.
        • NIM_WAF and NIM_WAF_PRECOMPILED_POLICIES – (Required if NGINX App Protect WAF is not included in the image) Replace the default true with false.
                - name: NIM_HOST
                  value: "nginx-nim2.nginx-nim2"
                - name: NIM_GRPC_PORT
                  value: "443"
                - name: NIM_INSTANCEGROUP
                  value: "lab"
                - name: NIM_TAGS
                  value: "preprod,devops"
                - name: NAP_WAF
                  value: "true"
                - name: NAP_WAF_PRECOMPILED_POLICIES
                  value: "true"
    2. Run the script as indicated to apply the manifest and start two pods (as specified by the replicas: 2 instruction in the spec section of the manifest), each with NGINX Plus and NGINX Agent:

      $ ./scripts/ start
      $ ./scripts/ stop
    3. Verify that two pods are now running: each pod runs an NGINX Plus instance and an NGINX Agent to communicate with the NGINX Management Suite control plane.

      $ kubectl get pods -n nim-test  
      NAME                        READY  STATUS   RESTARTS  AGE 
      nginx-nim-7f77c8bdc9-hkkck  1/1    Running  0         1m 
      nginx-nim-7f77c8bdc9-p2s94  1/1    Running  0         1m
    4. Access the NGINX Instance Manager GUI in NGINX Management Suite and verify that two NGINX Plus instances are running with status Online. In this example, NGINX App Protect WAF is not enabled.

    Get Started

    To try out the NGINX solutions discussed in this post, start a 30-day free trial today or contact us to discuss your use cases:

Download NGINX Agent – it’s free and open source.

Exit mobile version