Merge branch 'release-3.4' into docs/update-crds-operator

nginx · Jan 2, 2024 · 0106c51 · 0106c51
2 parents 4c3a0b4 + f136a4f
commit 0106c51
Show file tree

Hide file tree

Showing 7 changed files with 371 additions and 149 deletions.
diff --git a/docs/content/includes/installation/create-custom-resources.md b/docs/content/includes/installation/create-custom-resources.md
@@ -0,0 +1,48 @@
+To make sure your NGINX Ingress Controller pods reach the `Ready` state, you'll need to create custom resource definitions (CRDs) for various components.
+
+Alternatively, you can disable this requirement by setting the `-enable-custom-resources` command-line argument to `false`.
+
+There are two ways you can install the custom resource definitions:
+
+1. Using a URL to apply a single CRD yaml file, which we recommend.
+1. Applying your local copy of the CRD yaml files, which requires you to clone the repository.
+
+{{<tabs name="install-crds">}}
+
+{{%tab name="Install CRDs from single YAML"%}}
+
+This single YAML file creates CRDs for the following resources:
+
+- [VirtualServer and VirtualServerRoute]({{< relref "configuration/virtualserver-and-virtualserverroute-resources.md" >}})
+- [TransportServer]({{< relref "configuration/transportserver-resource.md" >}})
+- [Policy]({{< relref "configuration/policy-resource.md" >}})
+- [GlobalConfiguration]({{< relref "configuration/global-configuration/globalconfiguration-resource.md" >}})
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.3.2/deploy/crds.yaml
+```
+
+{{%/tab%}}
+
+{{%tab name="Install CRDs after cloning the repo"%}}
+
+{{< note >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /note >}}
+
+These YAML files create CRDs for the following resources:
+
+- [VirtualServer and VirtualServerRoute]({{< relref "configuration/virtualserver-and-virtualserverroute-resources.md" >}})
+- [TransportServer]({{< relref "configuration/transportserver-resource.md" >}})
+- [Policy]({{< relref "configuration/policy-resource.md" >}})
+- [GlobalConfiguration]({{< relref "configuration/global-configuration/globalconfiguration-resource.md" >}})
+
+```shell
+kubectl apply -f config/crd/bases/k8s.nginx.org_virtualservers.yaml
+kubectl apply -f config/crd/bases/k8s.nginx.org_virtualserverroutes.yaml
+kubectl apply -f config/crd/bases/k8s.nginx.org_transportservers.yaml
+kubectl apply -f config/crd/bases/k8s.nginx.org_policies.yaml
+kubectl apply -f config/crd/bases/k8s.nginx.org_globalconfigurations.yaml
+```
+
+{{%/tab%}}
+
+{{</tabs>}}
diff --git a/docs/content/includes/installation/deploy-controller.md b/docs/content/includes/installation/deploy-controller.md
@@ -0,0 +1,10 @@
+---
+docs:
+---
+
+You have two options for deploying NGINX Ingress Controller:
+
+- **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas.
+- **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes.
+
+Before you start, update the [command-line arguments]({{< relref "configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements.
diff --git a/docs/content/installation/installing-nic/installation-with-operator.md b/docs/content/installation/installing-nic/installation-with-operator.md
@@ -16,10 +16,6 @@ h2 {
 }
 </style>
 
-{{< note >}}
-NGINX Ingress Operator isn't compatible with NGINX Ingress Controller 3.4.0 at this time.  We'll update this guide and remove this note when we release a compatible version.
-{{< /note >}}
-
 ## Before you start
 
 {{<note>}} We recommend the most recent stable version of NGINX Ingress Controller, available on the GitHub repository's [releases page]({{< relref "releases.md" >}}). {{</note>}}

diff --git a/docs/content/installation/integrations/app-protect-dos/installation.md b/docs/content/installation/integrations/app-protect-dos/installation.md
@@ -116,14 +116,53 @@ make push PREFIX=<my-docker-registry>/nginx-plus-ingress
 
 ---
 
-## Deploy NGINX Ingress Controller {#deploy-ingress-controller}
+## Create custom resources {#create-custom-resources}
+
+{{< include "installation/create-custom-resources.md" >}}
+
+---
+
+## Create App Protect DoS custom resources
+
+{{<tabs name="install-dos-crds">}}
+
+{{%tab name="Install CRDs from single YAML"%}}
+
+This single YAML file creates CRDs for the following resources:
+
+- `APDosPolicy`
+- `APDosLogConf`
+- `DosProtectedResource`
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.3.2/deploy/crds-nap-dos.yaml
+```
 
