From 882268345c757b5d8928d60c9504b96ae3239b4e Mon Sep 17 00:00:00 2001 From: Sean O'Neill Date: Fri, 10 Dec 2021 14:50:21 +0000 Subject: [PATCH] review comments 2 - return of the docs --- deployments/helm-chart/README.md | 29 ------- docs/content/app-protect-dos/configuration.md | 84 ++++++++++--------- .../dos-protected.md | 68 +-------------- .../installation-with-helm-dos-arbitrator.md | 0 ...advanced-configuration-with-annotations.md | 2 +- 5 files changed, 46 insertions(+), 137 deletions(-) rename docs/content/{configuration => app-protect-dos}/dos-protected.md (61%) rename docs/content/{installation => app-protect-dos}/installation-with-helm-dos-arbitrator.md (100%) diff --git a/deployments/helm-chart/README.md b/deployments/helm-chart/README.md index 1501ed326e..9040eac549 100644 --- a/deployments/helm-chart/README.md +++ b/deployments/helm-chart/README.md @@ -61,10 +61,6 @@ For NGINX Plus: (assuming you have pushed the Ingress controller image `nginx-pl ```console $ helm install my-release nginx-stable/nginx-ingress --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true ``` -For App Protect Dos: (assuming you have pushed the Ingress controller image `nginx-plus-ingress` to your private registry `myregistry.example.com` -```console -$ helm install --create-namespace -n nginx-ingress my-release nginx-stable/nginx-ingress --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true --set controller.appprotectdos.enable=true -``` **Note**: If you wish to use the experimental repository, replace `stable` with `edge` and add the `--devel` flag. @@ -82,14 +78,6 @@ For NGINX Plus: $ helm install my-release -f values-plus.yaml . ``` -For App Protect Dos: - -replace the value in the `appprotectdos.enable` field inside the values.yaml file with `true` - -```console -$ helm install --create-namespace -n nginx-ingress my-release -f values-plus.yaml . -``` - **Note**: If you wish to use the experimental repository, replace the value in the `tag` field inside the yaml files with `edge`. The command deploys the Ingress controller in your Kubernetes cluster in the default configuration. The configuration section lists the parameters that can be configured during installation. @@ -119,22 +107,12 @@ To upgrade the release `my-release`: $ helm upgrade my-release . ``` -For App Protect Dos: -```console -$ helm upgrade -n nginx-ingress my-release . -``` - #### Upgrade via Helm Repository: ```console $ helm upgrade my-release nginx-stable/nginx-ingress ``` -For App Protect Dos: -```console -$ helm upgrade -n nginx-ingress my-release nginx-stable/nginx-ingress -``` - ## Uninstalling the Chart ### Uninstalling the Release @@ -144,13 +122,6 @@ To uninstall/delete the release `my-release`: ```console $ helm uninstall my-release ``` - -For App Protect Dos: -```console -$ helm uninstall -n nginx-ingress my-release -$ kubectl delete ns nginx-ingress -``` - The command removes all the Kubernetes components associated with the release and deletes the release. ### Uninstalling the CRDs diff --git a/docs/content/app-protect-dos/configuration.md b/docs/content/app-protect-dos/configuration.md index 2e9c77ecd2..e424d13f64 100644 --- a/docs/content/app-protect-dos/configuration.md +++ b/docs/content/app-protect-dos/configuration.md @@ -10,34 +10,27 @@ toc: true This document describes how to configure the NGINX App Protect Dos module > Check out the complete [NGINX Ingress Controller with App Protect Dos example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/appprotect-dos). -## Global Configuration - -The NGINX Ingress Controller has a set of global configuration parameters that align with those available in the NGINX App Protect Dos module. See [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#modules) for the complete list. The App Protect parameters use the `app-protect-dos*` prefix. - -## Enable App Protect Dos for Ingress - -You can enable and configure NGINX App Protect Dos on a per-Ingress-resource basis. To do so, you can apply the [App Protect Dos annotation](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#app-protect-dos) to each desired resource. +## App Protect Dos Configuration -## App Protect Dos Protected Resources - -An `DosProtectedResource` is a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) that holds the configuration of a collection of protected resources. -An Ingress or VirtualServer can be protected by adding a reference to the Dos Protected Resource. - -To enable DOS protection to an Ingress: +A `DosProtectedResource` is a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) that holds the configuration of a collection of protected resources. +An [Ingress](/nginx-ingress-controller/configuration/ingress-resources/basic-configuration), [VirtualServer and VirtualServerRoute](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) can be protected by specifying a reference to the DosProtectedResource. 1. Create an `DosProtectedResource` Custom resource manifest. As an example: ```yaml - apiVersion: appprotectdos.f5.com/v1beta1 - kind: DosProtectedResource - metadata: - name: dos-protected - spec: - enable: true - name: "my-dos" - apDosMonitor: - uri: "webapp.example.com" +apiVersion: appprotectdos.f5.com/v1beta1 +kind: DosProtectedResource +metadata: + name: dos-protected +spec: + enable: true + name: "webapp.example.com" + apDosMonitor: + uri: "webapp.example.com" + protocol: "http1" + timeout: 5 + dosAccessLogDest: "127.0.0.1:5561" ``` -2. Add an annotation to an Ingress that refers to that resource by `namespace/name`: +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: ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress @@ -46,10 +39,28 @@ To enable DOS protection to an Ingress: annotations: appprotectdos.f5.com/app-protect-dos-resource: "default/dos-protected" ``` -## Dos Policy configuration +3. Enable App Protect Dos on a VirtualServer by setting the `dos` field value to the qualified identifier(`namespace/name`) of a DosProtectedResource: + ```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: webapp +spec: + host: webapp.example.com + upstreams: + - name: webapp + service: webapp-svc + port: 80 + routes: + - path: / + dos: dos-protected + action: + pass: webapp + ``` -You can set the App Protect Dos Policy configurations by creating an `APDosPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and referencing that in the `DosProtectedResource`. +## Dos Policy Configuration +You can configure the policy for Dos by creating an `APDosPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and specifying the qualified identifier(`namespace/name`) of the `ApDosPolicy` in the `DosProtectedResource`. For example, say you want to use Dos Policy as shown below: @@ -92,21 +103,9 @@ Then add a reference in the `DosProtectedResrouce` to the `ApDosPolicy`: apDosPolicy: "default/dospolicy" ``` -> Notice how the fields match exactly in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect Dos policy config. - -> **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. - - ## App Protect Dos Logs -You can set the [App Protect Dos Log configurations](/nginx-app-protect-dos/logs-overview/types-of-logs/) by creating an `APDosLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). - -To add the App Protect Dos log configurations to an Ingress resource: - -1. Create an `APDosLogConf` Custom resource manifest. -2. Add the desired log configuration to the `spec` field in the `APDosLogConf` resource. - - > **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect Dos log config. +You can set the [App Protect Dos Log configuration](/nginx-app-protect-dos/logs-overview/types-of-logs/) by creating an `APDosLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and specifying the qualified identifier(`namespace/name`) of the `ApDosLogConf` in the `DosProtectedResource`. For example, say you want to log state changing requests for your Ingress resources using App Protect Dos. The App Protect Dos log configuration looks like this: @@ -123,7 +122,7 @@ For example, say you want to log state changing requests for your Ingress resour } ``` -You would add define that config in the `spec` of your `APDosLogConf` resource as follows: +You would add that config in the `spec` of your `APDosLogConf` resource as follows: ```yaml apiVersion: appprotectdos.f5.com/v1beta1 @@ -140,7 +139,7 @@ spec: attack-signatures: top 10 ``` -Then add a reference in the `DosProtectedResrouce` to the `APDosLogConf`: +Then add a reference in the `DosProtectedResource` to the `APDosLogConf`: ```yaml apiVersion: appprotectdos.f5.com/v1beta1 kind: DosProtectedResource @@ -155,4 +154,7 @@ Then add a reference in the `DosProtectedResrouce` to the `APDosLogConf`: enable: true apDosLogConf: "doslogconf" dosLogDest: "syslog-svc.default.svc.cluster.local:514" - ``` \ No newline at end of file + ``` +## Global Configuration + +The NGINX Ingress Controller has a set of global configuration parameters that align with those available in the NGINX App Protect Dos module. See [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#modules) for the complete list. The App Protect parameters use the `app-protect-dos*` prefix. diff --git a/docs/content/configuration/dos-protected.md b/docs/content/app-protect-dos/dos-protected.md similarity index 61% rename from docs/content/configuration/dos-protected.md rename to docs/content/app-protect-dos/dos-protected.md index 6ca63ceab1..eeb17a7b45 100644 --- a/docs/content/configuration/dos-protected.md +++ b/docs/content/app-protect-dos/dos-protected.md @@ -7,11 +7,6 @@ doctypes: [""] toc: true --- - -The DosProtectedResource allows you to specify App Protect Dos configuration as a Kubernetes resource that can then be referenced by your [Ingress](/nginx-ingress-controller/configuration/ingress-resources/basic-configuration) and [VirtualServer and VirtualServerRoute](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) resources. - -The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). - > **Feature Status**: DOS is available as a preview feature: it is suitable for experimenting and testing; however, it must be used with caution in production environments. Additionally, while the feature is in preview status, we might introduce some backward-incompatible changes to the resource specification in the next releases. The feature is disabled by default. To enable it, set the [enable-preview-policies](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-enable-preview-policies) command-line argument of the Ingress Controller. > Note: This feature is only available in NGINX Plus with AppProtectDos. @@ -21,7 +16,7 @@ The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/co ## Dos Protected Resource Specification -Below is an example of a dos protected resource. It defines it's own configuration and references to policy configuration and to log configuration: +Below is an example of a dos protected resource. ```yaml apiVersion: appprotectdos.f5.com/v1beta1 kind: DosProtectedResource @@ -32,11 +27,6 @@ spec: name: "my-dos" apDosMonitor: uri: "webapp.example.com" - apDosPolicy: "dospolicy" - dosSecurityLog: - enable: true - apDosLogConf: "doslogconf" - dosLogDest: "syslog-svc.default.svc.cluster.local:514" ``` @@ -56,66 +46,12 @@ spec: ### DosProtectedResource.apDosPolicy -The `apDosPolicy` is a reference to the policy configuration defined as an `ApDosPolicy`. +The `apDosPolicy` is a reference (qualified identifier in the format `namespace/name`) to the policy configuration defined as an `ApDosPolicy`. ### DosProtectedResource.apDosMonitor 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). -### Applying Policies - -You can apply policies to both VirtualServer and VirtualServerRoute resources. For example: - * VirtualServer: - ```yaml - apiVersion: k8s.nginx.org/v1 - kind: VirtualServer - metadata: - name: cafe - namespace: cafe - spec: - host: cafe.example.com - dos: "default/dos-protected" # virtual server dos configuration - upstreams: - - name: coffee - service: coffee-svc - port: 80 - routes: - - path: /tea - dos: "other/other-dos-protected" # route dos configuration - route: tea/tea - - path: /coffee - action: - pass: coffee - ``` - - For VirtualServer, you can apply a policy: - - to all routes (spec dos) - - to a specific route (route dos) - - Route dos configuration override spec dos configuration. - - * VirtualServerRoute, which is referenced by the VirtualServer above: - ```yaml - apiVersion: k8s.nginx.org/v1 - kind: VirtualServerRoute - metadata: - name: tea - namespace: tea - spec: - host: cafe.example.com - upstreams: - - name: tea - service: tea-svc - port: 80 - subroutes: - - path: /tea - dos: "default/dos-protected" - action: - pass: tea - ``` - - For VirtualServerRoute, you can apply dos configuration to a subroute (subroute policies). - ### Invalid Dos Protected Resources NGINX will treat a dos protected resource as invalid if one of the following conditions is met: diff --git a/docs/content/installation/installation-with-helm-dos-arbitrator.md b/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md similarity index 100% rename from docs/content/installation/installation-with-helm-dos-arbitrator.md rename to docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md diff --git a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md index 1f920116c8..4208bcabae 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -213,5 +213,5 @@ The table below summarizes the available annotations. {{% table %}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``appprotectdos.f5.com/app-protect-dos-resource`` | N/A | Enable App Protect Dos for the Ingress Resource by specifying a DosProtectedResource. | N/A | [Example for App Protect Dos](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/appprotect-dos). | +|``appprotectdos.f5.com/app-protect-dos-resource`` | N/A | Enable App Protect Dos for the Ingress Resource by specifying a [DosProtectedResource](/nginx-ingress-controller/app-protect-dos/dos-protected/). | N/A | [Example for App Protect Dos](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/appprotect-dos). | {% /table %}}