Skip to content

Epic 472 port nginx one labs #681

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 46 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
9698077
Added lab 1
travisamartin May 30, 2025
2df7454
added lab2
travisamartin May 30, 2025
25f374f
added steps for lab 2
travisamartin Jun 10, 2025
411d3b8
moved lab files out of content dir
travisamartin Jun 10, 2025
1e1af12
added lab 3
travisamartin Jun 10, 2025
56fa0e5
Merge remote-tracking branch 'origin' into epic-472-port-nginx-one-labs
travisamartin Jun 10, 2025
c44decd
edits to lab 3
travisamartin Jun 10, 2025
5bd0015
Merge branch 'port-lab-3' of github.com:nginx/documentation into port…
travisamartin Jun 11, 2025
d03aa23
deleted unused file
travisamartin Jun 11, 2025
5f50bea
edits to lab 3
travisamartin Jun 17, 2025
a4b29ca
Merge remote-tracking branch 'origin' into epic-472-port-nginx-one-labs
travisamartin Jun 17, 2025
a9ecc38
Merge branch 'epic-472-port-nginx-one-labs' into port-lab-3
travisamartin Jun 17, 2025
67423e7
fixed link
travisamartin Jun 17, 2025
7d42168
deleted 1-day and 30-day certs and keys
travisamartin Jun 17, 2025
f6faf61
Ported lab 4
travisamartin Jun 17, 2025
d437960
Merge branch 'epic-472-port-nginx-one-labs' into port-n1-lab-4-workshop
travisamartin Jun 20, 2025
a04b3e7
edits to note re combining NOSS and N+ in config sync groups
travisamartin Jun 21, 2025
8c8580e
Merge remote-tracking branch 'origin' into epic-472-port-nginx-one-labs
travisamartin Jun 23, 2025
bd9ada1
Merge remote-tracking branch 'origin' into epic-472-port-nginx-one-labs
travisamartin Jun 24, 2025
c3046e1
Merge remote-tracking branch 'origin' into epic-472-port-nginx-one-labs
travisamartin Jun 24, 2025
7a90fb8
Merge remote-tracking branch 'origin' into epic-472-port-nginx-one-labs
travisamartin Jun 25, 2025
fa6260f
Port lab 5 (#733)
travisamartin Jun 25, 2025
fac3953
edits per tech review
travisamartin Jun 25, 2025
f46af90
Merge branch 'epic-472-port-nginx-one-labs' of github.com:nginx/docum…
travisamartin Jun 25, 2025
b461555
Apply suggestions from code review
travisamartin Jun 25, 2025
bfb0fec
reordered N1 workshops in nav
travisamartin Jun 25, 2025
4b312a1
edits
travisamartin Jun 25, 2025
16c7d06
added verification step for enabling N+ API using CSG
travisamartin Jun 25, 2025
e7b1ede
added card for workshops to index page
travisamartin Jun 25, 2025
54faf01
Merge branch 'main' into epic-472-port-nginx-one-labs
travisamartin Jun 25, 2025
5d33ebd
fixed workshops card link
travisamartin Jun 25, 2025
8a59ccc
Merge branch 'main' into epic-472-port-nginx-one-labs
lamATnginx Jun 26, 2025
2e00869
Update workshops card link
lamATnginx Jun 26, 2025
82567cf
Merge branch 'main' into epic-472-port-nginx-one-labs
travisamartin Jun 26, 2025
e5982d4
Merge branch 'main' into epic-472-port-nginx-one-labs
lamATnginx Jul 1, 2025
9bc04c0
Fix url link in N1 landing + changed to workshop for featured card
lamATnginx Jul 1, 2025
a6b54bf
Merge branch 'main' into epic-472-port-nginx-one-labs
travisamartin Jul 1, 2025
a939950
Merge remote-tracking branch 'origin' into epic-472-port-nginx-one-labs
travisamartin Jul 2, 2025
a1b62b3
edited N1 card text to include Console
travisamartin Jul 2, 2025
c6b5352
removed Apache license
travisamartin Jul 8, 2025
5083348
Merge remote-tracking branch 'origin' into epic-472-port-nginx-one-labs
travisamartin Jul 8, 2025
61b7954
added workshop card
travisamartin Jul 8, 2025
c4daaa7
Merge branch 'main' into epic-472-port-nginx-one-labs
travisamartin Jul 8, 2025
7b5786e
added wrench icon to workshop card
travisamartin Jul 8, 2025
bd1fd9d
Merge branch 'epic-472-port-nginx-one-labs' of github.com:nginx/docum…
travisamartin Jul 8, 2025
275abe7
Merge branch 'main' into epic-472-port-nginx-one-labs
travisamartin Jul 9, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,4 @@ server {
root /usr/share/nginx/html;
}
}
```
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
docs:
files:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note to self: add file references here.

-
-
---

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**.
8. Open your browser to `http://<instance-ip>:9000/dashboard.html` (replace `<instance-ip>` with the IP or hostname of one of your group members). You should see the NGINX Plus dashboard.
Original file line number Diff line number Diff line change
Expand Up @@ -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).
{{</ call-out >}}

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" >}}).
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" >}}).
27 changes: 27 additions & 0 deletions content/includes/workshops/nginx-one-env-variables.md
Original file line number Diff line number Diff line change
@@ -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"
```
22 changes: 16 additions & 6 deletions content/nginx-one/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,18 @@ F5 NGINX One Console makes it easy to manage NGINX instances across locations an
{{<card title="Get started" titleUrl="/nginx-one/getting-started/" isFeatured="true" icon="unplug">}}
Get up and running with NGINX One Console
{{</card >}}
{{</card-section>}}
{{</card-layout>}}


{{<card-layout>}}
{{<card-section showAsCards="true" >}}
{{<card title="Connect more NGINX instances" titleUrl="/nginx-one/connect-instances/" >}}
Work with data plane keys, containers, and proxy servers
{{</card>}}
{{<card title="Manage your NGINX instances" titleUrl="/nginx-one/nginx-configs/" >}}
Manage one instance or groups of instances. Monitor certificates. Set up metrics.
{{</card>}}
{{</card-section>}}
{{</card-layout>}}


{{<card-layout>}}
{{<card-section showAsCards="true" >}}
{{<card title="Organize users with RBAC" titleUrl="/nginx-one/rbac/" >}}
Assign responsibilities with role-based access control
{{</card>}}
Expand All @@ -45,6 +45,16 @@ F5 NGINX One Console makes it easy to manage NGINX instances across locations an
{{</card-section>}}
{{</card-layout>}}

### Workshops

{{<card-layout>}}
{{<card-section showAsCards="true">}}
{{<card title="NGINX One Console workshops" titleUrl="/nginx-one/workshops/" icon="wrench" >}}
Learn how to register and manage NGINX instances in NGINX One Console. View CVE and configuration recommendations. Use Config Sync Groups to deploy JWT licenses and upgrade to the latest NGINX Plus.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a way to set this up with bullets?

  • Alternatively, I'm tempted to set up different cards for the "unique" use cases
    • We already cover your first sentence in "Manage your NGINX instances"
    • Use case: "Review CVEs and our recommended config changes"
    • Use case: "Manage groups of instances (Config Sync Groups) to update licenses and upgrade systems with one command"

Screenshot 2025-07-09 at 7 05 50 AM

{{</card>}}
{{</card-section>}}
{{</card-layout>}}

### More information

{{<card-layout>}}
Expand Down
10 changes: 8 additions & 2 deletions content/nginx-one/nginx-configs/metrics/enable-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}
6 changes: 6 additions & 0 deletions content/nginx-one/workshops/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
title: Workshops
description:
weight: 750
url: /nginx-one/workshops
---
126 changes: 126 additions & 0 deletions content/nginx-one/workshops/lab1/getting-started-with-nginx-one.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
---
title: "Lab 1: Get started with NGINX One Console"
weight: 100
toc: true
nd-content-type: tutorial
nd-product: NGINX-ONE
---

## Introduction

This guide helps you log in to NGINX One Console and understand the basics of how it works. You’ll learn how to get started, find your way around the console, and manage your NGINX instances using data plane keys.

## What you’ll learn

By the end of this tutorial, you’ll know how to:

- Open and use NGINX One Console
- Understand what NGINX One Console does and how it works
- Create, copy, and save a data plane key
- Revoke or delete a data plane key (optional)

## Before you begin

Make sure you have:

- An F5 Distributed Cloud (XC) account
- NGINX One service enabled in your account
Comment on lines +26 to +27
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You might be able to use these includes:

nginx-one/cloud-access.md
nginx-one/cloud-access-nginx.md

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If enabling NGINX One is a separate step, I might need to update cloud-access-nginx.md

- Basic knowledge of Linux and NGINX

---

## Learn what NGINX One Console does

NGINX One Console is a cloud-based service in the F5 Distributed Cloud platform. It helps you:

- Manage all your NGINX instances from one place
- Monitor performance and health metrics
- Catch security risks like expired SSL certificates and known vulnerabilities
- Keep track of software versions and get performance tips
Comment on lines +36 to +39
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be tempted to add links, but that's a "stretch" goal IMO


With NGINX One Console, you don’t need to switch between tools. You get a single dashboard with real-time data and alerts.

---

## How NGINX One Console works

NGINX One Console connects to each NGINX instance using a lightweight agent called **NGINX Agent**.

NGINX Agent is responsible for securely registering and managing each instance through the console.

There are a few ways to install NGINX Agent:

- Use public Docker images of NGINX Open source that already include NGINX Agent
- Use NGINX Plus containers with NGINX Agent preinstalled
- Install manually using package managers like `apt` or `yum`
- Use the one-line curl command that NGINX One provides during registration

Comment on lines +53 to +57
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd like some links to examples

When you register a new instance in the console, you'll get a ready-to-use `curl` command that downloads and installs the NGINX Agent on your target system.

For more information about NGINX Agent, see the [NGINX Agent documentation]({{< ref "/agent/about.md" >}}).

---

## Open and use NGINX One Console

1. Go to [https://console.ves.volterra.io/login/start](https://console.ves.volterra.io/login/start).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I go to this URL, I get the following screen. We're referring to domain as a tenant

Screenshot 2025-07-09 at 7 59 42 AM

In cloud-access.md, I'm using:

"Navigate to https://INSERT_YOUR_TENANT_NAME.console.ves.volterra.io/ to access F5 Distributed Cloud."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related -- we're about ready to release #731 (Once XC makes their June release, maybe on July 14)

2. Sign in using your Distributed Cloud account.
3. On the home page, find the **NGINX One** tile.
4. Select the tile to open the console.
5. Make sure the service status shows **Enabled**.
6. Select **Visit Service** to go to the **Overview** dashboard.

If NGINX One Console isn’t enabled, contact your XC administrator to request access.

When no NGINX instances are connected, the dashboard will be empty. Once you add instances, it will show metrics like availability, version, and usage trends.

---

## Create and save a data plane key
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Future issue: we may be able to set up more common content


To register NGINX instances, you need a data plane key.

1. In the console, go to **Manage > Data Plane Keys**.
2. Select **Add Data Plane Key**.
3. Enter a name for the key.
4. Set an expiration date (or keep the default of one year).
5. Select **Generate**.
6. Copy the key when it appears—**you won’t be able to see it again**.
7. Save it somewhere safe.

You can use the same key to register many instances. If you lose the key, you’ll need to create a new one.

---

## (Optional) Revoke a data plane key

To disable a key:

1. On the **Data Plane Keys** page, find the key you want to revoke.
2. Select the key.
3. Choose **Revoke**, then confirm.

---

## (Optional) Delete a revoked key

You can only delete a key after you revoke it.

1. On the **Revoked Keys** tab, find the key you want to delete.
2. Select the key.
3. Choose **Delete Selected**, then confirm.

---

## Next steps

Now that you’ve explored NGINX One Console and created a key, you’re ready to connect your first NGINX instance.

Go to [Lab 2: Run workshop components with Docker]({{< ref "nginx-one/workshops/lab2/run-workshop-components-with-docker.md" >}})

---

## References

- [Create and manage data plane keys]({{< ref "nginx-one/connect-instances/create-manage-data-plane-keys.md" >}})
- [NGINX Agent overview]({{< ref "/agent/about.md" >}})
Loading