diff --git a/cmd/nginx-ingress/main.go b/cmd/nginx-ingress/main.go index 1eb4b8c1bd..db38de9bd5 100644 --- a/cmd/nginx-ingress/main.go +++ b/cmd/nginx-ingress/main.go @@ -59,6 +59,7 @@ func main() { fmt.Printf("NGINX Ingress Controller Version=%v Commit=%v Date=%v DirtyState=%v Arch=%v/%v Go=%v\n", version, commitHash, commitTime, dirtyBuild, runtime.GOOS, runtime.GOARCH, runtime.Version()) parseFlags() + parsedFlags := os.Args[1:] config, kubeClient := createConfigAndKubeClient() @@ -217,6 +218,7 @@ func main() { TelemetryReportingEndpoint: telemetryEndpoint, NICVersion: version, DynamicWeightChangesReload: *enableDynamicWeightChangesReload, + InstallationFlags: parsedFlags, } lbc := k8s.NewLoadBalancerController(lbcInput) diff --git a/docs/content/configuration/global-configuration/globalconfiguration-resource.md b/docs/content/configuration/global-configuration/globalconfiguration-resource.md index 51d9f8f48f..33830af896 100644 --- a/docs/content/configuration/global-configuration/globalconfiguration-resource.md +++ b/docs/content/configuration/global-configuration/globalconfiguration-resource.md @@ -77,15 +77,15 @@ You can use the usual `kubectl` commands to work with a GlobalConfiguration reso For example, the following command creates a GlobalConfiguration resource defined in `global-configuration.yaml` with the name `nginx-configuration`: -``` -$ kubectl apply -f global-configuration.yaml +```shell +kubectl apply -f global-configuration.yaml globalconfiguration.k8s.nginx.org/nginx-configuration created ``` Assuming the namespace of the resource is `nginx-ingress`, you can get the resource by running: -``` -$ kubectl get globalconfiguration nginx-configuration -n nginx-ingress +```shell +kubectl get globalconfiguration nginx-configuration -n nginx-ingress NAME AGE nginx-configuration 13s ``` @@ -128,8 +128,8 @@ The Ingress Controller validates the fields of a GlobalConfiguration resource. I You can check if the Ingress Controller successfully applied the configuration for a GlobalConfiguration. For our `nginx-configuration` GlobalConfiguration, we can run: -``` -$ kubectl describe gc nginx-configuration -n nginx-ingress +```shell +kubectl describe gc nginx-configuration -n nginx-ingress . . . Events: Type Reason Age From Message @@ -141,8 +141,8 @@ Note how the events section includes a Normal event with the Updated reason that If you create a GlobalConfiguration `nginx-configuration` with two or more listeners that have the same protocol UDP and port 53, you will get: -``` -$ kubectl describe gc nginx-configuration -n nginx-ingress +```shell +kubectl describe gc nginx-configuration -n nginx-ingress . . . Events: Type Reason Age From Message diff --git a/docs/content/configuration/global-configuration/reporting-resources-status.md b/docs/content/configuration/global-configuration/reporting-resources-status.md index dad4f17fe6..4c75281d60 100644 --- a/docs/content/configuration/global-configuration/reporting-resources-status.md +++ b/docs/content/configuration/global-configuration/reporting-resources-status.md @@ -34,16 +34,16 @@ Notes: NGINX Ingress Controller does not clear the status of Ingress resources w A VirtualServer or VirtualServerRoute resource includes the status field with information about the state of the resource and the IP address, through which the hosts of that resource are publicly accessible. You can see the status in the output of the `kubectl get virtualservers` or `kubectl get virtualserverroutes` commands as shown below: -``` -$ kubectl get virtualservers +```shell +kubectl get virtualservers NAME STATE HOST IP PORTS AGE cafe Valid cafe.example.com 12.13.23.123 [80,443] 34s ``` To see an external hostname address associated with a VirtualServer resource, use the `-o wide` option: -``` -$ kubectl get virtualservers -o wide +```shell +kubectl get virtualservers -o wide NAME STATE HOST IP EXTERNALHOSTNAME PORTS AGE cafe Valid cafe.example.com ae430f41a1a0042908655abcdefghijkl-12345678.eu-west-2.elb.amazonaws.com [80,443] 106s ``` @@ -52,8 +52,8 @@ $ kubectl get virtualservers -o wide In order to see additional addresses or extra information about the `Status` of the resource, use the following command: -``` -$ kubectl describe virtualserver +```shell +kubectl describe virtualserver . . . Status: External Endpoints: @@ -110,16 +110,16 @@ Notes: The Ingress Controller does not clear the status of VirtualServer and Vir A Policy resource includes the status field with information about the state of the resource. You can see the status in the output of the `kubectl get policy` command as shown below: -``` -$ kubectl get policy +```shell +kubectl get policy NAME STATE AGE webapp-policy Valid 30s ``` In order to see additional addresses or extra information about the `Status` of the resource, use the following command: -``` -$ kubectl describe policy +```shell +kubectl describe policy . . . Status: Message: Configuration for default/webapp-policy was added or updated @@ -144,16 +144,16 @@ The following fields are reported in Policy status: A TransportServer resource includes the status field with information about the state of the resource. You can see the status in the output of the `kubectl get transportserver` command as shown below: -``` -$ kubectl get transportserver +```shell +kubectl get transportserver NAME STATE REASON AGE dns-tcp Valid AddedOrUpdated 47m ``` In order to see additional addresses or extra information about the `Status` of the resource, use the following command: -``` -$ kubectl describe transportserver +```shell +kubectl describe transportserver . . . Status: Message: Configuration for default/dns-tcp was added or updated diff --git a/docs/content/configuration/handling-host-and-listener-collisions.md b/docs/content/configuration/handling-host-and-listener-collisions.md index 90963365d6..45ef42afd8 100644 --- a/docs/content/configuration/handling-host-and-listener-collisions.md +++ b/docs/content/configuration/handling-host-and-listener-collisions.md @@ -56,7 +56,7 @@ If a user creates both resources in the cluster, a host collision will occur. As In our example, if `cafe-virtual-server` was created first, it will win the host `cafe.example.com` and the Ingress Controller will reject `cafe-ingress`. This will be reflected in the events and in the resource's status field: -```console +```shell kubectl describe vs cafe-virtual-server . . . @@ -130,7 +130,7 @@ If a user creates both resources in the cluster, a listener collision will occur In our example, if `tcp-1` was created first, it will win the listener `dns-tcp` and the Ingress Controller will reject `tcp-2`. This will be reflected in the events and in the resource's status field: -```console +```shell kubectl describe ts tcp-2 . . . 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 342e5342bf..bd28023273 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -57,7 +57,7 @@ NGINX Ingress Controller validates the annotations of Ingress resources. If an I You can check if the Ingress Controller successfully applied the configuration for an Ingress. For our example `cafe-ingress-with-annotations` Ingress, we can run: -```console +```shell kubectl describe ing cafe-ingress-with-annotations . . . @@ -71,7 +71,7 @@ Note how the events section includes a Normal event with the AddedOrUpdated reas If you create an invalid Ingress, the Ingress Controller will reject it and emit a Rejected event. For example, if you create an Ingress `cafe-ingress-with-annotations`, with an annotation `nginx.org/redirect-to-https` set to `yes please` instead of `true`, you will get: -```console +```shell kubectl describe ing cafe-ingress-with-annotations . . . diff --git a/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md b/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md index fd83073a90..6001d18e4f 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md @@ -104,7 +104,7 @@ If a snippet includes an invalid NGINX configuration, the Ingress Controller wil An example of an error from the logs: -``` +```shell [emerg] 31#31: unknown directive "badd_header" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54 Event(v1.ObjectReference{Kind:"Ingress", Namespace:"default", Name:"cafe-ingress-with-snippets", UID:"f9656dc9-63a6-41dd-a499-525b0e0309bb", APIVersion:"extensions/v1beta1", ResourceVersion:"2322030", FieldPath:""}): type: 'Warning' reason: 'AddedOrUpdatedWithError' Configuration for default/cafe-ingress-with-snippets was added or updated, but not applied: Error reloading NGINX for default/cafe-ingress-with-snippets: nginx reload failed: Command /usr/sbin/nginx -s reload stdout: "" stderr: "nginx: [emerg] unknown directive \"badd_header\" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54\n" @@ -113,7 +113,7 @@ finished with error: exit status 1 An example of an event with an error (you can view events associated with the Ingress by running `kubectl describe -n nginx-ingress ingress nginx-ingress`): -``` +```shell Events: Type Reason Age From Message ---- ------ ---- ---- ------- diff --git a/docs/content/configuration/ingress-resources/custom-annotations.md b/docs/content/configuration/ingress-resources/custom-annotations.md index c1fefcb130..67738816b3 100644 --- a/docs/content/configuration/ingress-resources/custom-annotations.md +++ b/docs/content/configuration/ingress-resources/custom-annotations.md @@ -57,7 +57,7 @@ spec: Assuming that the Ingress Controller is using that customized template, it will generate a config for the Ingress resource that will include the following part, generated by our template excerpt: -``` +```yaml # This is the configuration for cafe-ingress/default # Insert config for feature A if the annotation is set diff --git a/docs/content/configuration/policy-resource.md b/docs/content/configuration/policy-resource.md index a28b703cc8..5b96c58f27 100644 --- a/docs/content/configuration/policy-resource.md +++ b/docs/content/configuration/policy-resource.md @@ -502,7 +502,7 @@ You can use the usual `kubectl` commands to work with Policy resources, just as For example, the following command creates a Policy resource defined in `access-control-policy-allow.yaml` with the name `webapp-policy`: -```console +```shell kubectl apply -f access-control-policy-allow.yaml policy.k8s.nginx.org/webapp-policy configured @@ -510,7 +510,7 @@ policy.k8s.nginx.org/webapp-policy configured You can get the resource by running: -```console +```shell kubectl get policy webapp-policy NAME AGE @@ -670,7 +670,7 @@ If you try to create (or update) a resource that violates the structural schema - Example of `kubectl` validation: - ```console + ```shell kubectl apply -f access-control-policy-allow.yaml error: error validating "access-control-policy-allow.yaml": error validating data: ValidationError(Policy.spec.accessControl.allow): invalid type for org.nginx.k8s.v1.Policy.spec.accessControl.allow: got "string", expected "array"; if you choose to ignore these errors, turn validation off with --validate=false @@ -678,7 +678,7 @@ If you try to create (or update) a resource that violates the structural schema - Example of Kubernetes API server validation: - ```console + ```shell kubectl apply -f access-control-policy-allow.yaml --validate=false The Policy "webapp-policy" is invalid: spec.accessControl.allow: Invalid value: "string": spec.accessControl.allow in body must be of type array: "string" @@ -692,7 +692,7 @@ NGINX Ingress Controller validates the fields of a Policy resource. If a resourc You can use `kubectl` to check whether or not NGINX Ingress Controller successfully applied a Policy configuration. For our example `webapp-policy` Policy, we can run: -```console +```shell kubectl describe pol webapp-policy . . . @@ -706,7 +706,7 @@ Note how the events section includes a Normal event with the AddedOrUpdated reas If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a Policy `webapp-policy` with an invalid IP `10.0.0.` in the `allow` field, you will get: -```console +```shell kubectl describe policy webapp-policy . . . @@ -720,7 +720,7 @@ Note how the events section includes a Warning event with the Rejected reason. Additionally, this information is also available in the `status` field of the Policy resource. Note the Status section of the Policy: -```console +```shell kubectl describe pol webapp-policy . . . diff --git a/docs/content/configuration/transportserver-resource.md b/docs/content/configuration/transportserver-resource.md index c0d0d9d44d..2ef19d51f3 100644 --- a/docs/content/configuration/transportserver-resource.md +++ b/docs/content/configuration/transportserver-resource.md @@ -278,7 +278,7 @@ You can use the usual `kubectl` commands to work with TransportServer resources, For example, the following command creates a TransportServer resource defined in `transport-server-passthrough.yaml` with the name `secure-app`: -```console +```shell kubectl apply -f transport-server-passthrough.yaml transportserver.k8s.nginx.org/secure-app created @@ -286,7 +286,7 @@ transportserver.k8s.nginx.org/secure-app created You can get the resource by running: -```console +```shell kubectl get transportserver secure-app NAME AGE @@ -363,7 +363,7 @@ If you try to create (or update) a resource that violates the structural schema - Example of `kubectl` validation: - ```console + ```shell kubectl apply -f transport-server-passthrough.yaml error: error validating "transport-server-passthrough.yaml": error validating data: ValidationError(TransportServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.TransportServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false @@ -371,7 +371,7 @@ If you try to create (or update) a resource that violates the structural schema - Example of Kubernetes API server validation: - ```console + ```shell kubectl apply -f transport-server-passthrough.yaml --validate=false The TransportServer "secure-app" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: @@ -386,7 +386,7 @@ The Ingress Controller validates the fields of a TransportServer resource. If a You can check if the Ingress Controller successfully applied the configuration for a TransportServer. For our example `secure-app` TransportServer, we can run: -```console +```shell kubectl describe ts secure-app . . . @@ -400,7 +400,7 @@ Note how the events section includes a Normal event with the AddedOrUpdated reas If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you create a TransportServer `secure-app` with a pass action that references a non-existing upstream, you will get : -```console +```shell kubectl describe ts secure-app . . . diff --git a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md index 209ca295d0..2cc77b556d 100644 --- a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md @@ -936,7 +936,7 @@ You can use the usual `kubectl` commands to work with VirtualServer and VirtualS For example, the following command creates a VirtualServer resource defined in `cafe-virtual-server.yaml` with the name `cafe`: -```console +```shell kubectl apply -f cafe-virtual-server.yaml virtualserver.k8s.nginx.org "cafe" created @@ -944,7 +944,7 @@ virtualserver.k8s.nginx.org "cafe" created You can get the resource by running: -```console +```shell kubectl get virtualserver cafe NAME STATE HOST IP PORTS AGE @@ -1024,7 +1024,7 @@ If you try to create (or update) a resource that violates the structural schema - Example of `kubectl` validation: - ```console + ```shell kubectl apply -f cafe-virtual-server.yaml error: error validating "cafe-virtual-server.yaml": error validating data: ValidationError(VirtualServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.VirtualServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false @@ -1032,7 +1032,7 @@ If you try to create (or update) a resource that violates the structural schema - Example of Kubernetes API server validation: - ```console + ```shell kubectl apply -f cafe-virtual-server.yaml --validate=false The VirtualServer "cafe" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: @@ -1047,7 +1047,7 @@ The Ingress Controller validates the fields of the VirtualServer and VirtualServ You can check if the Ingress Controller successfully applied the configuration for a VirtualServer. For our example `cafe` VirtualServer, we can run: -```console +```shell kubectl describe vs cafe . . . @@ -1061,7 +1061,7 @@ Note how the events section includes a Normal event with the AddedOrUpdated reas If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you create a VirtualServer `cafe` with two upstream with the same name `tea`, you will get: -```console +```shell kubectl describe vs cafe . . . @@ -1075,7 +1075,7 @@ Note how the events section includes a Warning event with the Rejected reason. Additionally, this information is also available in the `status` field of the VirtualServer resource. Note the Status section of the VirtualServer: -```console +```shell kubectl describe vs cafe . . . diff --git a/docs/content/installation/installing-nic/installation-with-helm.md b/docs/content/installation/installing-nic/installation-with-helm.md index 6ce206d878..7a8ddbce7a 100644 --- a/docs/content/installation/installing-nic/installation-with-helm.md +++ b/docs/content/installation/installing-nic/installation-with-helm.md @@ -38,7 +38,7 @@ kubectl apply -f crds/ Alternatively, CRDs can be upgraded without pulling the chart by running: -```console +```shell kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.1/deploy/crds.yaml ``` diff --git a/docs/content/installation/integrations/app-protect-dos/configuration.md b/docs/content/installation/integrations/app-protect-dos/configuration.md index 600f416998..f7d96fadb6 100644 --- a/docs/content/installation/integrations/app-protect-dos/configuration.md +++ b/docs/content/installation/integrations/app-protect-dos/configuration.md @@ -32,7 +32,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 @@ -43,7 +43,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 @@ -76,10 +76,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 2c76cb2f2f..fcc42aff2d 100644 --- a/docs/content/installation/integrations/app-protect-dos/dos-protected.md +++ b/docs/content/installation/integrations/app-protect-dos/dos-protected.md @@ -2,20 +2,18 @@ docs: DOCS-581 doctypes: - '' -title: DoS Protected Resource +title: DoS protected resource specification toc: true weight: 300 --- -NGINX App Protect DoS Protected Resource Specification +NGINX App Protect DoS protected resource specification -> Note: This feature is only available in NGINX Plus with App Protect DoS. +{{< 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 >}} -> Note: The feature is implemented using the NGINX Plus [NGINX App Protect DoS Module](/nginx-app-protect-dos/deployment-guide/learn-about-deployment/). +## 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 @@ -27,7 +25,6 @@ spec: name: "my-dos" apDosMonitor: uri: "webapp.example.com" - ``` {{% table %}} @@ -53,51 +50,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 ---- ------ ---- ---- ------- @@ -106,17 +108,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 e76f04a166..dc699bdb66 100644 --- a/docs/content/installation/integrations/app-protect-dos/installation.md +++ b/docs/content/installation/integrations/app-protect-dos/installation.md @@ -2,7 +2,7 @@ docs: DOCS-583 doctypes: - '' -title: Building NGINX Ingress Controller with NGINX App Protect DoS +title: Build NGINX Ingress Controller with NGINX App Protect DoS toc: true weight: 100 --- 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 92% 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 ccb041f13a..ad8aee8705 100644 --- a/docs/content/troubleshooting/troubleshooting-app-protect-dos.md +++ b/docs/content/installation/integrations/app-protect-dos/troubleshooting-app-protect-dos.md @@ -2,18 +2,18 @@ docs: DOCS-1456 doctypes: - '' -title: Troubleshooting with NGINX App Protect DoS +title: Troubleshooting NGINX App Protect DoS toc: true -weight: 600 +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. +To troubleshoot other parts of NGINX Ingress Controller, check the [troubleshooting]({{< relref "troubleshooting/troubleshoot-common.md" >}}) section of the documentation. -## Potential Problems +## 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 0c0c3e91fb..944e2e5590 100644 --- a/docs/content/installation/integrations/app-protect-waf/configuration.md +++ b/docs/content/installation/integrations/app-protect-waf/configuration.md @@ -4,12 +4,12 @@ doctypes: - '' title: Configuration toc: true -weight: 1900 +weight: 200 --- This document explains how to use F5 NGINX Ingress Controller to configure NGINX App Protect WAF. -> 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 >}} 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 @@ -28,19 +28,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 { @@ -104,9 +104,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. @@ -114,7 +114,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 { @@ -145,13 +145,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. @@ -266,7 +266,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. @@ -274,7 +274,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 @@ -288,7 +288,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 @@ -407,7 +407,7 @@ paths: In this case, the following request will trigger an `Illegal parameter data type` violation, as we expect to have an integer value in the `query_int` parameter: -``` +```none http://localhost/query?query_int=abc ``` @@ -421,20 +421,20 @@ 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 + ```shell IC_IP=XXX.YYY.ZZZ.III ``` 3. Save the HTTP port of NGINX Ingress Controller into a shell variable: - ```console + ```shell IC_HTTP_PORT= ``` @@ -442,7 +442,7 @@ In this example we deploy NGINX Ingress Controller with NGINX Plus and NGINX App Create the application deployment and service: - ```console + ```shell kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.1/examples/custom-resources/app-protect-waf/webapp.yaml ``` @@ -450,13 +450,13 @@ Create the application deployment and service: 1. Create the syslog service and pod for the NGINX App Protect WAF security logs: - ```console + ```shell kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.1/examples/custom-resources/app-protect-waf/syslog.yaml ``` 2. Create the User-Defined Signature, WAF policy, and log configuration: - ```console + ```shell kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.1/examples/custom-resources/app-protect-waf/ap-apple-uds.yaml kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.1/examples/custom-resources/app-protect-waf/ap-dataguard-alarm-policy.yaml kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.1/examples/custom-resources/app-protect-waf/ap-logconf.yaml @@ -466,7 +466,7 @@ Create the application deployment and service: Create the WAF policy - ```console + ```shell kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.1/examples/custom-resources/app-protect-waf/waf.yaml ``` @@ -476,7 +476,7 @@ Create the WAF policy 1. Create the VirtualServer Resource: - ```console + ```shell kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.1/examples/custom-resources/app-protect-waf/virtual-server.yaml ``` @@ -488,33 +488,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/