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

Fabrizio FiorucciSolutions Architect

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:

• NGINX Plus and NGINX Agent only
• NGINX Plus, NGINX Agent, and NGINX App Protect WAF
• NGINX Plus, NGINX Agent, and support for the NGINX Management Suite API Connectivity Manager developer portal (for NGINX Plus instances running as an API gateway)

[Editor – This post was updated in April 2023 to clarify the instructions, and add the ACM_DEVPORTAL field, in Step 1 of Running the Docker Image in Kubernetes.]

Prerequisites

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:

• A Linux host (bare metal or VM)
• Docker 20.10+
• A private registry to which you can push the target Docker image
• A running NGINX Management Suite instance with Instance Manager, and API Connectivity Manager if you want to leverage support for the developer portal
• A subscription (or 30-day free trial) for NGINX Plus and optionally NGINX App Protect

To run the Docker image, you need:

• A running Kubernetes cluster
• kubectl with access to the Kubernetes cluster

Building the Docker Image

Follow these instructions to build the Docker image.

1. Clone the GitHub repository: [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
2. Change to the build directory: [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
3. Run docker ps to verify that Docker is running and then run the build.sh script to include the desired software in the Docker image. The base options are: The additional options are: Here are the commands for the different combinations of software: Here’s a sample trace of the build for a basic image. The Build complete message at the end indicates a successful build. [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop Running the Docker Image in Kubernetes Follow these instructions to prepare the Deployment manifest and start NGINX Plus with NGINX Agent on Kubernetes. 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.
   • ‑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_name>/<image_name>:<tag> (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)
   • ‑d – Add data‑plane support for the developer portal when using NGINX API Connectivity Manager
   • ‑w – Add NGINX App Protect WAF
   • NGINX Plus and NGINX Agent: [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
   • NGINX Plus, NGINX Agent, and NGINX App Protect WAF (add the ‑w option): [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
   • NGINX Plus, NGINX Agent, and developer portal support (add the ‑d option): [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop

1. Using your preferred text editor, open manifests/1.nginx-with-agent.yaml and make the following changes (the code snippets show the default values that you can or must change, highlighted in orange):
   • 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 Building the Docker Image (in our case, registry.ff.lan:31005/nginx-plus-with-agent:2.7.0): [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
   • In the spec.template.spec.containers.env section, make these substitutions in the value field for each indicated name: [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
     • 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 different port number for gRPC traffic.
     • 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.
   • Also in the spec.template.spec.containers.env section, uncomment these name‑value field pairs if the indicated condition applies: [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
     • NIM_WAF and NIM_WAF_PRECOMPILED_POLICIES – NGINX App Protect WAF is included in the image (you included the -w option in Step 3 of Building the Docker Image), so the value is "true".
     • ACM_DEVPORTAL – Support for the App Connectivity Manager developer portal is included in the image (you included the -d option in Step 3 of Building the Docker Image), so the value is "true".
2. Run the nginxwithAgentStart.sh 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: [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
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. [@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop
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.
   

• NGINX Management Suite
• NGINX Plus (includes NGINX App Protect WAF)

About the Author

Fabrizio FiorucciSolutions Architect

More blogs by Fabrizio Fiorucci