|
| 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 | +- Deploy a Docker container running the latest NGINX Plus with NGINX Agent installed |
| 25 | +- Add a VM to a Config Sync Group and push your JWT license |
| 26 | +- Install or upgrade to the latest NGINX Plus on a VM |
| 27 | +- Check version and sync status in the NGINX One Console |
| 28 | +- Clean up unavailable instances in the NGINX One Console |
| 29 | + |
| 30 | +## Before you begin |
| 31 | + |
| 32 | +Make sure you have: |
| 33 | + |
| 34 | +- Completed [Lab 4: Config Sync Groups]({{< ref "nginx-one/workshops/lab4/config-sync-groups.md" >}}) |
| 35 | +- Docker and Docker Compose installed and running (for Docker scenario) |
| 36 | +- A trial or paid NGINX One JWT license (saved as `nginx-repo.jwt`) from [MyF5](https://my.f5.com/manage/s/). |
| 37 | +- A VM with NGINX Plus R32 (or earlier), SSH access, and the NGINX Agent installed (for VM scenario) |
| 38 | +- {{< include "workshops/nginx-one-env-variables.md" >}} |
| 39 | +- Basic familiarity with Linux command line and NGINX concepts |
| 40 | + |
| 41 | +## Scenario A: Upgrade NGINX Plus in Docker |
| 42 | + |
| 43 | +### Exercise A1: Pull and run the latest NGINX Plus image |
| 44 | + |
| 45 | +1. In your shell, log in to the private registry: |
| 46 | + |
| 47 | + ```shell |
| 48 | + echo "$JWT" | docker login private-registry.nginx.com \ |
| 49 | + --username "$JWT" --password-stdin |
| 50 | + ``` |
| 51 | + |
| 52 | +2. Open `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. |
| 53 | + |
| 54 | + ```yaml |
| 55 | + plus4: # Debian latest NGINX Plus Web / Load Balancer |
| 56 | + environment: |
| 57 | + NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' |
| 58 | + NGINX_AGENT_SERVER_GRPCPORT: '443' |
| 59 | + NGINX_AGENT_TLS_ENABLE: 'true' |
| 60 | + NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console |
| 61 | + NGINX_LICENSE_JWT: $JWT |
| 62 | + NGINX_AGENT_INSTANCE_GROUP: $NAME-sync-group |
| 63 | + hostname: $NAME-plus4 |
| 64 | + container_name: $NAME-plus4 |
| 65 | + image: private-registry.nginx.com/nginx-plus/agent:debian # From NGINX Private Registry |
| 66 | + volumes: # Sync these folders to container |
| 67 | + - ./nginx-plus/etc/nginx/nginx.conf:/etc/nginx/nginx.conf |
| 68 | + - ./nginx-plus/etc/nginx/conf.d:/etc/nginx/conf.d |
| 69 | + - ./nginx-plus/etc/nginx/includes:/etc/nginx/includes |
| 70 | + - ./nginx-plus/usr/share/nginx/html:/usr/share/nginx/html |
| 71 | + ports: |
| 72 | + - '80' # Open for HTTP |
| 73 | + - '443' # Open for HTTPS |
| 74 | + - '9000' # Open for API / Dashboard page |
| 75 | + - '9113' # Open for Prometheus Scraper page |
| 76 | + restart: always |
| 77 | + ``` |
| 78 | +
|
| 79 | + {{< call-out "note" "Tip" "" >}} If you use VS Code, highlight lines 74–95 and press `Ctrl` + `/` to uncomment them. {{< /call-out >}} |
| 80 | + |
| 81 | +3. Restart your containers: |
| 82 | + |
| 83 | + ```shell |
| 84 | + docker compose down && docker compose up --force-recreate -d |
| 85 | + ``` |
| 86 | + |
| 87 | +4. In the NGINX One Console, go to **Instances**. |
| 88 | +5. You should see your new instance (`$NAME-plus4`) in the list (for example, `s.jobs-plus4`). |
| 89 | +6. Select that instance and verify it runs the latest versions of NGINX Plus and NGINX Agent. |
| 90 | +7. The `$NAME-plus4` container was added to the `$NAME-sync-group` config sync group and inherited the shared config. |
| 91 | + |
| 92 | + {{< call-out "note" "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. {{< /call-out >}} |
| 93 | + |
| 94 | +### Exercise A2: Delete unavailable containers |
| 95 | + |
| 96 | +When you recreate containers, they re-register in the NGINX One Console. Use the filter to clean up old entries: |
| 97 | + |
| 98 | +1. In the NGINX One Console, go **Instances**. |
| 99 | +2. Select **Add filter > Availability > Unavailable**. |
| 100 | +3. Check the boxes next to the unavailable hosts. |
| 101 | +4. Select **Delete selected**, then confirm. |
| 102 | +5. Remove the filter: Hover over the **Availability is Unavailable** filter tag, then select **X** to clear it and show all instances again. |
| 103 | + |
| 104 | +<span style="display: inline-block;"> |
| 105 | +{{< img src="nginx-one/images/unavailable-instances.png" |
| 106 | + 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." >}} |
| 107 | +</span> |
| 108 | + |
| 109 | +## Scenario B: Use Config Sync Groups to upgrade NGINX Plus on a VM |
| 110 | + |
| 111 | +{{< call-out "note" "Note" >}} |
| 112 | +These steps cover RHEL, Amazon Linux, CentOS, Oracle Linux, AlmaLinux, Rocky Linux, Debian, and Ubuntu only. Other systems (for example, FreeBSD) aren’t covered here. |
| 113 | +{{</ call-out >}} |
| 114 | + |
| 115 | +### Exercise B1: Create a Config Sync Group for VMs |
| 116 | + |
| 117 | +1. In the NGINX One Console, go to **Manage > Config Sync Groups**. |
| 118 | +2. Select **Add Config Sync Group**. |
| 119 | +3. In the **Name** field, enter `$NAME-sync-group-vm` (for example, `s.jobs-sync-group-vm`), then select **Create**. |
| 120 | + |
| 121 | +### Exercise B2: Add your VM to the Config Sync Group |
| 122 | + |
| 123 | +1. Select **Manage > Config Sync Groups**, then pick your config sync group's name. |
| 124 | +2. On the **Details** tab, in the **Instances** pane, select **Add Instance to Config Sync Group**. |
| 125 | +3. Select **Register a new instance with NGINX One then add to config sync group**, then select **Next**. |
| 126 | +4. Select **Use existing key**, paste `<your-key>` into the **Data Plane Key** box. |
| 127 | +5. Copy the pre-filled `curl` command and run it on your VM: |
| 128 | + |
| 129 | + **Example**: |
| 130 | + |
| 131 | + ```shell |
| 132 | + curl https://agent.connect.nginx.com/nginx-agent/install | \ |
| 133 | + DATA_PLANE_KEY="<your-key>" \ |
| 134 | + sh -s -- -y -c "<config-sync-group-name>" |
| 135 | + ``` |
| 136 | + |
| 137 | +6. Back in the NGINX One Console, select **Refresh**. Your VM appears in the list and its **Config Sync Status** shows **In Sync**. |
| 138 | + |
| 139 | +### Exercise B3: Enable the NGINX Plus API and dashboard |
| 140 | + |
| 141 | +In this exercise, you add a new configuration file (`/etc/nginx/conf.d/dashboard.conf`) to your shared group config. This file enables the NGINX Plus API and dashboard. Any instance you add to the group will pick up these settings automatically. |
| 142 | + |
| 143 | +{{< include "use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md" >}} |
| 144 | + |
| 145 | +### Exercise B4: Add your JWT license file |
| 146 | + |
| 147 | +You need your NGINX One JWT license (from [MyF5](https://my.f5.com/manage/s/)) on each instance before you upgrade to the latest NGINX Plus. You can add it in your Config Sync Group so every member gets it automatically. |
| 148 | + |
| 149 | +1. In the NGINX One Console, select **Manage > Config Sync Groups**, then pick your config sync group's name. |
| 150 | +2. Select the **Configuration** tab, then **Edit Configuration**. |
| 151 | +3. Select **Add File**. |
| 152 | +4. Select **New Configuration File**. |
| 153 | +5. In the **File name** box, enter `/etc/nginx/license.jwt` (the filename must match exactly), then select **Add**. |
| 154 | +6. Paste the contents of your JWT file into new file workspace. |
| 155 | +7. Select **Next**, review the diff, then select **Save and Publish**. |
| 156 | + |
| 157 | +For more information, see [About subscription licenses]({{< ref "solutions/about-subscription-licenses.md" >}}). |
| 158 | + |
| 159 | +### Exercise B5: Upgrade NGINX Plus on your VM |
| 160 | + |
| 161 | +1. Upgrade the NGINX Plus package on your VM: |
| 162 | + |
| 163 | + - **RHEL, Amazon Linux, CentOS, Oracle Linux, AlmaLinux, Rocky Linux** |
| 164 | + |
| 165 | + ```shell |
| 166 | + sudo yum upgrade nginx-plus |
| 167 | + ``` |
| 168 | + |
| 169 | + - **Debian, Ubuntu** |
| 170 | + |
| 171 | + ```shell |
| 172 | + sudo apt update && sudo apt install nginx-plus |
| 173 | + ``` |
| 174 | + |
| 175 | +2. In the NGINX One Console, go to **Manage > Instances**. |
| 176 | +3. Select your VM instance in the list. |
| 177 | +4. In the Instance Details panel, confirm the NGINX Plus version has been updated. |
| 178 | +5. If the version doesn’t update right away, refresh the page after a few seconds. |
0 commit comments