-You have two options for deploying NGINX Ingress Controller:
+{{%/tab%}}
 
-- **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas.
-- **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes.
+{{%tab name="Install CRDs after cloning the repo"%}}
+
+These YAML files create CRDs for the following resources:
+
+- `APDosPolicy`
+- `APDosLogConf`
+- `DosProtectedResource`
+
+```shell
+kubectl apply -f config/crd/bases/appprotectdos.f5.com_apdoslogconfs.yaml
+kubectl apply -f config/crd/bases/appprotectdos.f5.com_apdospolicy.yaml
+kubectl apply -f config/crd/bases/appprotectdos.f5.com_dosprotectedresources.yaml
+```
+
+{{%/tab%}}
+
+{{</tabs>}}
+
+---
+
+## Deploy NGINX Ingress Controller {#deploy-ingress-controller}
 
-Before you start, update the [command-line arguments]({{< relref "configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements.
+{{< include "installation/deploy-controller.md" >}}
 
 ### Using a Deployment
 

diff --git a/docs/content/installation/integrations/app-protect-waf/configuration.md b/docs/content/installation/integrations/app-protect-waf/configuration.md
@@ -1,114 +1,115 @@
 ---
 title: Configuration
-description: "Learn how to use NGINX Ingress Controller to configure NGINX App Protect WAF."
+description: "This document explains how to use F5 NGINX Ingress Controller to configure NGINX App Protect WAF."
 weight: 1900
 doctypes: [""]
 toc: true
 docs: "DOCS-578"
 aliases: ["/app-protect/configuration/"]
 ---
 
-> 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.4.0/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.4.0/examples/ingress-resources/app-protect-waf).
+{{< note >}} The NGINX Ingress Controller repository has complete NGINX App Protect WAF examples with [VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.3.2/examples/custom-resources/app-protect-waf) and [Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.3.2/examples/ingress-resources/app-protect-waf). {{< /note >}}
 
 ## Global Configuration
 
-NGINX Ingress Controller has a set of global configuration parameters that align with those available in NGINX App Protect WAF. See [ConfigMap keys]({{< relref "configuration/global-configuration/configmap-resource.md#modules" >}}) for the complete list. The NGINX App Protect WAF parameters use the `app-protect*` prefix.
+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*`.
 
 ## Enable NGINX App Protect WAF
 
-You can enable and configure NGINX App Protect WAF on the Custom Resources (VirtualServer, VirtualServerRoute) or on the Ingress-resource basis.
+NGINX App Protect WAF can be enabled and configured for custom resources (VirtualServer, VirtualServerRoute) or Ingress resources.
 
-To configure NGINX App Protect WAF on a VirtualServer resource, you would create a Policy Custom Resource referencing the `APPolicy` Custom Resource or `APPolicy` Bundle, and add this to the VirtualServer definition. See the documentation on the [NGINX App Protect WAF Policy]({{< relref "configuration/policy-resource.md#waf" >}}).
+- For custom resources, you need to create a Policy Custom Resource referencing the `APPolicy` custom resource or bundle, then add it to the VirtualServer definition. Additional detail can be found in the [Policy Resource documentation]({{< relref "configuration/policy-resource.md#waf" >}}).
+- For Ingress resources, apply the [`app-protect` annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) to each desired resource.
 
-To configure NGINX App Protect WAF on an Ingress resource, you would apply the [`app-protect` annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) to each desired resource.
 
 ## NGINX App Protect WAF Policies
 
-You can define NGINX App Protect WAF policies for your VirtualServer, VirtualServerRoute, or Ingress resources by creating an `APPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
+NGINX App Protect WAF Policies can be created for VirtualServer, VirtualServerRoute, or Ingress resources by creating an `APPolicy` [custom resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). There are some caveats:
 
- > **Note**: The fields `policy.signature-requirements[].minRevisionDatetime` and `policy.signature-requirements[].maxRevisionDatetime` are not supported.
-
- > **Note**: [The Advanced gRPC Protection for Unary Traffic](/nginx-app-protect-waf/configuration-guide/configuration/#grpc-protection-for-unary-traffic) only supports providing an `idl-file` inline. The fields `policy.idl-files[].link`, `policy.idl-files[].$ref`, and
+- The fields `policy.signature-requirements[].minRevisionDatetime` and `policy.signature-requirements[].maxRevisionDatetime` are not supported.
+- [The Advanced gRPC Protection for Unary Traffic](/nginx-app-protect-waf/configuration-guide/configuration/#grpc-protection-for-unary-traffic) only supports providing an `idl-file` inline. The fields `policy.idl-files[].link`, `policy.idl-files[].$ref`, and
  `policy.idl-files[].file` are not supported. The IDL file should be provided in field `policy.idl-files[].contents`. The value of this field can be base64 encoded. In this case the field `policy.idl-files[].isBase64` should be set to `true`.
 
- > **Note**: [External References](/nginx-app-protect-waf/configuration-guide/configuration/#external-references) in the Ingress Controller are deprecated and will not be supported in future releases.
-
-To add any [NGINX App Protect WAF policy](/nginx-app-protect-waf/declarative-policy/policy/) to an Ingress resource:
-
-1. Create an `APPolicy` Custom resource manifest.
-2. Add the desired policy to the `spec` field in the `APPolicy` resource.
-
-   > **Note**: The relationship between the Policy JSON and the resource spec is 1:1. If you're defining your resources in YAML, as we do in our examples, you'll need to represent the policy as YAML. The fields must match those in the source JSON exactly in name and level.
-
-  For example, say you want to use the [DataGuard policy](/nginx-app-protect-waf/declarative-policy/policy/#policy/data-guard) shown below:
-
-  ```json
-  {
-      "policy": {
-          "name": "dataguard_blocking",
-          "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
-          "applicationLanguage": "utf-8",
-          "enforcementMode": "blocking",
-          "blocking-settings": {
-              "violations": [
-                  {
-                      "name": "VIOL_DATA_GUARD",
-                      "alarm": true,
-                      "block": true
-                  }
-              ]
-          },
-          "data-guard": {
-              "enabled": true,
-              "maskData": true,
-              "creditCardNumbers": true,
-              "usSocialSecurityNumbers": true,
-              "enforcementMode": "ignore-urls-in-list",
-              "enforcementUrls": []
-          }
-      }
-  }
-  ```
+{{<warning>}} External references are deprecated in NGINX Ingress Controller and will not be supported in future releases. {{</warning>}}
 
-  You would create an `APPolicy` resource with the policy defined in the `spec`, as shown below:
+To add an [NGINX App Protect WAF policy](/nginx-app-protect-waf/declarative-policy/policy/) to an Ingress resource:
 
-  ```yaml
-  apiVersion: appprotect.f5.com/v1beta1
-  kind: APPolicy
-  metadata:
-    name: dataguard-blocking
-  spec:
-    policy:
-      name: dataguard_blocking
-      template:
-        name: POLICY_TEMPLATE_NGINX_BASE
-      applicationLanguage: utf-8
-      enforcementMode: blocking
-      blocking-settings:
-        violations:
-        - name: VIOL_DATA_GUARD
-          alarm: true
-          block: true
-      data-guard:
-        enabled: true
-        maskData: true
-        creditCardNumbers: true
-        usSocialSecurityNumbers: true
-        enforcementMode: ignore-urls-in-list
-        enforcementUrls: []
+1. Create an `APPolicy` custom resource manifest.
+1. Add the policy to the `spec` field in the `APPolicy` resource.
+
+A resource specification and its Policy JSON **must** match. The fields must be identical in name and nesting level. If the resources are defined with YAML, the policy must also be represented in YAML.
+
+As an example, this is a [DataGuard policy](/nginx-app-protect-waf/declarative-policy/policy/#policy/data-guard):
+
+```json
+{
+    "policy": {
+        "name": "dataguard_blocking",
+        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
+        "applicationLanguage": "utf-8",
+        "enforcementMode": "blocking",
+        "blocking-settings": {
+            "violations": [
+                {
+                    "name": "VIOL_DATA_GUARD",
+                    "alarm": true,
+                    "block": true
+                }
+            ]
+        },
+        "data-guard": {
+            "enabled": true,
+            "maskData": true,
+            "creditCardNumbers": true,
+            "usSocialSecurityNumbers": true,
+            "enforcementMode": "ignore-urls-in-list",
+            "enforcementUrls": []
+        }
+    }
+}
   ```
 
-  > Notice how the fields match exactly in name and level. NGINX Ingress Controller will transform the YAML into a valid JSON WAF policy config.
+This is what its corresponding `APPolicy` resource defined in the `spec` would look like:
+
+```yaml
+apiVersion: appprotect.f5.com/v1beta1
+kind: APPolicy
+metadata:
+  name: dataguard-blocking
+spec:
+  policy:
+    name: dataguard_blocking
+    template:
+      name: POLICY_TEMPLATE_NGINX_BASE
+    applicationLanguage: utf-8
+    enforcementMode: blocking
+    blocking-settings:
+      violations:
+      - name: VIOL_DATA_GUARD
+        alarm: true
+        block: true
+    data-guard:
+      enabled: true
+      maskData: true
+      creditCardNumbers: true
+      usSocialSecurityNumbers: true
+      enforcementMode: ignore-urls-in-list
+      enforcementUrls: []
+```
+
+Notice that the fields match in name and nesting: NGINX Ingress Controller will transform the YAML into a valid JSON WAF policy config.
 
 ## NGINX App Protect WAF Logs
 
+Configuring
+
 You can set the [NGINX App Protect WAF log configurations](/nginx-app-protect-waf/logging-overview/logs-overview/) by creating an `APLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
 
 To add the [log configurations](/nginx-app-protect-waf/logging-overview/security-log/) to a VirtualServer or an Ingress resource:
 
 1. Create an `APLogConf` Custom Resource manifest.
-2. Add the desired log configuration to the `spec` field in the `APLogConf` resource.
-3. Add the `APLogConf` reference to the [VirtualServer Policy resource]({{< relref "configuration/policy-resource.md#waf" >}}) or the [Ingress resource]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) as per the documentation.
+1. Add the log configuration to the `spec` field in the `APLogConf` resource.
+1. Add a reference to `APLogConf` in the [VirtualServer Policy resource]({{< relref "configuration/policy-resource.md#waf" >}}) or the [Ingress resource]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) as per the documentation.
 
    > **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. NGINX Ingress Controller will transform the YAML into a valid JSON WAF log config.
 
@@ -209,12 +210,15 @@ spec:
 
 ## App Protect WAF Bundles
 
-You can define App Protect WAF bundles for VirtualServers by creating policy bundles and putting them on a mounted volume accessible from NGINX Ingress Controller.
+You can 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.
 
+Before applying a policy, a WAF policy bundle must be created, then copied to a volume mounted to `/etc/nginx/waf/bundles`.
+
+{{< note >}} NGINX Ingress Controller does not currently support `securityLogs` for policy bundles. {{< /note >}}
+
+This example show how a policy is configured by referencing a generated WAF Policy Bundle:
 
-For example, you can configure a policy by referencing generated WAF Policy Bundle:
 
-> **Note**: Currently we do not support `securityLogs` for policy bundles.
 ```yaml
 apiVersion: k8s.nginx.org/v1
 kind: Policy
@@ -226,8 +230,6 @@ spec:
     apBundle: "<policy_bundle_name>.tgz"
 ```
 
-> **Note**: Before applying the policy, a WAF Policy Bundle must be created, copied to a volume, and the volume must be mounted to `/etc/nginx/waf/bundles`.
-
 ## OpenAPI Specification in NGINX Ingress Controller
 
 The OpenAPI Specification defines the spec file format needed to describe RESTful APIs. The spec file can be written either in JSON or YAML. Using a spec file simplifies the work of implementing API protection. Refer to the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) (formerly called Swagger) for details.