Skip to content

Commit 1f47add

Browse files
electricjesuselectricjesus
committed
docs(gateway-waf): apply doc review feedback
Restructure the Gateway WAF section per review: - make the category an empty expansion; move its landing content to overview - drop the Get started page; put prerequisites on each task page - add the tech-preview banner to every page - convert procedures to numbered steps (the tutorial is now one list) - rename the baseline page title to name the feature - move the plugin slot table to overview; trim the Rego example on the validation page
1 parent 8a96343 commit 1f47add

13 files changed

Lines changed: 696 additions & 654 deletions

‎calico-enterprise/threat/deploying-waf-ingress-gateway.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ This feature is tech preview. Tech preview features may be subject to significan
1515

1616
:::caution
1717

18-
This page describes the original, Gateway-wide WAF for Calico Ingress Gateway. It is superseded by [Gateway WAF](./gateway-waf/index.mdx), which adds per-route and per-namespace policies, custom rules, and compliance validation. For Gateway-wide protection equivalent to this guide, attach a `WAFPolicy` to your `Gateway` — see [Attach WAF to a route](./gateway-waf/attach-waf-to-a-route.mdx). This page will be removed in a future release.
18+
This page describes the original, Gateway-wide WAF for Calico Ingress Gateway. It is superseded by [Gateway WAF](./gateway-waf/overview.mdx), which adds per-route and per-namespace policies, custom rules, and compliance validation. For Gateway-wide protection equivalent to this guide, attach a `WAFPolicy` to your `Gateway` — see [Attach WAF to a route](./gateway-waf/attach-waf-to-a-route.mdx). This page will be removed in a future release.
1919

2020
:::
2121

‎calico-enterprise/threat/gateway-waf/attach-waf-to-a-route.mdx‎

Lines changed: 68 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,21 @@ description: Attach a WAFPolicy to a Gateway or HTTPRoute to turn on WAF inspect
44

55
# Attach WAF to a Gateway or route
66

7+
:::note
8+
9+
This feature is tech preview. Tech preview features may be subject to significant changes before they become GA.
10+
11+
:::
12+
713
Create a `WAFPolicy` in your namespace pointing at Gateway API targets — WAF inspection doesn't start automatically when the feature is enabled. It inherits the cluster baseline with namespace overrides layered on top.
814

9-
**Prerequisites:** the cluster operator has created a `GlobalWAFPolicy`; you have write access to `WAFPolicy` in your namespace; a `Gateway`/`HTTPRoute` is already receiving traffic.
15+
## Prerequisites
16+
17+
- The cluster operator has created the `GlobalWAFPolicy` baseline. See [Set a cluster-wide baseline for Gateway WAF](./set-a-baseline.mdx).
18+
- You have write access to `WAFPolicy` in your namespace.
19+
- A `Gateway` or `HTTPRoute` in your namespace is already receiving traffic.
20+
21+
## Choose a target
1022

1123
`WAFPolicy.spec.targetRefs[]` accepts two kinds of targets:
1224

