Download NGINX Ingress Controller from the F5 Registry

This page describes how to download an F5 NGINX Plus Ingress Controller image from the official F5 Docker registry.

The F5 Registry images include versions with NGINX App Protect WAF and NGINX App Protect DoS.

Before you begin

To follow these steps, you will need the following pre-requisites:

You can also get the NGINX Ingress Controller image using the following alternate methods:

Download your subscription credential files

In order to obtain a container image, you will need the JSON Web Token file or SSL certificate and private key files provided with your NGINX Plus subscription.

These files grant access to the package repository from which the script will download the NGINX Plus package:

  1. Log in to MyF5.
  2. Go to My Products & Plans > Subscriptions to see your active subscriptions.
  3. Find your NGINX subscription, and select the Subscription ID for details.
  4. Download the JSON Web Token file from the subscription page.
  1. Log in to MyF5.
  2. Go to My Products & Plans > Subscriptions to see your active subscriptions.
  3. Find your NGINX subscription, and select the Subscription ID for details.
  4. Download the SSL Certificate and Private Key files from the subscription page.

Set up Docker for the F5 Container Registry

This step describes how to use Docker to communicate with the F5 Container Registry located at private-registry.nginx.com.

The steps provided are for Linux. For Mac or Windows, see the Docker for Mac or Docker for Windows documentation.

For more details on Docker Engine security, you can refer to the Docker Engine Security documentation.

Open the JSON Web Token file previously downloaded from MyF5 customer portal (for example, nginx-repo-12345abc.jwt) and copy its contents.

Log in to the Docker registry using the contents of the JSON Web Token file:

docker login private-registry.nginx.com --username=<output_of_jwt_token> --password=none

Create a directory and copy your certificate and key to this directory:

mkdir -p /etc/docker/certs.d/private-registry.nginx.com
cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key

Log in to the Docker registry:

docker login private-registry.nginx.com

Pull the image

Identify which image you need using the Technical specifications topic.

Next, pull the image from private-registry.nginx.com.

Replace <version-tag> with the specific version you need, for example, 5.1.0.

  • For NGINX Plus Ingress Controller, run:

    docker pull private-registry.nginx.com/nginx-ic/nginx-plus-ingress:<version-tag>

  • For NGINX Plus Ingress Controller with NGINX App Protect WAF, run:

    docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:<version-tag>

  • For NGINX Plus Ingress Controller with NGINX App Protect WAF v5, run:

    docker pull private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag>
    docker pull private-registry.nginx.com/nap/waf-config-mgr:<waf-version-tag>
    docker pull private-registry.nginx.com/nap/waf-enforcer:<waf-version-tag>

  • For NGINX Plus Ingress Controller with NGINX App Protect DoS, run:

    docker pull private-registry.nginx.com/nginx-ic-dos/nginx-plus-ingress:<version-tag>

  • For NGINX Plus Ingress Controller with NGINX App Protect WAF and NGINX App Protect DoS, run:

    docker pull private-registry.nginx.com/nginx-ic-nap-dos/nginx-plus-ingress:<version-tag>

You can use the Docker registry API to list the available image tags by running the following commands. Replace <path-to-client.key> with the location of your client key and <path-to-client.cert> with the location of your client certificate.

The jq command was used in these examples to make the JSON output easier to read.

curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
{
  "name": "nginx-ic/nginx-plus-ingress",
  "tags": [
    "5.1.0-alpine",
    "5.1.0-alpine-fips",
    "5.1.0-ubi",
    "5.1.0"
  ]
}
curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
{
  "name": "nginx-ic-nap/nginx-plus-ingress",
  "tags": [
    "5.1.0-alpine-fips",
    "5.1.0-ubi",
    "5.1.0"
  ]
}
curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
{
  "name": "nginx-ic-dos/nginx-plus-ingress",
  "tags": [
    "5.1.0-ubi",
    "5.1.0"
  ]
}

Push to your private registry

After pulling the image, tag it and upload it to your private registry.

  1. Log in to your private registry:

    docker login <my-docker-registry>

  2. Tag and push the image. Replace <my-docker-registry> with your registry’s path and <version-tag> with the version you’re using, for example 5.1.0:

    • For NGINX Plus Ingress Controller, run:

      docker tag private-registry.nginx.com/nginx-ic/nginx-plus-ingress:<version-tag> <my-docker-registry>/nginx-ic/nginx-plus-ingress:<version-tag>
docker push <my-docker-registry>/nginx-ic/nginx-plus-ingress:<version-tag>

    • For NGINX Controller with NGINX App Protect WAF, run:

      docker tag private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:<version-tag> <my-docker-registry>/nginx-ic-nap/nginx-plus-ingress:<version-tag>
docker push <my-docker-registry>/nginx-ic-nap/nginx-plus-ingress:<version-tag>
      • For NGINX Controller with NGINX App Protect WAF v5, run:
      docker tag private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag> <my-docker-registry>/nginx-ic-nap/nginx-plus-ingress:<version-tag>
docker push <my-docker-registry>/nginx-ic-nap/nginx-plus-ingress:<version-tag>
      docker tag private-registry.nginx.com/nap/waf-config-mgr:<waf-version-tag> <my-docker-registry>/nap/waf-config-mgr:<waf-version-tag>
docker push <my-docker-registry>/nap/waf-config-mgr:<waf-version-tag>
      docker tag private-registry.nginx.com/nap/waf-enforcer:<waf-version-tag> <my-docker-registry>/nap/waf-enforcer:<waf-version-tag>
docker push <my-docker-registry>/nap/waf-enforcer:<waf-version-tag>

    • For NGINX Controller with NGINX App Protect DoS, run:

      docker tag private-registry.nginx.com/nginx-ic-dos/nginx-plus-ingress:<version-tag> <my-docker-registry>/nginx-ic-dos/nginx-plus-ingress:<version-tag>
docker push <my-docker-registry>/nginx-ic-dos/nginx-plus-ingress:<version-tag>

Troubleshooting

If you encounter issues while following this guide, here are some possible solutions:

  • Certificate errors

    • Likely Cause: Incorrect certificate or key location, or using an NGINX Plus certificate.
    • Solution: Verify you have the correct NGINX Ingress Controller certificate and key. Place them in the correct directory and ensure the certificate has a .cert extension.

  • Docker version compatibility

    • Likely Cause: Outdated Docker version.
    • Solution: Make sure you’re running Docker v18.09 or higher. Upgrade if necessary.

  • Can’t pull the image

    • Likely Cause: Mismatched image name or tag.
    • Solution: Double-check the image name and tag matches the Technical specifications document.

  • Failed to push to private registry

    • Likely Cause: Not logged into your private registry or incorrect image tagging.
    • Solution: Verify login status and correct image tagging before pushing. Consult the Docker documentation for more details.