|
| 1 | +--- |
| 2 | +title: "Lab 5: Upgrade NGINX Plus to the latest version" |
| 3 | +weight: 500 |
| 4 | +toc: true |
| 5 | +nd-content-type: tutorial |
| 6 | +nd-product: |
| 7 | +- nginx-one |
| 8 | +- nginx-plus |
| 9 | +--- |
| 10 | + |
| 11 | +## Overview |
| 12 | + |
| 13 | +In this lab, you upgrade NGINX Plus from R32 (or earlier) to the latest version in two ways: |
| 14 | + |
| 15 | +- **Docker**: Deploy a new container running the latest NGINX Plus image, add it to your Config Sync Group, then shift traffic and retire older containers. |
| 16 | +- **VM**: Push your JWT license to an existing VM instance, install the new NGINX Plus package, and restart the service. |
| 17 | + |
| 18 | +Pick the scenario that matches your setup. |
| 19 | + |
| 20 | +## What you’ll learn |
| 21 | + |
| 22 | +By the end of this lab, you’ll know how to: |
| 23 | + |
| 24 | +- Upgrade NGINX Plus Docker containers to R34 |
| 25 | +- Add a VM to a Config Sync Group and push your JWT license |
| 26 | +- Upgrade NGINX Plus on a VM to R34 |
| 27 | +- Verify the new version and sync status in NGINX One Console |
| 28 | + |
| 29 | +## Before you begin |
| 30 | + |
| 31 | +Make sure you have: |
| 32 | + |
| 33 | +- Completed [Lab 4: Config Sync Groups]({{< ref "nginx-one/workshops/lab4/config-sync-groups.md" >}}) |
| 34 | +- Docker and Docker Compose installed and running (for Docker scenario) |
| 35 | +- A VM with NGINX Plus R32 (or earlier), SSH access, and the NGINX Agent installed (for VM scenario) |
| 36 | +- Your data plane key in the `TOKEN` environment variable: |
| 37 | + |
| 38 | + ```shell |
| 39 | + export TOKEN="your-data-plane-key" |
| 40 | + ``` |
| 41 | + |
| 42 | +- Your NGINX Plus JWT license file saved as `nginx-repo.jwt` and JWT set: |
| 43 | + |
| 44 | + ```shell |
| 45 | + export JWT=$(cat path/to/nginx-repo.jwt) |
| 46 | + ``` |
| 47 | + |
| 48 | +- Your unique identifier in the NAME environment variable (for example s.jobs): |
| 49 | + |
| 50 | + ```shell |
| 51 | + export NAME="s.jobs" |
| 52 | + ``` |
| 53 | + |
| 54 | +- Basic familiarity with Linux command line and NGINX Plus |
| 55 | + |
| 56 | +## Scenario A: Upgrade NGINX Plus in Docker |
| 57 | + |
| 58 | +### Exercise A1: Pull and run the latest NGINX Plus image |
| 59 | + |
| 60 | +1. In your shell, log in to the private registry: |
| 61 | + |
| 62 | + ```shell |
| 63 | + echo "$JWT" | docker login private-registry.nginx.com \ |
| 64 | + --username "$JWT" --password-stdin |
| 65 | + ``` |
| 66 | + |
| 67 | +2. Open `docker-compose.yaml` in a text editor and uncomment the **plus4** service block (lines 74–95). This block pulls the latest Debian NGINX Plus image with the latest NGINX Agent installed, and sets your data plane key, JWT, and config sync group. |
| 68 | + |
| 69 | + ```yaml |
| 70 | + plus4: # Debian latest NGINX Plus Web / Load Balancer |
| 71 | + environment: |
| 72 | + NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' |
| 73 | + NGINX_AGENT_SERVER_GRPCPORT: '443' |
| 74 | + NGINX_AGENT_TLS_ENABLE: 'true' |
| 75 | + NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console |
| 76 | + NGINX_LICENSE_JWT: $JWT |
| 77 | + NGINX_AGENT_INSTANCE_GROUP: $NAME-sync-group |
| 78 | + hostname: $NAME-plus4 |
| 79 | + container_name: $NAME-plus4 |
| 80 | + image: private-registry.nginx.com/nginx-plus/agent:debian # From NGINX Private Registry |
| 81 | + volumes: # Sync these folders to container |
| 82 | + - ./nginx-plus/etc/nginx/nginx.conf:/etc/nginx/nginx.conf |
| 83 | + - ./nginx-plus/etc/nginx/conf.d:/etc/nginx/conf.d |
| 84 | + - ./nginx-plus/etc/nginx/includes:/etc/nginx/includes |
| 85 | + - ./nginx-plus/usr/share/nginx/html:/usr/share/nginx/html |
| 86 | + ports: |
| 87 | + - '80' # Open for HTTP |
| 88 | + - '443' # Open for HTTPS |
| 89 | + - '9000' # Open for API / Dashboard page |
| 90 | + - '9113' # Open for Prometheus Scraper page |
| 91 | + restart: always |
| 92 | + ``` |
| 93 | +
|
| 94 | + > Tip: If you use VS Code, highlight lines 74–95 and press `Ctrl` + `/` to uncomment them. |
| 95 | + |
| 96 | +3. Restart your containers: |
| 97 | + |
| 98 | + ```shell |
| 99 | + docker compose down && docker compose up --force-recreate -d |
| 100 | + ``` |
| 101 | + |
| 102 | +4. In the NGINX One Console, go to **Instances**. |
| 103 | +5. You should see your new instance (`$NAME-plus4`) in the list (for example, `s.jobs-plus4`). |
| 104 | +6. Select that instance and verify it runs the latest versions of NGINX Plus and NGINX Agent. |
| 105 | +7. The `$NAME-plus4` container was added to the `$NAME-sync-group` config sync group and inherited the shared config. |
| 106 | + |
| 107 | + > **Tip:** Because new containers in a sync group automatically pick up the shared config, you get a consistent, tested setup across versions. You can shift traffic to the new container one at a time for a safer, zero-downtime upgrade, and avoid any manual copy-and-paste steps. |
| 108 | + |
| 109 | +### Exercise A2: Delete unavailable containers |
| 110 | + |
| 111 | +When you recreate containers, they re-register in the NGINX One Console. Use the filter to clean up old entries: |
| 112 | + |
| 113 | +1. In the NGINX One Console, go **Instances**. |
| 114 | +2. Select **Add filter > Availability > Unavailable**. |
| 115 | +3. Check the boxes next to the unavailable hosts. |
| 116 | +4. Select **Delete selected**, then confirm. |
| 117 | +5. Remove the filter to view the full list again. |
| 118 | + |
| 119 | +<span style="display: inline-block;"> |
| 120 | +{{< img src="nginx-one/images/unavailable-instances.png" |
| 121 | + alt="Table of three NGINX One Console instances filtered to ‘Availability = Unavailable.’ Shows hostnames (s.jobs-plus1, s.jobs-plus2, s.jobs-plus3), NGINX versions, grey ‘Unavailable’ circles, CVE and recommendation indicators, certificate status, operating system, and last reported times. The ‘Delete selected’ button appears at top right." >}} |
| 122 | +</span> |
0 commit comments