@@ -23,66 +35,74 @@ Each `targetRefs` entry generates a separate `EnvoyExtensionPolicy` (max 16 entr
2335

2436
:::
2537

26-
Attaching WAF to one `HTTPRoute`, overriding action and paranoia; the unset `coreRuleSet.state` still inherits from the baseline:
27-
28-
```yaml
29-
apiVersion: applicationlayer.projectcalico.org/v3
30-
kind: WAFPolicy
31-
metadata:
32-
name: payments-api-waf
33-
namespace: payments
34-
spec:
35-
targetRefs:
36-
- group: gateway.networking.k8s.io
37-
kind: HTTPRoute
38-
name: payments-api
39-
action: Block # override: Block even if global baseline is Detect
40-
coreRuleSet:
41-
paranoiaLevel: 2 # stricter than the cluster default
42-
# coreRuleSet.state is unset → inherited from GlobalWAFPolicy
43-
```
44-
45-
Apply with `kubectl apply -f wafpolicy.yaml`. For custom rules beyond the baseline, see [Write custom rules](./write-custom-rules.mdx); for inheritance details, see the [Overview](./index.mdx#inheritance-namespaces-override-they-dont-restart).
38+
## Attach a WAFPolicy
4639

47-
## Conflict resolution
40+
1. Create a `WAFPolicy` in your namespace pointing at the target. This example attaches to one `HTTPRoute`, overriding action and paranoia; the unset `coreRuleSet.state` still inherits from the baseline:
4841

49-
Only one `WAFPolicy` may be active per target. If two in the same namespace target the same Gateway/HTTPRoute, $[prodname] follows [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/): oldest `creationTimestamp` wins; the newer is marked `Accepted=False` reason `Conflicted`, and only the winner's directives are merged. Fix by deleting the newer policy or repointing its `targetRefs`.
42+
```yaml
43+
apiVersion: applicationlayer.projectcalico.org/v3
44+
kind: WAFPolicy
45+
metadata:
46+
name: payments-api-waf
47+
namespace: payments
48+
spec:
49+
targetRefs:
50+
- group: gateway.networking.k8s.io
51+
kind: HTTPRoute
52+
name: payments-api
53+
action: Block # override: Block even if global baseline is Detect
54+
coreRuleSet:
55+
paranoiaLevel: 2 # stricter than the cluster default
56+
# coreRuleSet.state is unset → inherited from GlobalWAFPolicy
57+
```
5058

51-
## Verify the policy
59+
Apply it with `kubectl apply -f wafpolicy.yaml`. For inheritance details, see the [Overview](./overview.mdx#inheritance-namespaces-override-they-dont-restart).
5260

53-
```bash
54-
kubectl get wafpolicy payments-api-waf -n payments
55-
```
61+
1. Verify the policy was accepted and programmed:
5662

57-
```
58-
NAME ACCEPTED PROGRAMMED AGE
59-
payments-api-waf True True 45s
60-
```
63+
```bash
64+
kubectl get wafpolicy payments-api-waf -n payments
65+
```
6166

62-
`.status.conditions` reports `Accepted`, `Programmed`, and validation findings. Confirm Envoy Gateway received the filter with `kubectl get envoyextensionpolicies -n payments` (one per `targetRefs` entry).
67+
```
68+
NAME ACCEPTED PROGRAMMED AGE
69+
payments-api-waf True True 45s
70+
```
6371

64-
## Test the WAF
72+
`.status.conditions` reports `Accepted`, `Programmed`, and validation findings. Confirm Envoy Gateway received the filter with `kubectl get envoyextensionpolicies -n payments` (one per `targetRefs` entry).
6573

66-
```bash
67-
curl -si "https://<gateway-host>/api?id=1+OR+1%3D1"
68-
```
74+
1. Test that the WAF blocks an attack:
6975

70-
```
71-
HTTP/1.1 403 Forbidden
72-
content-length: 11
73-
content-type: text/plain
76+
```bash
77+
curl -si "https://<gateway-host>/api?id=1+OR+1%3D1"
78+
```
7479

75-
Access denied
76-
```
80+
```
81+
HTTP/1.1 403 Forbidden
82+
content-length: 11
83+
content-type: text/plain
7784
78-
:::tip
85+
Access denied
86+
```
7987

80-
In `Detect` mode the request is allowed (200), but the WAF hit is still recorded in the `tigera_secure_ee_waf` log index (carrying `gateway_name`/`gateway_namespace`). On this release, gateway-WAF hits are not raised as Security Events — see [Observing WAF activity](./troubleshooting.mdx#observing-waf-activity).
88+
:::tip
8189

82-
:::
90+
In `Detect` mode the request is allowed (200), but the WAF hit is still recorded in the `tigera_secure_ee_waf` log index (carrying `gateway_name`/`gateway_namespace`). On this release, gateway-WAF hits are not raised as Security Events — see [Observing WAF activity](./troubleshooting.mdx#observing-waf-activity).
8391

84-
:::caution
92+
:::
8593

86-
`ACCEPTED=False` reason `ValidationFailed` means a `GlobalWAFValidationPolicy` is blocking your config — the status message names the policy and rule. Contact your cluster operator or see [Validate configuration with Rego](./validate-config.mdx).
94+
:::caution
8795

88-
:::
96+
`ACCEPTED=False` reason `ValidationFailed` means a `GlobalWAFValidationPolicy` is blocking your config — the status message names the policy and rule. Contact your cluster operator or see [Validate configuration with Rego](./validate-config.mdx).
97+
98+
:::
99+
100+
## Conflict resolution
101+
102+
Only one `WAFPolicy` may be active per target. If two in the same namespace target the same Gateway/HTTPRoute, $[prodname] follows [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/): oldest `creationTimestamp` wins; the newer is marked `Accepted=False` reason `Conflicted`, and only the winner's directives are merged. Fix by deleting the newer policy or repointing its `targetRefs`.
103+
104+
## Next steps
105+
106+
- [Write custom rules with plugins](./write-custom-rules.mdx) — add app-specific detections beyond the baseline.
107+
- [Validate configuration with Rego](./validate-config.mdx) — check the merged config against compliance guardrails.
108+
- [Troubleshooting](./troubleshooting.mdx) — diagnose a policy that won't accept or program.

‎calico-enterprise/threat/gateway-waf/enable.mdx‎

Lines changed: 50 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -4,62 +4,69 @@ description: Turn Gateway WAF on or off by setting the operator GatewayAPI CR's
44

55
# Enable Gateway WAF
66

7+
:::note
8+
9+
This feature is tech preview. Tech preview features may be subject to significant changes before they become GA.
10+
11+
:::
12+
713
Gateway WAF is off by default. Turning it on is a one-line change to the operator's `GatewayAPI` CR — no new workload is deployed, so there's no extra resource footprint to plan for.
814

9-
## Enable Gateway WAF
15+
## Prerequisites
1016

11-
Edit the operator `GatewayAPI` CR named `default` and set `spec.extensions.waf.state` to `Enabled`. The default value is `Disabled`.
17+
- $[prodname] is installed with a valid license that includes the Gateway WAF feature.
18+
- $[prodname] Ingress Gateway is already set up. See [About Calico Ingress Gateway](../../networking/ingress-gateway/about-calico-ingress-gateway.mdx).
19+
- Cluster-admin rights — the `GatewayAPI` CR is a cluster-scoped operator resource.
1220

13-
```yaml
14-
apiVersion: operator.tigera.io/v1
15-
kind: GatewayAPI
16-
metadata:
17-
name: default
18-
spec:
19-
extensions:
20-
waf:
21-
state: Enabled # default is Disabled
22-
```
21+
:::note
2322

24-
Apply it:
23+
Customer-installed (BYO) Envoy Gateway is not supported. Gateway WAF requires the Ingress Gateway that $[prodname] manages.
2524

26-
```bash
27-
kubectl apply -f - <<'EOF'
28-
apiVersion: operator.tigera.io/v1
29-
kind: GatewayAPI
30-
metadata:
31-
name: default
32-
spec:
33-
extensions:
34-
waf:
35-
state: Enabled
36-
EOF
37-
```
25+
:::
3826

39-
The operator installs the six WAF CRDs and the validating admission webhook, and wires the WAF reconcilers into the existing `calico-kube-controllers` pod in `calico-system`. No new workload is deployed.
27+
## Enable Gateway WAF
4028

41-
Confirm the six CRDs are installed:
29+
1. Edit the operator `GatewayAPI` CR named `default` and set `spec.extensions.waf.state` to `Enabled` (the default is `Disabled`):
4230

43-
```bash
44-
kubectl get crd | grep applicationlayer.projectcalico.org
45-
```
31+
```bash
32+
kubectl apply -f - <<'EOF'
33+
apiVersion: operator.tigera.io/v1
34+
kind: GatewayAPI
35+
metadata:
36+
name: default
37+
spec:
38+
extensions:
39+
waf:
40+
state: Enabled
41+
EOF
42+
```
4643
47-
```text
48-
globalwafplugins.applicationlayer.projectcalico.org
49-
globalwafpolicies.applicationlayer.projectcalico.org
50-
globalwafvalidationpolicies.applicationlayer.projectcalico.org
51-
wafplugins.applicationlayer.projectcalico.org
52-
wafpolicies.applicationlayer.projectcalico.org
53-
wafvalidationpolicies.applicationlayer.projectcalico.org
54-
```
44+
The operator installs the six WAF CRDs and the validating admission webhook, and wires the WAF reconcilers into the existing `calico-kube-controllers` pod in `calico-system`. No new workload is deployed.
5545
56-
All six CRDs must be present before you create any WAF resources.
46+
1. Confirm the six CRDs are installed:
5747
58-
:::tip
48+
```bash
49+
kubectl get crd | grep applicationlayer.projectcalico.org
50+
```
5951
60-
To confirm the admission webhook is active, run `kubectl get validatingwebhookconfigurations | grep waf`. You should see one entry. If it is absent, check the `calico-kube-controllers` pod logs in the `calico-system` namespace.
52+
```text
53+
globalwafplugins.applicationlayer.projectcalico.org
54+
globalwafpolicies.applicationlayer.projectcalico.org
55+
globalwafvalidationpolicies.applicationlayer.projectcalico.org
56+
wafplugins.applicationlayer.projectcalico.org
57+
wafpolicies.applicationlayer.projectcalico.org
58+
wafvalidationpolicies.applicationlayer.projectcalico.org
59+
```
6160
62-
:::
61+
All six must be present before you create any WAF resources.
62+
63+
1. Confirm the admission webhook is active:
64+
65+
```bash
66+
kubectl get validatingwebhookconfigurations | grep waf
67+
```
68+
69+
You should see one entry. If it's absent, check the `calico-kube-controllers` pod logs in the `calico-system` namespace.
6370
6471
## Disable Gateway WAF
6572
@@ -81,3 +88,4 @@ The operator removes the admission webhook and stops the WAF reconcilers; existi
8188
## Next steps
8289
8390
- [Tutorial](./tutorial.mdx) — deploy a test app and block your first attack.
91+
- [Set a cluster-wide baseline for Gateway WAF](./set-a-baseline.mdx) — start your production rollout.

‎calico-enterprise/threat/gateway-waf/get-started.mdx‎

Lines changed: 0 additions & 35 deletions
This file was deleted.

0 commit comments

Comments
 (0)