Skip to content

Commit f1412b4

Browse files
AlexFenlonCopilotvepatel
authored
feat: NGINX One Console for NIC with Agent 3 with F5 WAF (#1897)
* feat: Agent V3 support for WAF for NIC * feat: update docs for NIC WAF Agent 3 images Co-authored-by: Copilot <copilot@github.com> * Update content/nginx-one-console/k8s/add-nic.md * feat: update NIC Agent 3 and image spec docs * feat: update security monitoring documentation Co-authored-by: Copilot <copilot@github.com> * fix: clarifies what file to add the args to Co-authored-by: Copilot <copilot@github.com> * fix: remove unnecessary notes * Update to Debian 13 * Update content/nic/tutorials/security-monitoring.md Co-authored-by: Venktesh Patel <ve.patel@f5.com> --------- Co-authored-by: Copilot <copilot@github.com> Co-authored-by: Venktesh Patel <ve.patel@f5.com>
1 parent fafafb3 commit f1412b4

4 files changed

Lines changed: 478 additions & 42 deletions

File tree

‎content/nginx-one-console/k8s/add-nic.md‎

Lines changed: 117 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,13 @@ Once connected, you'll see a **read-only** configuration of NGINX Ingress Contro
1313

1414
- Read-only configuration file
1515
- Unmanaged SSL/TLS certificates for Control Planes
16+
- F5 WAF for NGINX security events (when using a WAF-enabled image)
1617

1718
## Before you begin
1819

1920
If you do not already have a [data plane key]({{< ref "/nginx-one-console/connect-instances/create-manage-data-plane-keys.md" >}}), you can create one. Pay attention to the expiration date of that key. Any instance that's connected to a data plane key that's expired or revoked will stop working.
2021

21-
You can create a data plane key through the NGINX One Console. Once loggged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown.
22+
You can create a data plane key through the NGINX One Console. Once logged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown.
2223

2324
Before connecting NGINX Ingress Controller to NGINX One Console, you need to create a Kubernetes Secret with the data plane key. Use the following command:
2425

@@ -28,14 +29,27 @@ kubectl create secret generic dataplane-key \
2829
-n <namespace>
2930
```
3031

31-
When you create a Kubernetes Secret, use the same namespace where NGINX Ingress Controller is running.
32-
If you use [`-watch-namespace`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#watch-namespace-string" >}}) or [`watch-secret-namespace`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#watch-secret-namespace-string" >}}) arguments with NGINX Ingress Controller,
32+
When you create a Kubernetes Secret, use the same namespace where NGINX Ingress Controller is running.
33+
If you use [`-watch-namespace`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#watch-namespace-string" >}}) or [`watch-secret-namespace`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#watch-secret-namespace-string" >}}) arguments with NGINX Ingress Controller,
3334
you need to add the dataplane key secret to the watched namespaces. This secret will take approximately 60 - 90 seconds to reload on the pod.
3435

3536
{{< call-out "note" >}}
36-
You can also create a data plane key through the NGINX One Console. Once loggged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown.
37+
You can also create a data plane key through the NGINX One Console. Once logged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown.
3738
{{< /call-out >}}
3839

40+
### Choosing the right image
41+
42+
Starting with NGINX Ingress Controller 5.5.0, images with F5 WAF for NGINX and NGINX Agent 3 are available using the `-agent` suffix. The image you need depends on your deployment:
43+
44+
| Deployment type | Image variant |
45+
|---|---|
46+
| NGINX (open source) | Default image (no special variant needed) |
47+
| NGINX Plus | `nginx-plus-ingress` |
48+
| NGINX Plus with F5 WAF for NGINX v4 | Use an image with the `-nap-agent` suffix (for example, `debian-plus-nap-agent`) |
49+
| NGINX Plus with F5 WAF for NGINX v5 | Use an image with the `-nap-v5-agent` suffix (for example, `debian-plus-nap-v5-agent`) |
50+
51+
See the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}) for the full list of image variants available for each platform.
52+
3953
## Deploy NGINX Ingress Controller with NGINX Agent
4054

4155
{{<tabs name="deploy-config-resource">}}
@@ -63,6 +77,20 @@ Upgrade or install NGINX Ingress Controller with the following command to config
6377
--set nginxAgent.endpointHost=agent.connect.nginx.com
6478
```
6579

80+
- For NGINX Plus with F5 WAF for NGINX v4:
81+
82+
```shell
83+
helm upgrade --install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} \
84+
--set controller.image.repository=myregistry.example.com/nginx-plus-ingress \
85+
--set controller.nginxplus=true \
86+
--set controller.appprotect.enable=true \
87+
--set nginxAgent.enable=true \
88+
--set nginxAgent.dataplaneKeySecretName=<data_plane_key_secret_name> \
89+
--set nginxAgent.endpointHost=agent.connect.nginx.com
90+
```
91+
92+
- For NGINX Plus with F5 WAF for NGINX v5, set `controller.appprotect.v5=true` and configure the enforcer and config manager images. See the [F5 WAF for NGINX v5 installation guide]({{< ref "/nic/integrations/app-protect-waf-v5/installation.md" >}}) for the additional Helm values required.
93+
6694
The `dataplaneKeySecretName` is used to authenticate the agent with NGINX One Console. See the [NGINX One Console Docs]({{< ref "/nginx-one-console/connect-instances/create-manage-data-plane-keys.md" >}})
6795
for instructions on how to generate your dataplane key from the NGINX One Console.
6896

@@ -80,6 +108,10 @@ args:
80108

81109
Create a `ConfigMap` with an `nginx-agent.conf` file:
82110

111+
{{<tabs name="agent-config-manifests">}}
112+
113+
{{%tab name="Without F5 WAF for NGINX"%}}
114+
83115
```yaml
84116
kind: ConfigMap
85117
apiVersion: v1
@@ -93,17 +125,17 @@ data:
93125
level: info
94126
# set log path. if empty, don't log to file.
95127
path: ""
96-
128+
97129
allowed_directories:
98130
- /etc/nginx
99131
- /usr/lib/nginx/modules
100-
132+
101133
features:
102134
- certificates
103135
- connection
104136
- metrics
105137
- file-watcher
106-
138+
107139
## command server settings
108140
command:
109141
server:
@@ -117,35 +149,100 @@ data:
117149
collector:
118150
log:
119151
path: "stdout"
120-
```
152+
```
153+
154+
{{%/tab%}}
155+
156+
{{%tab name="With F5 WAF for NGINX"%}}
157+
158+
```yaml
159+
kind: ConfigMap
160+
apiVersion: v1
161+
metadata:
162+
name: nginx-agent-config
163+
namespace: <namespace>
164+
data:
165+
nginx-agent.conf: |-
166+
log:
167+
# set log level (error, info, debug; default "info")
168+
level: info
169+
# set log path. if empty, don't log to file.
170+
path: ""
121171
122-
Make sure to set the namespace in the nginx-agent.config to the same namespace as NGINX Ingress Controller.
172+
allowed_directories:
173+
- /etc/nginx
174+
- /usr/lib/nginx/modules
175+
- /etc/app_protect
176+
177+
features:
178+
- certificates
179+
- connection
180+
- metrics
181+
- file-watcher
182+
- logs-nap
183+
184+
## command server settings
185+
command:
186+
server:
187+
host: agent.connect.nginx.com
188+
port: 443
189+
auth:
190+
tokenpath: "/etc/nginx-agent/secrets/dataplane.key"
191+
tls:
192+
skip_verify: false
193+
194+
collector:
195+
log:
196+
path: "stdout"
197+
```
198+
199+
The `logs-nap` feature enables NGINX Agent to collect F5 WAF for NGINX security events. The `/etc/app_protect` entry in `allowed_directories` is required for WAF-enabled deployments.
200+
201+
{{%/tab%}}
202+
203+
{{</tabs>}}
204+
205+
Make sure to set the namespace in the ConfigMap to the same namespace as NGINX Ingress Controller.
123206
Mount the ConfigMap to the Deployment/DaemonSet file of NGINX Ingress Controller:
124207

125208
```yaml
126209
volumeMounts:
210+
- name: agent-etc
211+
mountPath: /etc/nginx-agent
127212
- name: nginx-agent-config
128213
mountPath: /etc/nginx-agent/nginx-agent.conf
129214
subPath: nginx-agent.conf
130215
- name: dataplane-key
131216
mountPath: /etc/nginx-agent/secrets
217+
- name: agent-dynamic
218+
mountPath: /var/lib/nginx-agent
132219
volumes:
133220
- name: nginx-agent-config
134221
configMap:
135222
name: nginx-agent-config
223+
- name: agent-etc
224+
emptyDir: {}
136225
- name: dataplane-key
137226
secret:
138227
secretName: "<data_plane_key_secret_name>"
228+
- name: agent-dynamic
229+
emptyDir: {}
139230
```
140231

141232
Follow the [Installation with Manifests]({{< ref "/nic/install/manifests.md" >}}) instructions to deploy NGINX Ingress Controller.
142233

143234
{{%/tab%}}
144235
{{</tabs>}}
145236

237+
## Configure F5 WAF for NGINX security monitoring {#configure-waf-security-monitoring}
238+
239+
When deploying NGINX Ingress Controller with F5 WAF for NGINX, you can forward WAF security events to NGINX One Console for centralized security monitoring.
240+
241+
For full setup instructions, including WAF policy configuration and examples, see [Connect F5 WAF for NGINX to NGINX Security Monitoring]({{< ref "/nic/tutorials/security-monitoring.md" >}}).
242+
146243
## Verify a connection to NGINX One Console
147244

148-
After deploying NGINX Ingress Controller <!-- or NGINX Gateway Fabric --> with NGINX Agent, you can verify the connection to NGINX One Console.
245+
After deploying NGINX Ingress Controller with NGINX Agent, you can verify the connection to NGINX One Console.
149246
Log in to your F5 Distributed Cloud Console account. Select **NGINX One > Visit Service**. In the dashboard, go to **Manage > Instances**. You should see your instances listed by name. The instance name matches both the hostname and the pod name.
150247

151248
## Troubleshooting
@@ -157,16 +254,21 @@ Check the NGINX Agent version:
157254
```shell
158255
kubectl exec -it -n <namespace> <nginx_ingress_pod_name> -- nginx-agent -v
159256
```
160-
161-
If nginx-agent version is v3, continue with the following steps.
162-
Otherwise, make sure you are using an image that does not include F5 WAF for NGINX.
257+
258+
Verify that the output shows `nginx-agent version v3.x.x`. If the agent version is v2, you are using an image that includes NGINX Agent 2 instead of NGINX Agent 3. Use an image variant with the `-agent` suffix (available starting with NGINX Ingress Controller 5.5.0):
259+
260+
- For NGINX Plus without WAF: use the standard NGINX Plus image
261+
- For F5 WAF for NGINX v4: use an image with the `-nap-agent` suffix (for example, `debian-plus-nap-agent`)
262+
- For F5 WAF for NGINX v5: use an image with the `-nap-v5-agent` suffix (for example, `debian-plus-nap-v5-agent`)
163263

164264
Check the NGINX Agent configuration:
165265

166266
```shell
167267
kubectl exec -it -n <namespace> <nginx_ingress_pod_name> -- cat /etc/nginx-agent/nginx-agent.conf
168268
```
169269

270+
If using F5 WAF for NGINX, verify that `logs-nap` is listed under `features` and `/etc/app_protect` is listed under `allowed_directories`.
271+
170272
Check NGINX Agent logs:
171273

172274
```shell
@@ -175,7 +277,7 @@ kubectl exec -it -n <namespace> <nginx_ingress_pod_name> -- nginx-agent
175277

176278
Select the instance associated with your deployment of NGINX Ingress Controller. Under the **Details** tab, you'll see information associated with:
177279
178-
- Unmanaged SSL/TLS certificates for Control Planes
179-
- Configuration recommendations
280+
- Unmanaged SSL/TLS certificates for Control Planes
281+
- Configuration recommendations
180282
181283
Under the **Configuration** tab, you'll see a **read-only** view of the configuration files.

‎content/nic/install/images/registry-download.md‎

Lines changed: 75 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,12 @@ Replace `<version-tag>` with the specific version you need, for example, `{{< ni
5151
docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:<version-tag>
5252
```
5353

54+
- 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:
55+
56+
```shell
57+
docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:<version-tag>-agent
58+
```
59+
5460
- For NGINX Plus Ingress Controller with F5 WAF for NGINX v5, run:
5561

5662
```shell
@@ -65,6 +71,20 @@ Replace `<version-tag>` with the specific version you need, for example, `{{< ni
6571
docker pull private-registry.nginx.com/nap/waf-enforcer:<waf-version-tag>
6672
```
6773

74+
- 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:
75+
76+
```shell
77+
docker pull private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag>-agent
78+
```
79+
80+
```shell
81+
docker pull private-registry.nginx.com/nap/waf-config-mgr:<waf-version-tag>
82+
```
83+
84+
```shell
85+
docker pull private-registry.nginx.com/nap/waf-enforcer:<waf-version-tag>
86+
```
87+
6888
- For NGINX Plus Ingress Controller with F5 DoS for NGINX, run:
6989

7090
```shell
@@ -106,8 +126,33 @@ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/
106126
"name": "nginx-ic-nap/nginx-plus-ingress",
107127
"tags": [
108128
"{{< nic-version >}}-alpine-fips",
129+
"{{< nic-version >}}-alpine-fips-agent",
109130
"{{< nic-version >}}-ubi",
110-
"{{< nic-version >}}"
131+
"{{< nic-version >}}-ubi-agent",
132+
"{{< nic-version >}}-ubi8",
133+
"{{< nic-version >}}-ubi8-agent",
134+
"{{< nic-version >}}",
135+
"{{< nic-version >}}-agent"
136+
]
137+
}
138+
```
139+
140+
```shell
141+
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>
142+
```
143+
144+
```json
145+
{
146+
"name": "nginx-ic-nap-v5/nginx-plus-ingress",
147+
"tags": [
148+
"{{< nic-version >}}-alpine-fips",
149+
"{{< nic-version >}}-alpine-fips-agent",
150+
"{{< nic-version >}}-ubi",
151+
"{{< nic-version >}}-ubi-agent",
152+
"{{< nic-version >}}-ubi8",
153+
"{{< nic-version >}}-ubi8-agent",
154+
"{{< nic-version >}}",
155+
"{{< nic-version >}}-agent"
111156
]
112157
}
113158
```
@@ -145,18 +190,42 @@ After pulling the image, tag it and upload it to your private registry.
145190
docker push <my-docker-registry>/nginx-ic/nginx-plus-ingress:<version-tag>
146191
```
147192

148-
- For NGINX Controller with F5 WAF for NGINX, run:
193+
- For NGINX Plus Ingress Controller with F5 WAF for NGINX, run:
149194

150195
```shell
151196
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>
152197
docker push <my-docker-registry>/nginx-ic-nap/nginx-plus-ingress:<version-tag>
153198
```
154199

155-
- For NGINX Controller with F5 WAF for NGINX v5, run:
200+
- For NGINX Plus Ingress Controller with F5 WAF for NGINX and NGINX Agent 3, run:
156201

157202
```shell
158-
docker tag private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag> <my-docker-registry>/nginx-ic-nap/nginx-plus-ingress:<version-tag>
159-
docker push <my-docker-registry>/nginx-ic-nap/nginx-plus-ingress:<version-tag>
203+
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
204+
docker push <my-docker-registry>/nginx-ic-nap/nginx-plus-ingress:<version-tag>-agent
205+
```
206+
207+
- For NGINX Plus Ingress Controller with F5 WAF for NGINX v5, run:
208+
209+
```shell
210+
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>
211+
docker push <my-docker-registry>/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag>
212+
```
213+
214+
```shell
215+
docker tag private-registry.nginx.com/nap/waf-config-mgr:<waf-version-tag> <my-docker-registry>/nap/waf-config-mgr:<waf-version-tag>
216+
docker push <my-docker-registry>/nap/waf-config-mgr:<waf-version-tag>
217+
```
218+
219+
```shell
220+
docker tag private-registry.nginx.com/nap/waf-enforcer:<waf-version-tag> <my-docker-registry>/nap/waf-enforcer:<waf-version-tag>
221+
docker push <my-docker-registry>/nap/waf-enforcer:<waf-version-tag>
222+
```
223+
224+
- For NGINX Plus Ingress Controller with F5 WAF for NGINX v5 and NGINX Agent 3, run:
225+
226+
```shell
227+
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
228+
docker push <my-docker-registry>/nginx-ic-nap-v5/nginx-plus-ingress:<version-tag>-agent
160229
```
161230

162231
```shell
@@ -169,7 +238,7 @@ After pulling the image, tag it and upload it to your private registry.
169238
docker push <my-docker-registry>/nap/waf-enforcer:<waf-version-tag>
170239
```
171240

172-
- For NGINX Controller with F5 DoS for NGINX, run:
241+
- For NGINX Plus Ingress Controller with F5 DoS for NGINX, run:
173242

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

0 commit comments

Comments
 (0)