Deploy ACM Developer Portal Using Helm

Follow the steps in the guide to deploy the API Connectivity Manager Developer Portal to Kubernetes using a Helm chart.

Overview

Follow the steps in this section to install, upgrade, or uninstall the ACM Developer Portal on Kubernetes using Helm.

Before You Begin

To complete the steps in this section, you need the following:

• A working knowledge of Docker and how to build and extend containers
• An installed, licensed, and running version of API Connectivity manager
• A installed version of Helm v3.10.0 or newer
• An externally-accessible private Docker registry to push the container images to
• Your NGINX Plus certificate and key files, which you can download from MyF5

See Also:

• Take a few minutes to review the Configurable Helm Settings at the end of this topic. You can change these settings to customize your installation to meet your needs.

• Check out the Deployment Patterns for Developer Portal topic if you’re considering installing the Developer Portal on a single host or on a cluster for high availability.

Build the API Gateway Container Image

The Developer Portal Helm chart requires a container image that includes the NGINX Plus service and NGINX Agent in order to deploy the chart and have the API Gateway register with the API Connectivity Manager control plane.

In this example, we use Ubuntu (focal), but other supported distributions can be used.

Create a Dockerfile similar to the following example:

1. Create a Dockerfile similar to the following example:

   Example Dockerfile

   Download example Dockerfile

   FROM ubuntu:focal
   
   # NGXIN Plus release e.g 27
   ARG NGINX_PLUS_VERSION
   
   # DEVPORTAL release e.g 1.3.0
   ARG DEVPORTAL_UI_VERSION
   
   ARG CONTROL_PLANE_IP
   
   # Install NGINX Plus
   RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
       --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
   set -ex \
   && apt-get update \
   && apt-get upgrade -y \
   && apt-get install --no-install-recommends --no-install-suggests -y \
       curl \
       gnupg \
       ca-certificates \
       apt-transport-https \
       lsb-release \
       procps \
   && \
   NGINX_GPGKEY=573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62; \
   for server in \
       hkp://keyserver.ubuntu.com:80 \
       pgp.mit.edu; do \
       echo "Fetching GPG key $NGINX_GPGKEY from $server"; \
       gpg --keyserver "$server" \
           --recv-keys "$NGINX_GPGKEY" \
           && break; \
   done \
   # Configure APT repos
   && curl -k -sS -L https://$CONTROL_PLANE_IP/packages-repository/nginx-signing.key | gpg --import - \
   && gpg --export "$NGINX_GPGKEY" > /etc/apt/trusted.gpg.d/nginx.gpg \
   && gpg --export "support@nginx.com" > /etc/apt/trusted.gpg.d/nginx-agent.gpg \
   && printf "Acquire::https::pkgs.nginx.com::SslCert \"/etc/ssl/nginx/nginx-repo.crt\";\n" >> /etc/apt/apt.conf.d/90pkgs-nginx \
   && printf "Acquire::https::pkgs.nginx.com::SslKey  \"/etc/ssl/nginx/nginx-repo.key\";\n" >> /etc/apt/apt.conf.d/90pkgs-nginx \
   && printf "Acquire::https::$CONTROL_PLANE_IP::Verify-Peer \"false\";\n" >> /etc/apt/apt.conf.d/90pkgs-nginx-agent \
   && printf "Acquire::https::$CONTROL_PLANE_IP::Verify-Host \"false\";\n" >> /etc/apt/apt.conf.d/90pkgs-nginx-agent \
   && printf "deb https://pkgs.nginx.com/plus/$(lsb_release -is | tr '[:upper:]' '[:lower:]') $(lsb_release -cs) nginx-plus\n" > /etc/apt/sources.list.d/nginx-plus.list \
   && printf "deb https://pkgs.nginx.com/nms/$(lsb_release -is | tr '[:upper:]' '[:lower:]') $(lsb_release -cs) nginx-plus\n" > /etc/apt/sources.list.d/nms.list \
   && printf "deb https://$CONTROL_PLANE_IP/packages-repository/deb/$(lsb_release -is | tr '[:upper:]' '[:lower:]') $(lsb_release -cs) agent\n" > /etc/apt/sources.list.d/nginx-agent.list \
   && apt-get update \
   # Install NGINX Plus & agent\
   && apt-get install -y \
           nginx-plus=${NGINX_PLUS_VERSION}* \
           nginx-plus-module-njs=${NGINX_PLUS_VERSION}* \
           nginx-devportal-ui=${DEVPORTAL_UI_VERSION}* \
           nginx-agent \
   # Forward request and error logs to docker log collector \
   && ln -sf /dev/stdout /var/log/nginx/access.log \
   && ln -sf /dev/stderr /var/log/nginx/error.log \
   # Cleanup \
   && apt-get autoremove --purge -y \
       curl \
       gnupg \
       apt-transport-https \
       lsb-release \
   && rm -rf /root/.gnupg \
   && rm -rf /var/lib/apt/lists/* 
   
   COPY /packaging/docker/entrypoint.sh /
   
   STOPSIGNAL SIGTERM
   
   CMD bash /entrypoint.sh
   

   
   

2. Add an entrypoint.sh file similar to the following example to the same directory where you added the Dockerfile:

   Example entrypoint.sh

   Download example entrypoint.sh file

   #!/bin/bash
   
   set -euxo pipefail
   
   handle_term()
   {
       echo "received TERM signal"
       echo "stopping nginx-agent ..."
       kill -TERM "${agent_pid}" 2>/dev/null
       echo "stopping nginx ..."
       kill -TERM "${nginx_pid}" 2>/dev/null
   }
   
   trap 'handle_term' TERM
   
   if [ -z "${CONTROL_PLANE_IP}" ]; then
       echo "ERROR CONTROL_PLANE_IP environment variable needs to be set."
       exit 1
   fi
   
   if [ -z "${INSTANCE_GROUP}" ]; then
       echo "ERROR INSTANCE_GROUP environment variable needs to be set."
       exit 1
   fi
   
   # Launch nginx
   echo "starting nginx ..."
   nginx -g "daemon off;" &
   
   nginx_pid=$!
   
   # start nginx-agent, pass args
   echo "starting nginx-agent ..."
   nginx-agent --instance-group "${INSTANCE_GROUP}" --server-host "${CONTROL_PLANE_IP}" &
   
   agent_pid=$!
   
   wait_term()
   {
       wait ${agent_pid}
       trap - TERM
       kill -QUIT "${nginx_pid}" 2>/dev/null
       echo "waiting for nginx to stop..."
       wait ${nginx_pid}
   }
   
   wait_term
   
   echo "nginx-agent process has stopped, exiting."
   

   
   

3. Add your NGINX Plus certificate and key files to the same directory as the Dockerfile. You can download these files from the MyF5 site.

4. Build the Dockerfile and specify the following settings:

   • CONTROL_PLANE_IP: The IP address or hostname of your API Connectivity Manager control plane host
   • NGINX_PLUS_VERSION: The version of NGINX Plus that you want to use; for example, 27
   • DEVPORTAL_UI_VERSION: The version of the Developer Portal UI that you want to use; for example, 1.3.0
   • REGISTRY_URL: The private registry for your images

   export CONTROL_PLANE_IP=<NGINX-INSTANCE-MANAGER-FQDN>
   export NGINX_PLUS_VERSION=<NGINX-PLUS-VERSION>
   export DEVPORTAL_UI_VERSION=<ACM-VERSION>
   export REGISTRY_URL=<REGISTRY-URL>
   export DOCKER_BUILDKIT=1
   docker build \
     -t ${REGISTRY_URL}/apigw:latest \
     --build-arg CONTROL_PLANE_IP \
     --build-arg NGINX_PLUS_VERSION \
     --build-arg DEVPORTAL_UI_VERSION \
     --secret id=nginx-crt,src=nginx-repo.crt \
     --secret id=nginx-key,src=nginx-repo.key \
     .
   

Download the Developer Portal API Image

1. On the MyF5 website, select Resources > NGINX Downloads.

2. In the NGINX products list, select NGINX API Connectivity Manager.

3. Select the following download options. Pick the version that you require; in this guide, we’ve chosen 1.3.0 as an example:

   Product version: 1.3.0
   Linux distribution: Ubuntu
   Distribution Version: 20.04
   Architecture: amd64

4. Download the nginx-devportal-<version>-img.tar.gz file.

Load Docker Image

1. Change to the directory where you downloaded the Docker image:

   cd <directory name>
   

2. Load the Docker image:

   docker load -i nginx-devportal-<version>-img.tar.gz
   

   The output looks similar to the following:

   $ docker load -i nginx-devportal-<version>-img.tar.gz
   1b5933fe4b5: Loading layer [==================================================>]  5.796MB/5.796MB
   fbe0fc9bcf95: Loading layer [==================================================>]  17.86MB/17.86MB
   ...
   112ae1f604e0: Loading layer [==================================================>]   67.8MB/67.8MB
   4b6a693b90f4: Loading layer [==================================================>]  3.072kB/3.072kB
   Loaded image: devportal-api:1.3.0
   

3. For the output of the docker load command, note the loaded images name and tag. For example, in the output directly above, devportal-api is the image name and 1.3.0 is the tag. You’ll need to reference this image and tag in the next section when pushing the image to your private registry. The tag 1.3.0 could be different depending on the product version you downloaded from MyF5.

Push Images to Private Registry

Before you begin:
To complete this step, you need an externally-accessible private Docker registry to push the container images to.

After building or loading the Docker images, you can now tag and push the images to your private Docker registry. Replace <my-docker-registry> in the examples below with the path to your private Docker registry.

1. Log in to your private registry:

   docker login <my-docker-registry>
   

2. Tag the images with the values you noted when completing the Load Docker Images steps above. In this example, the images are tagged with version 1.3.0.

   docker tag apigw:latest <my-docker-registry>/apigw:1.3.0
   docker tag devportal-api:1.3.0 <my-docker-registry>/devportal-api:1.3.0
   

3. Push the images to your private registry:

   docker push <my-docker-registry>/apigw:1.3.0
   docker push <my-docker-registry>/devportal-api:1.3.0
   

Add Helm Repository

Run the following commands to install the NGINX Management Suite chart from the Helm repository:

helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update

The first command, helm repo add nginx-stable https://helm.nginx.com/stable, adds the nginx-stable repository to your local Helm repository list. This repository contains the Helm charts for deploying NGINX Management Suite.

The second command, helm repo update, updates the local Helm repository list with the newest versions of the charts from the nginx-stable repository. This command ensures you have the most up-to-date version of the charts available for installation.

Install the Chart

The Developer Portal does not require (although it is recommended) a dedicated namespace for the data plane. You can create this namespace yourself, or you can allow Helm to create it for you by using the --create-namespace flag when installing.

Note:
If persistent storage is not configured in your cluster, set the apigw.persistence.enabled abd api.persistence.enabled values to false either in the values file or using the --set helm commands.

To install the chart with the release name devportal and namespace devportal, run the following command:

helm install devportal nginx-stable/nginx-devportal --namespace devportal --create-namespace --wait

Upgrade the Chart

You can upgrade to the latest Helm chart from the version immediately before it. For example, you can upgrade from v1.3.0 to v1.3.1.

Upgrade the Release

To upgrade the release devportal in the devportal namespace, run the following command:

helm upgrade devportal nginx-stable/nginx-devportal  --namespace devportal --wait

Change Configuration Options

You can use the helm upgrade command to change or apply additional configurations to the release.

To change a configuration, use --set commands or -f <my-values-file>, where my-values-file is a path to a values file with your desired configuration.

Uninstall the Chart

To uninstall and delete the release devportal in the devportal namespace, take the following step:

helm uninstall devportal --namespace devportal

This command removes all of the Kubernetes components associated with the Developer Portal release. The namespace is not deleted.

Configurable Helm Settings

The values.yaml file within the nginx-devportal Helm chart contains the deployment configuration for the Developer Portal.

You can update these fields directly in the values.yaml file or by specifying the --set flag when running helm install.

To modify a configuration for an existing release, run the helm upgrade command and use the --set flag or -f <my-values-file>, where my-values-file is a path to a values file with your desired configuration.

The following table lists the configurable parameters and default values used by the Developer Portal chart when installing from a Helm chart.

Common Deployment Configurations

Select from the following options to view some of the commonly used configurations for the Developer Portal. To apply these configurations, edit the values.yaml file as needed.