# 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 F5 WAF for NGINX and F5 DoS for NGINX.

## Before you begin

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

- [Docker v18.09 or higher](https://docs.docker.com/engine/release-notes/18.09/)

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

- [Add an NGINX Ingress Controller image to your cluster](/nic/install/images/add-image-to-cluster.md)
- [Build NGINX Ingress Controller](/nic/install/build.md) 
- For NGINX Open Source, you can pull [an image from DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/)

### 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:

#### JSON Web Token

#### SSL

### 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`.

**Note:** 

The steps provided are for Linux. For Mac or Windows, see the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. 

For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/).

#### JSON Web Token

Open the JSON Web Token file previously downloaded from [MyF5](https://my.f5.com) 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:

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

#### SSL

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

```shell
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
```

## Pull the image

Identify which image you need using the [Technical specifications](/nic/technical-specifications.md#images-with-nginx-plus) topic.

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

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

- For NGINX Plus Ingress Controller, run:

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

- For NGINX Plus Ingress Controller with F5 WAF for NGINX, run:

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

- For NGINX Plus Ingress Controller with F5 WAF for NGINX and NGINX Agent 3 (required for NGINX One Console, available starting with NGINX Ingress Controller 5.5.0), run:

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

- For NGINX Plus Ingress Controller with F5 WAF for NGINX v5, run:

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

   ```shell
   docker pull private-registry.nginx.com/nap/waf-config-mgr:<waf-version-tag>
   ```

   ```shell
   docker pull private-registry.nginx.com/nap/waf-enforcer:<waf-version-tag>
   ```

- For NGINX Plus Ingress Controller with F5 WAF for NGINX v5 and NGINX Agent 3 (required for NGINX One Console, available starting with NGINX Ingress Controller 5.5.0), run:

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

   ```shell
   docker pull private-registry.nginx.com/nap/waf-config-mgr:<waf-version-tag>
   ```

   ```shell
   docker pull private-registry.nginx.com/nap/waf-enforcer:<waf-version-tag>
   ```

- For NGINX Plus Ingress Controller with F5 DoS for NGINX, run:

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

- For NGINX Plus Ingress Controller with F5 WAF for NGINX and F5 DoS for NGINX, run:

   ```shell
   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.

```shell
curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
```

```json
{
  "name": "nginx-ic/nginx-plus-ingress",
  "tags": [
    "-alpine",
    "-alpine-fips",
    "-ubi",
    ""
  ]
}
```

```shell
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>
```

```json
{
  "name": "nginx-ic-nap/nginx-plus-ingress",
  "tags": [
    "-alpine-fips",
    "-alpine-fips-agent",
    "-ubi",
    "-ubi-agent",
    "-ubi8",
    "-ubi8-agent",
    "",
    "-agent"
  ]
}
```

```shell
curl https://private-registry.nginx.com/v2/nginx-ic-nap-v5/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
```

```json
{
  "name": "nginx-ic-nap-v5/nginx-plus-ingress",
  "tags": [
    "-alpine-fips",
    "-alpine-fips-agent",
    "-ubi",
    "-ubi-agent",
    "-ubi8",
    "-ubi8-agent",
    "",
    "-agent"
  ]
}
```

```shell
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>
```

```json
{
  "name": "nginx-ic-dos/nginx-plus-ingress",
  "tags": [
    "-ubi",
    ""
  ]
}
```

## 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:

   ```shell
   docker login <my-docker-registry>
   ```

1. 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 ``:

   - For NGINX Plus Ingress Controller, run:

      ```shell
      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 Plus Ingress Controller with F5 WAF for NGINX, run:

      ```shell
      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 Plus Ingress Controller with F5 WAF for NGINX and NGINX Agent 3, run:

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

   - For NGINX Plus Ingress Controller with F5 WAF for NGINX v5, run:

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

      ```shell
      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>
      ```

      ```shell
      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 Plus Ingress Controller with F5 WAF for NGINX v5 and NGINX Agent 3, run:

      ```shell
      docker tag private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag>-agent <my-docker-registry>/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag>-agent
      docker push <my-docker-registry>/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag>-agent
      ```

      ```shell
      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>
      ```

      ```shell
      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 Plus Ingress Controller with F5 DoS for NGINX, run:

      ```shell
      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](https://docs.docker.com/engine/release-notes/18.09/). 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](/nic/technical-specifications.md#images-with-nginx-plus) 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](https://docs.docker.com/docker-hub/repos/) for more details.