diff --git a/content/includes/config-snippets/enable-nplus-api-dashboard.md b/content/includes/config-snippets/enable-nplus-api-dashboard.md index 0aaf4b750..cd086ae0c 100644 --- a/content/includes/config-snippets/enable-nplus-api-dashboard.md +++ b/content/includes/config-snippets/enable-nplus-api-dashboard.md @@ -34,4 +34,4 @@ server { root /usr/share/nginx/html; } } -``` \ No newline at end of file +``` diff --git a/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md b/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md new file mode 100644 index 000000000..28e221b78 --- /dev/null +++ b/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md @@ -0,0 +1,17 @@ +--- +docs: +files: +- +- +--- + +1. In the NGINX One Console, select **Manage > Config Sync Groups**, then pick your config sync group's name. +2. Select the **Configuration** tab, then select **Edit Configuration**. +3. Select **Add File**. +4. Select **New Configuration File**. +5. In the **File name** box, enter `/etc/nginx/conf.d/dashboard.conf`, then select **Add**. +6. Paste the following into the new file workspace: + +{{< include "config-snippets/enable-nplus-api-dashboard.md" >}} + +7. Select **Next**, review the diff, then select **Save and Publish**. \ No newline at end of file diff --git a/content/includes/use-cases/monitoring/enable-nginx-plus-api.md b/content/includes/use-cases/monitoring/enable-nginx-plus-api.md index 50fbd5be7..6a71f3c6b 100644 --- a/content/includes/use-cases/monitoring/enable-nginx-plus-api.md +++ b/content/includes/use-cases/monitoring/enable-nginx-plus-api.md @@ -15,4 +15,4 @@ To collect comprehensive metrics for NGINX Plus, including bytes streamed, infor - To restrict write methods (`POST`, `PATCH`, `DELETE`), uncomment and configure the `limit_except GET` block and set up [HTTP basic authentication](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html). {{}} -For more details, see the [NGINX Plus API module](https://nginx.org/en/docs/http/ngx_http_api_module.html) documentation and [Configuring the NGINX Plus API]({{< ref "/nginx/admin-guide/monitoring/live-activity-monitoring.md#configuring-the-api" >}}). \ No newline at end of file +For more details, see the [NGINX Plus API module](https://nginx.org/en/docs/http/ngx_http_api_module.html) documentation and [Configuring the NGINX Plus API]({{< ref "/nginx/admin-guide/monitoring/live-activity-monitoring.md#configuring-the-api" >}}). diff --git a/content/includes/workshops/nginx-one-env-variables.md b/content/includes/workshops/nginx-one-env-variables.md new file mode 100644 index 000000000..1baf15c49 --- /dev/null +++ b/content/includes/workshops/nginx-one-env-variables.md @@ -0,0 +1,27 @@ +--- +docs: +files: +- content/nginx-one/workshops/lab4/config-sync-groups.md +- content/nginx-one/workshops/lab5/upgrade-nginx-plus-to-r34.md + +--- + +Set these environment variables: + +- **TOKEN**: your data plane key, for example: + + ```shell + export TOKEN="your-data-plane-key" + ``` + +- **JWT**: your NGINX Plus license JWT. Save it as `nginx-repo.jwt`, then run: + + ```shell + export JWT=$(cat path/to/nginx-repo.jwt) + ``` + +- **NAME**: a unique ID for your workshop (for example, `s.jobs`): + + ```shell + export NAME="s.jobs" + ``` diff --git a/content/nginx-one/metrics/enable-metrics.md b/content/nginx-one/metrics/enable-metrics.md index 0e677a78c..02894c2c1 100644 --- a/content/nginx-one/metrics/enable-metrics.md +++ b/content/nginx-one/metrics/enable-metrics.md @@ -14,10 +14,16 @@ nd-product: NGINX-One The NGINX One Console dashboard relies on APIs for NGINX Plus and NGINX Open Source Stub Status to report traffic and system metrics. The following sections show you how to enable those metrics. -### Enable NGINX Plus API +## Enable NGINX Plus API and dashboard {{< include "/use-cases/monitoring/enable-nginx-plus-api.md" >}} -### Enable NGINX Open Source Stub Status API +## Enable NGINX Plus API and dashboard with Config Sync Groups + +To enable the NGINX Plus API and dashboard with [Config Sync Groups]({{< ref "nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}), add a file named `/etc/nginx/conf.d/dashboard.conf` to your shared group config. Any instance you add to that group automatically uses those settings. + +{{< include "use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md" >}} + +## Enable NGINX Open Source Stub Status API {{< include "/use-cases/monitoring/enable-nginx-oss-stub-status.md" >}} diff --git a/content/nginx-one/workshops/lab2/run-workshop-components-with-docker.md b/content/nginx-one/workshops/lab2/run-workshop-components-with-docker.md index 13eefc45d..516bb3c7a 100644 --- a/content/nginx-one/workshops/lab2/run-workshop-components-with-docker.md +++ b/content/nginx-one/workshops/lab2/run-workshop-components-with-docker.md @@ -28,7 +28,7 @@ Make sure you have: - NGINX One service enabled in your XC account - Docker and Docker Compose installed and running - An active data plane key from [Lab 1: Get started with NGINX One Console]({{< ref "nginx-one/workshops/lab1/getting-started-with-nginx-one.md" >}}) -- A trial or paid NGINX Plus JWT license (saved as `nginx-repo.jwt`) from [MyF5](https://my.f5.com/manage/s/). +- A trial or paid NGINX One JWT license (saved as `nginx-repo.jwt`) from [MyF5](https://my.f5.com/manage/s/). - Basic Linux and NGINX know-how - Git installed and SSH key set up for GitHub access @@ -48,9 +48,9 @@ Make sure you have: cd static/workshops/nginx-one/lab2 ``` -This folder contains `docker-compose.yml` and `generate_certs.sh`. +This folder contains `compose.yaml` and `generate_certs.sh`. -{{}} {{}} +{{}} {{}} {{}} {{}} diff --git a/content/nginx-one/workshops/lab3/explore-nginx-one-console-and-features.md b/content/nginx-one/workshops/lab3/explore-nginx-one-console-and-features.md index 3d2a7a296..cfd9209aa 100644 --- a/content/nginx-one/workshops/lab3/explore-nginx-one-console-and-features.md +++ b/content/nginx-one/workshops/lab3/explore-nginx-one-console-and-features.md @@ -34,12 +34,7 @@ Make sure you have: - An F5 Distributed Cloud (XC) account with NGINX One enabled - All containers from [Lab 2](nginx-one/workshops/lab2/run-workshop-components-with-docker.md) running and registered -- Your unique identifier in the `NAME` environment variable (set in Lab 2), for example `s.jobs`: - - ```shell - export NAME="s.jobs" - ``` - +- {{< include "workshops/nginx-one-env-variables.md" >}} - Basic NGINX and Linux knowledge --- diff --git a/content/nginx-one/workshops/lab4/config-sync-groups.md b/content/nginx-one/workshops/lab4/config-sync-groups.md index 0ae85bb55..0e4190975 100644 --- a/content/nginx-one/workshops/lab4/config-sync-groups.md +++ b/content/nginx-one/workshops/lab4/config-sync-groups.md @@ -24,24 +24,7 @@ Make sure you have: - Completed [Lab 2: Run workshop components with Docker]({{< ref "nginx-one/workshops/lab2/run-workshop-components-with-docker.md" >}}) - Docker and Docker Compose installed and running -- Your data plane key in the `TOKEN` environment variable (set in Lab 2): - - ```shell - export TOKEN="your-data-plane-key" - ``` - -- Your NGINX Plus JWT license file saved as `nginx-repo.jwt`, and `JWT` set (set in Lab 2): - - ```shell - export JWT=$(cat path/to/nginx-repo.jwt) - ``` - -- Your unique identifier in the NAME environment variable (set in Lab 2), for example `s.jobs`: - - ```shell - export NAME="s.jobs" - ``` - +- {{< include "workshops/nginx-one-env-variables.md" >}} - Basic familiarity with Linux command line and NGINX concepts --- @@ -134,7 +117,7 @@ You can edit the `docker-config.yaml` file to add those instances to the config docker compose down ``` -2. Open `docker-compose.yaml` in a text editor. +2. Open `compose.yaml` in a text editor. 3. Uncomment the lines beginning with: ```yaml diff --git a/content/nginx-one/workshops/lab5/upgrade-nginx-plus-to-latest-version.md b/content/nginx-one/workshops/lab5/upgrade-nginx-plus-to-latest-version.md new file mode 100644 index 000000000..08ca64339 --- /dev/null +++ b/content/nginx-one/workshops/lab5/upgrade-nginx-plus-to-latest-version.md @@ -0,0 +1,178 @@ +--- +title: "Lab 5: Upgrade NGINX Plus to the latest version" +weight: 500 +toc: true +nd-content-type: tutorial +nd-product: +- nginx-one +- nginx-plus +--- + +## Overview + +In this lab, you upgrade NGINX Plus from R32 (or earlier) to the latest version in two ways: + +- **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. +- **VM**: Push your JWT license to an existing VM instance, install the new NGINX Plus package, and restart the service. + +Pick the scenario that matches your setup. + +## What you’ll learn + +By the end of this lab, you’ll know how to: + +- Deploy a Docker container running the latest NGINX Plus with NGINX Agent installed +- Add a VM to a Config Sync Group and push your JWT license +- Install or upgrade to the latest NGINX Plus on a VM +- Check version and sync status in the NGINX One Console +- Clean up unavailable instances in the NGINX One Console + +## Before you begin + +Make sure you have: + +- Completed [Lab 4: Config Sync Groups]({{< ref "nginx-one/workshops/lab4/config-sync-groups.md" >}}) +- Docker and Docker Compose installed and running (for Docker scenario) +- A trial or paid NGINX One JWT license (saved as `nginx-repo.jwt`) from [MyF5](https://my.f5.com/manage/s/). +- A VM with NGINX Plus R32 (or earlier), SSH access, and the NGINX Agent installed (for VM scenario) +- {{< include "workshops/nginx-one-env-variables.md" >}} +- Basic familiarity with Linux command line and NGINX concepts + +## Scenario A: Upgrade NGINX Plus in Docker + +### Exercise A1: Pull and run the latest NGINX Plus image + +1. In your shell, log in to the private registry: + + ```shell + echo "$JWT" | docker login private-registry.nginx.com \ + --username "$JWT" --password-stdin + ``` + +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. + + ```yaml + plus4: # Debian latest NGINX Plus Web / Load Balancer + environment: + NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' + NGINX_AGENT_SERVER_GRPCPORT: '443' + NGINX_AGENT_TLS_ENABLE: 'true' + NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console + NGINX_LICENSE_JWT: $JWT + NGINX_AGENT_INSTANCE_GROUP: $NAME-sync-group + hostname: $NAME-plus4 + container_name: $NAME-plus4 + image: private-registry.nginx.com/nginx-plus/agent:debian # From NGINX Private Registry + volumes: # Sync these folders to container + - ./nginx-plus/etc/nginx/nginx.conf:/etc/nginx/nginx.conf + - ./nginx-plus/etc/nginx/conf.d:/etc/nginx/conf.d + - ./nginx-plus/etc/nginx/includes:/etc/nginx/includes + - ./nginx-plus/usr/share/nginx/html:/usr/share/nginx/html + ports: + - '80' # Open for HTTP + - '443' # Open for HTTPS + - '9000' # Open for API / Dashboard page + - '9113' # Open for Prometheus Scraper page + restart: always + ``` + + {{< call-out "note" "Tip" "" >}} If you use VS Code, highlight lines 74–95 and press `Ctrl` + `/` to uncomment them. {{< /call-out >}} + +3. Restart your containers: + + ```shell + docker compose down && docker compose up --force-recreate -d + ``` + +4. In the NGINX One Console, go to **Instances**. +5. You should see your new instance (`$NAME-plus4`) in the list (for example, `s.jobs-plus4`). +6. Select that instance and verify it runs the latest versions of NGINX Plus and NGINX Agent. +7. The `$NAME-plus4` container was added to the `$NAME-sync-group` config sync group and inherited the shared config. + + {{< 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 >}} + +### Exercise A2: Delete unavailable containers + +When you recreate containers, they re-register in the NGINX One Console. Use the filter to clean up old entries: + +1. In the NGINX One Console, go **Instances**. +2. Select **Add filter > Availability > Unavailable**. +3. Check the boxes next to the unavailable hosts. +4. Select **Delete selected**, then confirm. +5. Remove the filter: Hover over the **Availability is Unavailable** filter tag, then select **X** to clear it and show all instances again. + + +{{< img src="nginx-one/images/unavailable-instances.png" + 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." >}} + + +## Scenario B: Use Config Sync Groups to upgrade NGINX Plus on a VM + +{{< call-out "note" "Note" >}} +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. +{{}} + +### Exercise B1: Create a Config Sync Group for VMs + +1. In the NGINX One Console, go to **Manage > Config Sync Groups**. +2. Select **Add Config Sync Group**. +3. In the **Name** field, enter `$NAME-sync-group-vm` (for example, `s.jobs-sync-group-vm`), then select **Create**. + +### Exercise B2: Add your VM to the Config Sync Group + +1. Select **Manage > Config Sync Groups**, then pick your config sync group's name. +2. On the **Details** tab, in the **Instances** pane, select **Add Instance to Config Sync Group**. +3. Select **Register a new instance with NGINX One then add to config sync group**, then select **Next**. +4. Select **Use existing key**, paste `` into the **Data Plane Key** box. +5. Copy the pre-filled `curl` command and run it on your VM: + + **Example**: + + ```shell + curl https://agent.connect.nginx.com/nginx-agent/install | \ + DATA_PLANE_KEY="" \ + sh -s -- -y -c "" + ``` + +6. Back in the NGINX One Console, select **Refresh**. Your VM appears in the list and its **Config Sync Status** shows **In Sync**. + +### Exercise B3: Enable the NGINX Plus API and dashboard + +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. + +{{< include "use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md" >}} + +### Exercise B4: Add your JWT license file + +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. + +1. In the NGINX One Console, select **Manage > Config Sync Groups**, then pick your config sync group's name. +2. Select the **Configuration** tab, then **Edit Configuration**. +3. Select **Add File**. +4. Select **New Configuration File**. +5. In the **File name** box, enter `/etc/nginx/license.jwt` (the filename must match exactly), then select **Add**. +6. Paste the contents of your JWT file into new file workspace. +7. Select **Next**, review the diff, then select **Save and Publish**. + +For more information, see [About subscription licenses]({{< ref "solutions/about-subscription-licenses.md" >}}). + +### Exercise B5: Upgrade NGINX Plus on your VM + +1. Upgrade the NGINX Plus package on your VM: + + - **RHEL, Amazon Linux, CentOS, Oracle Linux, AlmaLinux, Rocky Linux** + + ```shell + sudo yum upgrade nginx-plus + ``` + + - **Debian, Ubuntu** + + ```shell + sudo apt update && sudo apt install nginx-plus + ``` + +2. In the NGINX One Console, go to **Manage > Instances**. +3. Select your VM instance in the list. +4. In the Instance Details panel, confirm the NGINX Plus version has been updated. +5. If the version doesn’t update right away, refresh the page after a few seconds. \ No newline at end of file diff --git a/static/nginx-one/images/unavailable-instances.png b/static/nginx-one/images/unavailable-instances.png new file mode 100644 index 000000000..8414825dc Binary files /dev/null and b/static/nginx-one/images/unavailable-instances.png differ diff --git a/static/workshops/nginx-one/lab2/docker-compose.yml b/static/workshops/nginx-one/lab2/compose.yaml similarity index 81% rename from static/workshops/nginx-one/lab2/docker-compose.yml rename to static/workshops/nginx-one/lab2/compose.yaml index a22431c7d..65f2d30cb 100644 --- a/static/workshops/nginx-one/lab2/docker-compose.yml +++ b/static/workshops/nginx-one/lab2/compose.yaml @@ -32,7 +32,7 @@ services: NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' NGINX_AGENT_SERVER_GRPCPORT: '443' NGINX_AGENT_TLS_ENABLE: 'true' - NGINX_AGENT_SERVER_TOKEN: $TOKEN # Datakey Fron Nginx One Console + NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console # NGINX_AGENT_INSTANCE_GROUP: $NAME-sync-group hostname: $NAME-plus2 container_name: $NAME-plus2 @@ -54,7 +54,7 @@ services: NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' NGINX_AGENT_SERVER_GRPCPORT: '443' NGINX_AGENT_TLS_ENABLE: 'true' - NGINX_AGENT_SERVER_TOKEN: $TOKEN # Datakey Fron Nginx One Console + NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console # NGINX_AGENT_INSTANCE_GROUP: $NAME-sync-group hostname: $NAME-plus3 container_name: $NAME-plus3 @@ -71,12 +71,35 @@ services: - '9113' # Open for Prometheus Scraper page restart: always # + # plus4: # Debian R34 NGINX Plus Web / Load Balancer + # environment: + # NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' + # NGINX_AGENT_SERVER_GRPCPORT: '443' + # NGINX_AGENT_TLS_ENABLE: 'true' + # NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console + # NGINX_LICENSE_JWT: $JWT + # NGINX_AGENT_INSTANCE_GROUP: $NAME-sync-group + # hostname: $NAME-plus4 + # container_name: $NAME-plus4 + # image: private-registry.nginx.com/nginx-plus/agent:debian # From NGINX Private Registry R34 + # volumes: # Sync these folders to container + # - ./nginx-plus/etc/nginx/nginx.conf:/etc/nginx/nginx.conf + # - ./nginx-plus/etc/nginx/conf.d:/etc/nginx/conf.d + # - ./nginx-plus/etc/nginx/includes:/etc/nginx/includes + # - ./nginx-plus/usr/share/nginx/html:/usr/share/nginx/html + # ports: + # - '80' # Open for HTTP + # - '443' # Open for HTTPS + # - '9000' # Open for API / Dashboard page + # - '9113' # Open for Prometheus Scraper page + # restart: always + # oss1: # Debian NGINX OSS Web / Load Balancer environment: NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' NGINX_AGENT_SERVER_GRPCPORT: '443' NGINX_AGENT_TLS_ENABLE: 'true' - NGINX_AGENT_SERVER_TOKEN: $TOKEN # Datakey Fron Nginx One Console + NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console hostname: $NAME-oss1 container_name: $NAME-oss1 image: docker-registry.nginx.com/nginx/agent:mainline # From Docker Public Registry @@ -98,7 +121,7 @@ services: NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' NGINX_AGENT_SERVER_GRPCPORT: '443' NGINX_AGENT_TLS_ENABLE: 'true' - NGINX_AGENT_SERVER_TOKEN: $TOKEN # Datakey Fron Nginx One Console + NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console hostname: $NAME-oss2 container_name: $NAME-oss2 image: docker-registry.nginx.com/nginx/agent:alpine # From Docker Public Registry @@ -120,7 +143,7 @@ services: NGINX_AGENT_SERVER_HOST: 'agent.connect.nginx.com' NGINX_AGENT_SERVER_GRPCPORT: '443' NGINX_AGENT_TLS_ENABLE: 'true' - NGINX_AGENT_SERVER_TOKEN: $TOKEN # Datakey Fron Nginx One Console + NGINX_AGENT_SERVER_TOKEN: $TOKEN # Data plane key from NGINX One Console hostname: $NAME-oss3 container_name: $NAME-oss3 image: docker-registry.nginx.com/nginx/agent:1.26-alpine # From Docker Public Registry