Skip to content

Commit 9c86aab

Browse files
jjngxAlexFenlon
jjngx
authored and
AlexFenlon
committed
WAF v5 docs update (#5719)
1 parent fec66af commit 9c86aab

File tree

13 files changed

+601
-25
lines changed

13 files changed

+601
-25
lines changed

‎docs/content/installation/building-nginx-ingress-controller.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,14 +143,17 @@ Key targets include:
143143
| _alpine-image_ | Builds an Alpine-based image with NGINX. |
144144
| _alpine-image-plus_ | Builds an Alpine-based image with NGINX Plus. |
145145
| _alpine-image-plus-fips_ | Builds an Alpine-based image with NGINX Plus and FIPS. |
146+
| _alpine-image-nap-v5-plus-fips_ | Builds an Alpine-based image with NGINX Plus, the [NGINX App Protect WAF v5](/nginx-app-protect/) module and FIPS. |
146147
| _debian-image_ | Builds a Debian-based image with NGINX. |
147148
| _debian-image-plus_ | Builds a Debian-based image with NGINX Plus. |
148149
| _debian-image-nap-plus_ | Builds a Debian-based image with NGINX Plus and the [NGINX App Protect WAF](/nginx-app-protect/) module. |
150+
| _debian-image-nap-v5-plus_ | Builds a Debian-based image with NGINX Plus and the [NGINX App Protect WAF v5](/nginx-app-protect/) module. |
149151
| _debian-image-dos-plus_ | Builds a Debian-based image with NGINX Plus and the [NGINX App Protect DoS](/nginx-app-protect-dos/) module. |
150152
| _debian-image-nap-dos-plus_ | Builds a Debian-based image with NGINX Plus, [NGINX App Protect WAF](/nginx-app-protect/) and [NGINX App Protect DoS](/nginx-app-protect-dos/) modules. |
151153
| _ubi-image_ | Builds a UBI-based image with NGINX for [OpenShift](https://www.openshift.com/) clusters. |
152154
| _ubi-image-plus_ | Builds a UBI-based image with NGINX Plus for [OpenShift](https://www.openshift.com/) clusters. |
153155
| _ubi-image-nap-plus_ | Builds a UBI-based image with NGINX Plus and the [NGINX App Protect WAF](/nginx-app-protect/) module for [OpenShift](https://www.openshift.com/) clusters. |
156+
| _ubi-image-nap-v5-plus_ | Builds a UBI-based image with NGINX Plus and the [NGINX App Protect WAF v5](/nginx-app-protect/) module for [OpenShift](https://www.openshift.com/) clusters. |
154157
| _ubi-image-dos-plus_ | Builds a UBI-based image with NGINX Plus and the [NGINX App Protect DoS](/nginx-app-protect-dos/) module for [OpenShift](https://www.openshift.com/) clusters. |
155158
| _ubi-image-nap-dos-plus_ | <p>Builds a UBI-based image with NGINX Plus, [NGINX App Protect WAF](/nginx-app-protect/) and the [NGINX App Protect DoS](/nginx-app-protect-dos/) module for [OpenShift](https://www.openshift.com/) clusters.</p> <p> **Important**: Save your RHEL organization and activation keys in a file named _rhel_license_ at the project root.</p> <p> For instance:</p> <pre>RHEL_ORGANIZATION=1111111<br />RHEL_ACTIVATION_KEY=your-key</pre>|
156159
{{</bootstrap-table>}}

‎docs/content/installation/integrations/app-protect-dos/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: NGINX App Protect DoS
33
description: Learn how to use NGINX Ingress Controller for Kubernetes with NGINX App Protect DoS.
4-
weight: 200
4+
weight: 300
55
menu:
66
docs:
77
parent: Integrations

‎docs/content/installation/integrations/app-protect-waf-v5/_index.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: NGINX App Protect WAF v5
3+
description: Learn how to use NGINX Ingress Controller for Kubernetes with NGINX App Protect version 5.
4+
weight: 200
5+
menu:
6+
docs:
7+
parent: NGINX Ingress Controller
8+
---

‎docs/content/installation/integrations/app-protect-waf-v5/configuration.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
docs: DOCS-000
3+
title: Configuration
4+
toc: true
5+
weight: 200
6+
---
7+
8+
9+
## Overview
10+
11+
This document explains how to use F5 NGINX Ingress Controller to configure [NGINX App Protect WAF v5](https://docs.nginx.com/nginx-app-protect-waf/v5/).
12+
13+
{{< note >}} Check out the complete NGINX Ingress Controller with NGINX App Protect WAF example resources on GitHub [for VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.6.0/examples/custom-resources/app-protect-waf-v5) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.6.0/examples/ingress-resources/app-protect-waf-v5).{{< /note >}}
14+
15+
16+
## Global Configuration
17+
18+
NGINX Ingress Controller has global configuration parameters that match those in NGINX App Protect WAF. They are found in the [ConfigMap resource]({{< relref "configuration/global-configuration/configmap-resource.md#modules" >}}): the NGINX App Protect WAF parameters are prefixed with `app-protect*`.
19+
20+
## Enable NGINX App Protect WAF v5
21+
22+
NGINX App Protect WAF can be enabled and configured for custom resources (VirtualServer, VirtualServerRoute) or Ingress resources.
23+
24+
- For custom resources, you need to create a Policy Custom Resource referencing a policy bundle, then add it to the VirtualServer definition. Additional detail can be found in the [Policy Resource documentation]({{< relref "configuration/policy-resource.md#waf" >}}).
25+
- For Ingress resources, apply the [`app-protect` annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) to each desired resource.
26+
27+
28+
29+
## NGINX App Protect WAF Bundles {#waf-bundles}
30+
31+
You define App Protect WAF bundles for VirtualServer custom resources by creating policy bundles and putting them on a mounted volume accessible from NGINX Ingress Controller.
32+
33+
Before applying a policy, a WAF policy bundle must be created, then copied to a volume mounted to `/etc/app_protect/bundles`.
34+
35+
{{< note >}} NGINX Ingress Controller supports `securityLogs` for policy bundles. Log bundles must also be copied to a volume mounted to `/etc/app_protect/bundles`. {{< /note >}}
36+
37+
This example shows how a policy is configured by referencing a generated WAF Policy Bundle:
38+
39+
40+
```yaml
41+
apiVersion: k8s.nginx.org/v1
42+
kind: Policy
43+
metadata:
44+
name: <policy_name>
45+
spec:
46+
waf:
47+
enable: true
48+
apBundle: "<policy_bundle_name>.tgz"
49+
```
50+
51+
This example shows the same policy as above but with a log bundle used for security log configuration:
52+
53+
54+
```yaml
55+
apiVersion: k8s.nginx.org/v1
56+
kind: Policy
57+
metadata:
58+
name: <policy_name>
59+
spec:
60+
waf:
61+
enable: true
62+
apBundle: "<policy_bundle_name>.tgz"
63+
securityLogs:
64+
- enable: true
65+
apLogBundle: "<log_bundle_name>.tgz"
66+
logDest: "syslog:server=syslog-svc.default:514"
67+
```
68+
69+
## Configuration in NGINX Plus Ingress Controller using Virtual Server Resource
70+
71+
This example shows how to deploy NGINX Ingress Controller with NGINX Plus and NGINX App Protect WAF v5, deploy a simple web application, and then configure load balancing and WAF protection for that application using the VirtualServer resource.
72+
73+
{{< note >}} You can find the files for this example on [GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v3.6.0/examples/custom-resources/app-protect-waf/app-protect-waf-v5).{{< /note >}}
74+
75+
## Prerequisites
76+
77+
1. Follow the installation [instructions]({{< relref "installation/integrations/app-protect-waf-v5/installation.md" >}}) to deploy NGINX Ingress Controller with NGINX Plus and NGINX App Protect WAF version 5.
78+
79+
2. Save the public IP address of NGINX Ingress Controller into a shell variable:
80+
81+
```shell
82+
IC_IP=XXX.YYY.ZZZ.III
83+
```
84+
85+
3. Save the HTTP port of NGINX Ingress Controller into a shell variable:
86+
87+
```shell
88+
IC_HTTP_PORT=<port number>
89+
```
90+
91+
### Step 1. Deploy a Web Application
92+
93+
Create the application deployment and service:
94+
95+
```shell
96+
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.6.0/examples/custom-resources/app-protect-waf-v5/webapp.yaml
97+
```
98+
99+
### Step 2. Create the Syslog Service
100+
101+
Create the syslog service and pod for the NGINX App Protect WAF security logs:
102+
103+
104+
```shell
105+
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.6.0/examples/custom-resources/app-protect-waf-v5/syslog.yaml
106+
```
107+
108+
### Step 3 - Deploy the WAF Policy
109+
110+
111+
{{< note >}} Configuration settings in the Policy resource enable WAF protection by configuring NGINX App Protect WAF with the log configuration created in the previous step. The policy bundle referenced as `your_policy_bundle_name.tgz` need to be created and placed in the `/etc/app_protect/bundles` volume first.{{</ note >}}
112+
113+
Create and deploy the WAF policy.
114+
115+
```shell
116+
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.6.0/examples/custom-resources/app-protect-waf-v5/waf.yaml
117+
```
118+
119+
120+
### Step 4 - Configure Load Balancing
121+
122+
123+
{{< note >}} VirtualServer references the `waf-policy` created in Step 3.{{</ note >}}
124+
125+
1. Create the VirtualServer Resource:
126+
127+
```shell
128+
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.6.0/examples/custom-resources/app-protect-waf-v5/virtual-server.yaml
129+
```
130+
131+
132+
### Step 5 - Test the Application
133+
134+
To access the application, curl the coffee and the tea services. We'll use the `--resolve` option to set the Host header of a request with `webapp.example.com`
135+
136+
1. Send a request to the application:
137+
138+
```shell
139+
curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT/
140+
```
141+
142+
```shell
143+
Server address: 10.12.0.18:80
144+
Server name: webapp-7586895968-r26zn
145+
```
146+
147+
1. Try to send a request with a suspicious URL:
148+
149+
```shell
150+
curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP "http://webapp.example.com:$IC_HTTP_PORT/<script>"
151+
```
152+
153+
```shell
154+
<html><head><title>Request Rejected</title></head><body>
155+
```
156+
157+
1. Check the security logs in the syslog pod:
158+
159+
```shell
160+
kubectl exec -it <SYSLOG_POD> -- cat /var/log/messages
161+
```
162+
163+
### Example VirtualServer configuration
164+
165+
The GitHub repository has a full [VirtualServer example](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.6.0/examples/custom-resources/app-protect-waf-v5/webapp.yaml).
166+
167+
```yaml
168+
apiVersion: k8s.nginx.org/v1
169+
kind: VirtualServer
170+
metadata:
171+
name: webapp
172+
spec:
173+
host: webapp.example.com
174+
policies:
175+
- name: waf-policy
176+
upstreams:
177+
- name: webapp
178+
service: webapp-svc
179+
port: 80
180+
routes:
181+
- path: /
182+
action:
183+
pass: webapp
184+
```

0 commit comments

Comments
 (0)