From 6ee6addee774206174594b967ef93579d3030ad1 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 23 May 2024 15:18:09 +0100 Subject: [PATCH] NAP link fixes & improvements to troubleshooting documentation (#5605) This commit updates broken NAP links to include the v4 path and changes the location of the troubleshooting documents so that they are colocated with the other NAP documentation. As part of this effort a number of improvements were made to the WAF, DoS and troubleshooting documents related to newer documentation standards. These changes include the use of title case and excision of gerunds. --- .../app-protect-dos/configuration.md | 8 +- .../app-protect-dos/dos-protected.md | 64 ++++++++------- .../app-protect-dos/installation.md | 7 +- .../troubleshooting-app-protect-dos.md | 18 ++--- .../app-protect-waf/configuration.md | 78 ++++++++++--------- .../app-protect-waf/installation.md | 15 ++-- .../troubleshooting-app-protect-waf.md | 42 +++++----- .../troubleshooting/troubleshoot-common.md | 57 +++++++------- .../troubleshoot-configmap-policy.md | 12 ++- .../troubleshooting/troubleshoot-ingress.md | 13 +++- .../troubleshoot-virtualserver.md | 18 +++-- 11 files changed, 183 insertions(+), 149 deletions(-) rename docs/content/{troubleshooting => installation/integrations/app-protect-dos}/troubleshooting-app-protect-dos.md (89%) rename docs/content/{troubleshooting => installation/integrations/app-protect-waf}/troubleshooting-app-protect-waf.md (80%) diff --git a/docs/content/installation/integrations/app-protect-dos/configuration.md b/docs/content/installation/integrations/app-protect-dos/configuration.md index f6ed20380d..ffb02740a5 100644 --- a/docs/content/installation/integrations/app-protect-dos/configuration.md +++ b/docs/content/installation/integrations/app-protect-dos/configuration.md @@ -31,7 +31,7 @@ spec: timeout: 5 ``` -2. Enable App Protect DoS on an Ingress by adding an annotation on the Ingress. Set the value of the annotation to the qualified identifier(`namespace/name`) of a DosProtectedResource: +2. Enable App Protect DoS for an Ingress resource by adding an annotation to the Ingress. Set the value of the annotation to the qualified identifier(`namespace/name`) of a DosProtectedResource: ```yaml apiVersion: networking.k8s.io/v1 @@ -42,7 +42,7 @@ spec: appprotectdos.f5.com/app-protect-dos-resource: "default/dos-protected" ``` -3. Enable App Protect DoS on a VirtualServer by setting the `dos` field value to the qualified identifier(`namespace/name`) of a DosProtectedResource: +3. Enable App Protect DoS on a VirtualServer resource by setting the `dos` field value to the qualified identifier(`namespace/name`) of a DosProtectedResource: ```yaml apiVersion: k8s.nginx.org/v1 @@ -75,10 +75,10 @@ For example, say you want to use DoS Policy as shown below: bad_actors: "on", automation_tools_detection: "on", tls_fingerprint: "on", -} + } ``` -You would create an `APDosPolicy` resource with the policy defined in the `spec`, as shown below: +Create an `APDosPolicy` resource with the policy defined in the `spec`, as shown below: ```yaml apiVersion: appprotectdos.f5.com/v1beta1 diff --git a/docs/content/installation/integrations/app-protect-dos/dos-protected.md b/docs/content/installation/integrations/app-protect-dos/dos-protected.md index d5cb4edcb8..974b71a7c4 100644 --- a/docs/content/installation/integrations/app-protect-dos/dos-protected.md +++ b/docs/content/installation/integrations/app-protect-dos/dos-protected.md @@ -1,20 +1,22 @@ --- -title: DoS Protected Resource - -description: "Dos Protected Resource Specification" +docs: DOCS-581 +doctypes: +- '' +title: DoS protected resource specification +toc: true weight: 300 doctypes: [""] toc: true docs: "DOCS-581" --- -> Note: This feature is only available in NGINX Plus with AppProtectDos. +NGINX App Protect DoS protected resource specification -> Note: The feature is implemented using the NGINX Plus [NGINX App Protect Dos Module](/nginx-app-protect-dos/deployment-guide/learn-about-deployment/). +{{< note >}} This feature is only available using the NGINX Plus [NGINX App Protect DoS Module](/nginx-app-protect-dos/deployment-guide/learn-about-deployment/). {{< /note >}} -## DoS Protected Resource Specification +## DoS Protected resource specification -Below is an example of a dos protected resource. +Below is an example of a DoS protected resource. ```yaml apiVersion: appprotectdos.f5.com/v1beta1 @@ -52,51 +54,56 @@ The `apDosPolicy` is a reference (qualified identifier in the format `namespace/ This is how NGINX App Protect DoS monitors the stress level of the protected object. The monitor requests are sent from localhost (127.0.0.1). -### Invalid DoS Protected Resources +### Invalid DoS Protected resources -NGINX will treat a dos protected resource as invalid if one of the following conditions is met: +NGINX will treat a DoS protected resource as invalid if one of the following conditions is met: -- The dos protected resource doesn't pass the [comprehensive validation](#comprehensive-validation). -- The dos protected resource isn't present in the cluster. +- The DoS protected resource doesn't pass the [comprehensive validation](#comprehensive-validation). +- The DoS protected resource isn't present in the cluster. ### Validation -Two types of validation are available for the dos protected resource: +Two types of validation are available for the DoS protected resource: - *Structural validation*, done by `kubectl` and the Kubernetes API server. -- *Comprehensive validation*, done by the Ingress Controller. +- *Comprehensive validation*, done by NGINX Ingress Controller. -#### Structural Validation +#### Structural validation -The custom resource definition for the dos protected resource includes a structural OpenAPI schema, which describes the type of every field of the resource. +The custom resource definition for the DoS protected resource includes a structural OpenAPI schema, which describes the type of every field of the resource. If you try to create (or update) a resource that violates the structural schema -- for example, the resource uses a string value instead of a bool in the `enable` field -- `kubectl` and the Kubernetes API server will reject the resource. - Example of `kubectl` validation: + ```shell + kubectl apply -f apdos-protected.yaml ``` - $ kubectl apply -f apdos-protected.yaml + ```shell error: error validating "examples/app-protect-dos/apdos-protected.yaml": error validating data: ValidationError(DosProtectedResource.spec.enable): invalid type for com.f5.appprotectdos.v1beta1.DosProtectedResource.spec.enable: got "string", expected "boolean"; if you choose to ignore these errors, turn validation off with --validate=false ``` - Example of Kubernetes API server validation: + ```shell + kubectl apply -f access-control-policy-allow.yaml --validate=false ``` - $ kubectl apply -f access-control-policy-allow.yaml --validate=false + ```shell The DosProtectedResource "dos-protected" is invalid: spec.enable: Invalid value: "string": spec.enable in body must be of type boolean: "string" ``` -If a resource passes structural validation, then the Ingress Controller's comprehensive validation runs. +If a resource passes structural validation, then NGINX Ingress Controller will start comprehensive validation. -#### Comprehensive Validation +#### Comprehensive validation -The Ingress Controller validates the fields of a dos protected resource. If a resource is invalid, the Ingress Controller will reject it. The resource will continue to exist in the cluster, but the Ingress Controller will ignore it. +NGINX Ingress Controller validates the fields of a DoS protected resource. If a resource is invalid, NGINX Ingress Controller will reject it. The resource will continue to exist in the cluster, but NGINX Ingress Controller will ignore it. -You can use `kubectl` to check if the Ingress Controller successfully applied a dos protected resource configuration. For our example `dos-protected` dos protected resource, we can run: +You can use `kubectl` to check if NGINX Ingress Controller successfully applied a DoS protected resource configuration. For our example `dos-protected` DoS protected resource, we can run: +```shell +kubectl describe dosprotectedresource dos-protected ``` -$ kubectl describe dosprotectedresource dos-protected -. . . +```shell Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -105,17 +112,18 @@ Events: Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. -If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you create a dos protected resource `dos-protected` with an invalid URI `bad` in the `dosSecurityLog/dosLogDest` field, you will get: +If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a dos protected resource `dos-protected` with an invalid URI `bad` in the `dosSecurityLog/dosLogDest` field, you will get: +```shell +kubectl describe policy webapp-policy ``` -$ kubectl describe policy webapp-policy -. . . +```shell Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning Rejected 2s nginx-ingress-controller error validating DosProtectedResource: dos-protected invalid field: dosSecurityLog/dosLogDest err: invalid log destination: bad, must follow format: : or stderr ``` -Note how the events section includes a Warning event with the Rejected reason. +The events section has Warning event with the rejection error in the message. -**Note**: If you make an existing resource invalid, the Ingress Controller will reject it. +{{< warning >}} If you invalidate an existing resource, NGINX Ingress Controller will reject it. {{< /warning >}} diff --git a/docs/content/installation/integrations/app-protect-dos/installation.md b/docs/content/installation/integrations/app-protect-dos/installation.md index 95cee4262b..7fcf91daa8 100644 --- a/docs/content/installation/integrations/app-protect-dos/installation.md +++ b/docs/content/installation/integrations/app-protect-dos/installation.md @@ -1,6 +1,9 @@ --- -title: Building NGINX Ingress Controller with NGINX App Protect DoS -description: "This document explains how to build an image for NGINX Ingress Controller with the NGINX App Protect DoS from source code." +docs: DOCS-583 +doctypes: +- '' +title: Build NGINX Ingress Controller with NGINX App Protect DoS +toc: true weight: 100 doctypes: [""] toc: true diff --git a/docs/content/troubleshooting/troubleshooting-app-protect-dos.md b/docs/content/installation/integrations/app-protect-dos/troubleshooting-app-protect-dos.md similarity index 89% rename from docs/content/troubleshooting/troubleshooting-app-protect-dos.md rename to docs/content/installation/integrations/app-protect-dos/troubleshooting-app-protect-dos.md index 51afa5eca6..2d5f74e07a 100644 --- a/docs/content/troubleshooting/troubleshooting-app-protect-dos.md +++ b/docs/content/installation/integrations/app-protect-dos/troubleshooting-app-protect-dos.md @@ -1,19 +1,19 @@ --- -title: "Troubleshooting with NGINX App Protect DoS" -description: "This document describes how to troubleshoot problems when using NGINX Ingress Controller and the App Protect DoS module." -weight: 600 -doctypes: [""] +docs: DOCS-1456 +doctypes: +- '' +title: Troubleshooting NGINX App Protect DoS toc: true -docs: "DOCS-1456" -aliases: - - /content/troubleshooting/troubleshooting-with-app-protect-dos +weight: 400 --- +This document describes how to troubleshoot problems when using NGINX Ingress Controller and the App Protect DoS module. + To troubleshoot other parts of NGINX Ingress Controller, check the [troubleshooting]({{< relref "troubleshooting/troubleshoot-common" >}}) section of the documentation. ## Potential Problems -The table below categorizes some potential problems with NGINX Ingress Controller when the App Protect DoS module is enabled. It suggests how to troubleshoot those problems, using one or more methods from the next section. +The table below outlines potential problems with NGINX Ingress Controller when the App Protect DoS module is enabled. It suggests how to troubleshoot those problems with methods explained in the next section. {{% table %}} |Problem area | Symptom | Troubleshooting method | Common cause | @@ -22,7 +22,7 @@ The table below categorizes some potential problems with NGINX Ingress Controlle |DosProtectedResource, APDosLogConf, APDosPolicy or Ingress Resource. | The configuration is not applied. | Check the events of the DosProtectedResource, APDosLogConf, APDosPolicy and Ingress Resource, check the Ingress Controller logs. | DosProtectedResource, APDosLogConf or APDosPolicy is invalid. | {{% /table %}} -## Troubleshooting Methods +## Troubleshooting ethods ### Checking NGINX Ingress Controller and App Protect DoS logs diff --git a/docs/content/installation/integrations/app-protect-waf/configuration.md b/docs/content/installation/integrations/app-protect-waf/configuration.md index 5d40d5ae28..04f9b56325 100644 --- a/docs/content/installation/integrations/app-protect-waf/configuration.md +++ b/docs/content/installation/integrations/app-protect-waf/configuration.md @@ -1,14 +1,12 @@ --- title: Configuration -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/"] +weight: 200 --- -> 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.5.1/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.1/examples/ingress-resources/app-protect-waf). +This document explains how to use F5 NGINX Ingress Controller to configure NGINX App Protect WAF. + +{{< 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.5.1/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.1/examples/ingress-resources/app-protect-waf).{{< /note >}} ## Global Configuration @@ -27,19 +25,19 @@ NGINX App Protect WAF can be enabled and configured for custom resources (Virtua 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: - 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 +- [The Advanced gRPC Protection for Unary Traffic](/nginx-app-protect-waf/v4/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`. {{}} External references are deprecated in NGINX Ingress Controller and will not be supported in future releases. {{}} -To add an [NGINX App Protect WAF policy](/nginx-app-protect-waf/declarative-policy/policy/) to an Ingress resource: +To add an [NGINX App Protect WAF policy](/nginx-app-protect-waf/v4/declarative-policy/policy/) to an Ingress resource: 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): +As an example, this is a [DataGuard policy](/nginx-app-protect-waf/v4/declarative-policy/policy/#policy/data-guard): ```json { @@ -103,9 +101,9 @@ Notice that the fields match in name and nesting: NGINX Ingress Controller will 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/). +You can set the [NGINX App Protect WAF log configurations](/nginx-app-protect-waf/v4/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: +To add the [log configurations](/nginx-app-protect-waf/v4/logging-overview/security-log/) to a VirtualServer or an Ingress resource: 1. Create an `APLogConf` Custom Resource manifest. 1. Add the log configuration to the `spec` field in the `APLogConf` resource. @@ -113,7 +111,7 @@ To add the [log configurations](/nginx-app-protect-waf/logging-overview/security > **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. -For example, say you want to [log state changing requests](/nginx-app-protect-waf/logging-overview/security-log/#security-log-configuration-file) for your VirtualServer or Ingress resources using NGINX App Protect WAF. The log configuration looks like this: +For example, say you want to [log state changing requests](/nginx-app-protect-waf/v4/logging-overview/security-log/#security-log-configuration-file) for your VirtualServer or Ingress resources using NGINX App Protect WAF. The log configuration looks like this: ```json { @@ -144,13 +142,13 @@ spec: ## NGINX App Protect WAF User Defined Signatures -You can define NGINX App Protect WAF [User-Defined Signatures](/nginx-app-protect-waf/configuration-guide/configuration/#user-defined-signatures) for your VirtualServer or Ingress resources by creating an `APUserSig` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +You can define NGINX App Protect WAF [User-Defined Signatures](/nginx-app-protect-waf/v4/configuration-guide/configuration/#user-defined-signatures) for your VirtualServer or Ingress resources by creating an `APUserSig` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). > **Note**: The field `revisionDatetime` is not currently supported. -> **Note**: `APUserSig` resources increase the reload time of NGINX Plus compared with `APPolicy` and `APLogConf` resources. Refer to [NGINX Fails to Start or Reload]({{< relref "troubleshooting/troubleshooting-app-protect-waf.md#nginx-fails-to-start-or-reload" >}}) for more information. +> **Note**: `APUserSig` resources increase the reload time of NGINX Plus compared with `APPolicy` and `APLogConf` resources. Refer to [NGINX Fails to Start or Reload]({{< relref "installation/integrations/app-protect-waf/troubleshooting-app-protect-waf.md#nginx-fails-to-start-or-reload" >}}) for more information. -To add the [User Defined Signatures](https://docs.nginx.com/nginx-app-protect-waf/configuration-guide/configuration/#user-defined-signatures) to a VirtualServer or Ingress resource: +To add the [User Defined Signatures](/nginx-app-protect-waf/v4/configuration-guide/configuration/#user-defined-signatures) to a VirtualServer or Ingress resource: 1. Create an `APUserSig` Custom resource manifest. 2. Add the desired User defined signature to the `spec` field in the `APUserSig` resource. @@ -265,7 +263,7 @@ It contains violations related to OpenAPI set to blocking (enforced). ### Types of OpenAPI References -There are different ways of referencing OpenAPI Specification files. The configuration is similar to [External References](/nginx-app-protect-waf/configuration-guide/configuration/#external-references). +There are different ways of referencing OpenAPI Specification files. The configuration is similar to [External References](/nginx-app-protect-waf/v4/configuration-guide/configuration/#external-references). **Note**: Any update of an OpenAPI Specification file referenced in the policy will not trigger a policy compilation. This action needs to be done actively by reloading the NGINX configuration. @@ -273,7 +271,7 @@ There are different ways of referencing OpenAPI Specification files. The configu URL reference is the method of referencing an external source by providing its full URL. -Make sure to configure certificates prior to using the HTTPS protocol - see the [External References](/nginx-app-protect-waf/configuration-guide/configuration/#types-of-references) for details. +Make sure to configure certificates prior to using the HTTPS protocol - see the [External References](/nginx-app-protect-waf/v4/configuration-guide/configuration/#types-of-references) for details. ## Configuration in NGINX Ingress Controller @@ -287,7 +285,7 @@ These are the typical steps to deploy an OpenAPI protection Policy in NGINX Ingr 6. Create a `Policy` object which references the `APPolicy` Custom Resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/v3.5.1/examples/custom-resources/app-protect-waf/waf.yaml). 7. Finally, attach the `Policy` object to a `VirtualServer` resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/v3.5.1/examples/custom-resources/app-protect-waf/virtual-server.yaml). -**Note**: You need to make sure that the server where the resource files are located is always available when you are compiling your policy. +{{< note >}} You need to make sure that the server where the resource files are located is available while you are compiling your policy. {{< /note >}} ### Example Configuration @@ -420,11 +418,11 @@ The `link` option is also available in the `openApiFileReference` property and i In this example we deploy NGINX Ingress Controller with NGINX Plus and NGINX App Protect WAF, deploy a simple web application, and then configure load balancing and WAF protection for that application using the VirtualServer resource. -**Note:** You can find the example, and the files referenced, on [GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.1/examples/custom-resources/app-protect-waf). +{{< note >}} You can find the example, and the files referenced, on [GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.1/examples/custom-resources/app-protect-waf).{{< /note >}} ## Prerequisites -1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy NGINX Ingress Controller with NGINX Plus and NGINX App Protect WAF. +1. Follow the installation [instructions]({{< relref "installation/integrations/app-protect-waf/installation.md" >}}) to deploy NGINX Ingress Controller with NGINX Plus and NGINX App Protect WAF. 2. Save the public IP address of NGINX Ingress Controller into a shell variable: ```console @@ -487,33 +485,39 @@ To access the application, curl the coffee and the tea services. We'll use the - 1. Send a request to the application: - ```console - $ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT/ - Server address: 10.12.0.18:80 - Server name: webapp-7586895968-r26zn - ``` + ```shell + curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT/ + ``` + ```shell + Server address: 10.12.0.18:80 + Server name: webapp-7586895968-r26zn + ``` 2. Now, let's try to send a request with a suspicious URL: - ```console - $ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP "http://webapp.example.com:$IC_HTTP_PORT/