diff --git a/docs/content/configuration/global-configuration/configmap-resource.md b/docs/content/configuration/global-configuration/configmap-resource.md index 40887762e7..a6aace92ca 100644 --- a/docs/content/configuration/global-configuration/configmap-resource.md +++ b/docs/content/configuration/global-configuration/configmap-resource.md @@ -1,10 +1,8 @@ --- -docs: DOCS-586 -doctypes: -- '' title: ConfigMap resources toc: true weight: 300 +docs: DOCS-586 --- When using F5 NGINX Ingress Controller, you can customize or fine tune NGINX behavior using ConfigMap resources. Examples include setting the number of worker processes or customizing the access log format. diff --git a/docs/content/configuration/global-configuration/custom-templates.md b/docs/content/configuration/global-configuration/custom-templates.md index 35a390fcb1..3d76703ae4 100644 --- a/docs/content/configuration/global-configuration/custom-templates.md +++ b/docs/content/configuration/global-configuration/custom-templates.md @@ -1,10 +1,8 @@ --- -docs: DOCS-587 -doctypes: -- '' title: Custom templates toc: true weight: 500 +docs: DOCS-587 --- diff --git a/docs/content/configuration/host-and-listener-collisions.md b/docs/content/configuration/host-and-listener-collisions.md index 3d81f58abd..be7fc82123 100644 --- a/docs/content/configuration/host-and-listener-collisions.md +++ b/docs/content/configuration/host-and-listener-collisions.md @@ -1,10 +1,8 @@ --- -docs: DOCS-590 -doctypes: -- '' title: Host and Listener collisions toc: true weight: 1700 +docs: DOCS-590 --- This document explains how F5 NGINX Ingress Controller handles host and listener collisions between resources. 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 46d02dffd2..dc0b8a3d02 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -1,10 +1,8 @@ --- -docs: DOCS-591 -doctypes: -- '' title: Advanced configuration with Annotations toc: true weight: 200 +docs: DOCS-591 --- This topic explains how to enable advanced features in F5 NGINX Ingress Controller with Annotations. @@ -200,7 +198,7 @@ The table below summarizes the available annotations. | *nginx.org/server-snippets* | *server-snippets* | Sets a custom snippet in server context. | N/A | | {{}} -### App Protect WAF {#app-protect} +### App Protect WAF {{< note >}} The App Protect annotations only work if the App Protect WAF module is [installed]({{< relref "installation/integrations/app-protect-waf/installation.md" >}}). {{< /note >}} 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 8b7006acbe..d087b72338 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md @@ -1,18 +1,14 @@ --- -docs: DOCS-592 -doctypes: -- '' title: Advanced configuration with Snippets toc: true weight: 400 +docs: DOCS-592 --- Snippets allow you to insert raw NGINX config into different contexts of the NGINX configurations that F5 NGINX Ingress Controller generates. Snippets are intended for advanced NGINX users who need more control over the generated NGINX configuration, and can be used in cases where Annotations and ConfigMap entries would not apply. - - ## Disadvantages of snippets Snippets are configured [using Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#snippets-and-custom-templates" >}}), but are disabled by default due to their complexity. They are also available through the [ConfigMap]({{< relref "/configuration/global-configuration/configmap-resource.md#snippets-and-custom-templates" >}}) resource. diff --git a/docs/content/configuration/ingress-resources/basic-configuration.md b/docs/content/configuration/ingress-resources/basic-configuration.md index 2eef418b98..732def8dd5 100644 --- a/docs/content/configuration/ingress-resources/basic-configuration.md +++ b/docs/content/configuration/ingress-resources/basic-configuration.md @@ -1,10 +1,8 @@ --- -docs: DOCS-593 -doctypes: -- '' title: Basic configuration toc: true weight: 100 +docs: DOCS-593 --- This document shows a basic Ingress resource definition for F5 NGINX Ingress Controller. It load balances requests for two services as part of a single application. @@ -55,7 +53,6 @@ To learn more about the Ingress resource, view [the official Kubernetes document {{< note >}} For complete instructions on deploying Ingress and Secret resources in the cluster, see the [complete example](https://github.com/nginxinc/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/complete-example) in the GitHub repository. {{< /note >}} - ## New features available in Kubernetes 1.18 Starting from Kubernetes 1.18, you can use the following new features: diff --git a/docs/content/configuration/policy-resource.md b/docs/content/configuration/policy-resource.md index 3ef091240a..beddaff116 100644 --- a/docs/content/configuration/policy-resource.md +++ b/docs/content/configuration/policy-resource.md @@ -67,8 +67,11 @@ accessControl: deny: - 10.0.0.0/8 ``` +{{< note >}} -> Note: The feature is implemented using the NGINX [ngx_http_access_module](http://nginx.org/en/docs/http/ngx_http_access_module.html). NGINX Ingress Controller access control policy supports either allow or deny rules, but not both (as the module does). +The feature is implemented using the NGINX [ngx_http_access_module](http://nginx.org/en/docs/http/ngx_http_access_module.html). NGINX Ingress Controller access control policy supports either allow or deny rules, but not both (as the module does). + +{{< /note >}} {{% table %}} |Field | Description | Type | Required | @@ -110,8 +113,11 @@ rateLimit: zoneSize: 10M key: ${binary_remote_addr} ``` +{{< note >}} + +The feature is implemented using the NGINX [ngx_http_limit_req_module](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html). -> Note: The feature is implemented using the NGINX [ngx_http_limit_req_module](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html). +{{< /note >}} {{% table %}} |Field | Description | Type | Required | @@ -128,7 +134,11 @@ rateLimit: |``scale`` | Enables a constant rate-limit by dividing the configured rate by the number of nginx-ingress pods currently serving traffic. This adjustment ensures that the rate-limit remains consistent, even as the number of nginx-pods fluctuates due to autoscaling. Note: This will not work properly if requests from a client are not evenly distributed accross all ingress pods (sticky sessions, long lived TCP-Connections with many requests etc.). In such cases using NGINX+'s zone-sync feature instead would give better results. | ``bool`` | No | {{% /table %}} -> For each policy referenced in a VirtualServer and/or its VirtualServerRoutes, NGINX Ingress Controller will generate a single rate limiting zone defined by the [`limit_req_zone`](http://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone) directive. If two VirtualServer resources reference the same policy, NGINX Ingress Controller will generate two different rate limiting zones, one zone per VirtualServer. +{{< note >}} + +For each policy referenced in a VirtualServer and/or its VirtualServerRoutes, NGINX Ingress Controller will generate a single rate limiting zone defined by the [`limit_req_zone`](http://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone) directive. If two VirtualServer resources reference the same policy, NGINX Ingress Controller will generate two different rate limiting zones, one zone per VirtualServer. + +{{< /note >}} #### RateLimit Merging Behavior @@ -147,7 +157,11 @@ When you reference more than one rate limit policy, NGINX Ingress Controller wil The API Key auth policy configures NGINX to authorize client requests based on the presence of a valid API Key in a header or query param specified in the policy. -> Note: The feature is implemented using NGINX [ngx_http_auth_request_module](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) and [NGINX JavaScript (NJS)](https://nginx.org/en/docs/njs/). +{{< note >}} + +The feature is implemented using NGINX [ngx_http_auth_request_module](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) and [NGINX JavaScript (NJS)](https://nginx.org/en/docs/njs/). + +{{< /note >}} The policies' API keys are securely stored using SHA-256 hashing. When a client sends an API Key, it is hashed by NJS and then compared to the hashed API Key in the NGINX config. @@ -229,8 +243,9 @@ basicAuth: secret: htpasswd-secret realm: "My API" ``` - -> Note: The feature is implemented using the NGINX [ngx_http_auth_basic_module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html). +{{< note >}} +The feature is implemented using the NGINX [ngx_http_auth_basic_module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html). +{{< /note >}} {{% table %}} |Field | Description | Type | Required | @@ -253,7 +268,11 @@ In this example NGINX Ingress Controller will use the configuration from the fir ### JWT Using Local Kubernetes Secret -> Note: This feature is only available in NGINX Plus. +{{< note >}} + +This feature is only available with NGINX Plus. + +{{< /note >}} The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens. @@ -284,7 +303,11 @@ We use the `requestHeaders` of the [Action.Proxy](/nginx-ingress-controller/conf The value of the `${jwt_claim_user}` variable is the `user` claim of a JWT. For other claims, use `${jwt_claim_name}`, where `name` is the name of the claim. Note that nested claims and claims that include a period (`.`) are not supported. Similarly, use `${jwt_header_name}` where `name` is the name of a header. In our example, we use the `alg` header. -> Note: This feature is implemented using the NGINX Plus [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). +{{< note >}} + +This feature is implemented using the NGINX Plus [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). + +{{< /note >}} {{% table %}} |Field | Description | Type | Required | @@ -308,7 +331,11 @@ In this example NGINX Ingress Controller will use the configuration from the fir ### JWT Using JWKS From Remote Location -> Note: This feature is only available in NGINX Plus. +{{< note >}} + +This feature is only available with NGINX Plus. + +{{< /note >}} The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens, allowing import of the keys (JWKS) for JWT policy by means of a URL (for a remote server or an identity provider) as a result they don't have to be copied and updated to the IC pod. @@ -322,7 +349,11 @@ jwt: keyCache: 1h ``` -> Note: This feature is implemented using the NGINX Plus directive [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) under [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). +{{< note >}} + +This feature is implemented using the NGINX Plus directive [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) under [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). + +{{< /note >}} {{% table %}} |Field | Description | Type | Required | @@ -333,8 +364,13 @@ jwt: |``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | {{% /table %}} -> Note: Content caching is enabled by default for each JWT policy with a default time of 12 hours. -> This is done to ensure to improve resiliency by allowing the JWKS (JSON Web Key Set) to be retrieved from the cache even when it has expired. +{{< note >}} + +Content caching is enabled by default for each JWT policy with a default time of 12 hours. + +This is done to ensure to improve resiliency by allowing the JWKS (JSON Web Key Set) to be retrieved from the cache even when it has expired. + +{{< /note >}} #### JWT Merging Behavior @@ -396,14 +432,22 @@ action: We use the `requestHeaders` of the [Action.Proxy](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#actionproxy) to set the values of the two headers that NGINX will pass to the upstream servers. See the [list of embedded variables](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#variables) that are supported by the `ngx_http_ssl_module`, which you can use to pass the client certificate details. -> Note: The feature is implemented using the NGINX [ngx_http_ssl_module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html). +{{< note >}} + + The feature is implemented using the NGINX [ngx_http_ssl_module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html). + + {{< /note >}} #### Using a Certificate Revocation List The IngressMTLS policy supports configuring at CRL for your policy. This can be done in one of two ways. -> Note: Only one of these configurations options can be used at a time. +{{< note >}} + + Only one of these configurations options can be used at a time. + +{{< /note >}} 1. Adding the `ca.crl` field to the `nginx.org/ca` secret type, which accepts a base64 encoded certificate revocation list (crl). Example YAML: @@ -421,8 +465,13 @@ data: 2. Adding the `crlFileName` field to your IngressMTLS policy spec with the name of the CRL file. -> Note: This configuration option should only be used when using a CRL that is larger than 1MiB -> Otherwise we recommend using the `nginx.org/ca` secret type for managing your CRL. +{{< note >}} + +This configuration option should only be used when using a CRL that is larger than 1MiB. + +Otherwise we recommend using the `nginx.org/ca` secret type for managing your CRL. + +{{< /note >}} Example YAML: @@ -482,7 +531,11 @@ egressMTLS: verifyDepth: 2 ``` -> Note: The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html). +{{< note >}} + +The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html). + +{{< /note >}} {{% table %}} |Field | Description | Type | Required | @@ -512,7 +565,11 @@ In this example NGINX Ingress Controller will use the configuration from the fir ### OIDC -> **Feature Status**: This feature is disabled by default. To enable it, set the [enable-oidc](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-enable-oidc) command-line argument of NGINX Ingress Controller. +{{< tip >}} + +This feature is disabled by default. To enable it, set the [enable-oidc]({{< relref "configuration/global-configuration/command-line-arguments.md#cmdoption-enable-oidc" >}}) command-line argument of NGINX Ingress Controller. + +{{< /tip >}} The OIDC policy configures NGINX Plus as a relying party for OpenID Connect authentication. @@ -531,14 +588,22 @@ spec: NGINX Plus will pass the ID of an authenticated user to the backend in the HTTP header `username`. -> Note: The feature is implemented using the [reference implementation](https://github.com/nginxinc/nginx-openid-connect/) of NGINX Plus as a relying party for OpenID Connect authentication. +{{< note >}} + +The feature is implemented using the [reference implementation](https://github.com/nginxinc/nginx-openid-connect/) of NGINX Plus as a relying party for OpenID Connect authentication. + +{{< /note >}} #### Prerequisites In order to use OIDC, you need to enable [zone synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/). If you don't set up zone synchronization, NGINX Plus will fail to reload. You also need to configure a resolver, which NGINX Plus will use to resolve the IDP authorization endpoint. You can find an example configuration [in our GitHub repository](https://github.com/nginxinc/kubernetes-ingress/blob/v{{< nic-version >}}/examples/custom-resources/oidc#step-7---configure-nginx-plus-zone-synchronization-and-resolver). -> **Note**: The configuration in the example doesn't enable TLS and the synchronization between the replica happens in clear text. This could lead to the exposure of tokens. +{{< warning >}} + +The configuration in the example doesn't enable TLS and the synchronization between the replica happens in clear text. This could lead to the exposure of tokens. + +{{< /warning >}} #### Limitations @@ -559,7 +624,11 @@ The OIDC policy defines a few internal locations that can't be customized: `/_jw |``accessTokenEnable`` | Option of whether Bearer token is used to authorize NGINX to access protected backend. | ``boolean`` | No | {{% /table %}} -> **Note**: Only one OIDC policy can be referenced in a VirtualServer and its VirtualServerRoutes. However, the same policy can still be applied to different routes in the VirtualServer and VirtualServerRoutes. +{{< note >}} + +Only one OIDC policy can be referenced in a VirtualServer and its VirtualServerRoutes. However, the same policy can still be applied to different routes in the VirtualServer and VirtualServerRoutes. + +{{< /note >}} #### OIDC Merging Behavior @@ -598,7 +667,7 @@ For `kubectl get` and similar commands, you can also use the short name `pol` in ### WAF {#waf} -> Note: This feature is only available in NGINX Plus with AppProtect. +{{< note >}} The feature is implemented using the NGINX Plus [NGINX App Protect WAF Module](https://docs.nginx.com/nginx-app-protect/configuration/). {{< /note >}} The WAF policy configures NGINX Plus to secure client requests using App Protect WAF policies. @@ -617,8 +686,7 @@ waf: logDest: "syslog:server=syslog-svc-secondary.default:514" ``` -> Note: The field `waf.securityLog` is deprecated and will be removed in future releases.It will be ignored if `waf.securityLogs` is populated. -> Note: The feature is implemented using the NGINX Plus [NGINX App Protect WAF Module](https://docs.nginx.com/nginx-app-protect/configuration/). +{{< note >}} The field `waf.securityLog` is deprecated and will be removed in future releases.It will be ignored if `waf.securityLogs` is populated. {{< /note >}} {{% table %}} |Field | Description | Type | Required | diff --git a/docs/content/configuration/transportserver-resource.md b/docs/content/configuration/transportserver-resource.md index d49588006c..531321bf9b 100644 --- a/docs/content/configuration/transportserver-resource.md +++ b/docs/content/configuration/transportserver-resource.md @@ -216,7 +216,6 @@ See the [match](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.h |``send`` | A string to send to an upstream server. | ``string`` | No | |``expect`` | A literal string or a regular expression that the data obtained from the server should match. The regular expression is specified with the preceding ``~*`` modifier (for case-insensitive matching), or the ``~`` modifier (for case-sensitive matching). NGINX Ingress Controller validates a regular expression using the RE2 syntax. | ``string`` | No | {{}} - ### UpstreamParameters The upstream parameters define various parameters for the upstreams: diff --git a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md index a8bd075dcc..6afefe25f4 100644 --- a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md @@ -1,10 +1,8 @@ --- -docs: DOCS-599 -doctypes: -- '' title: VirtualServer and VirtualServerRoute resources toc: true weight: 1600 +docs: DOCS-599 --- This document is reference material for the VirtualServer and VirtualServerRoute resources used by F5 NGINX Ingress Controller. @@ -151,12 +149,11 @@ https: https-8443 ### VirtualServer.ExternalDNS -The externalDNS field configures controlling DNS records dynamically for VirtualServer resources using [ExternalDNS](https://github.com/kubernetes-sigs/external-dns). Please see the [ExternalDNS configuration documentation](https://kubernetes-sigs.github.io/external-dns/v0.12.0/) for more information on deploying and configuring ExternalDNS and Providers. Example: +The externalDNS field configures controlling DNS records dynamically for VirtualServer resources using [ExternalDNS](https://github.com/kubernetes-sigs/external-dns). Please see the [ExternalDNS configuration documentation](https://kubernetes-sigs.github.io/external-dns/) for more information on deploying and configuring ExternalDNS and Providers. Example: ```yaml enable: true ``` - {{}} |Field | Description | Type | Required | | ---| ---| ---| --- | diff --git a/docs/content/installation/building-nginx-ingress-controller.md b/docs/content/installation/build-nginx-ingress-controller.md similarity index 89% rename from docs/content/installation/building-nginx-ingress-controller.md rename to docs/content/installation/build-nginx-ingress-controller.md index e4b1321a87..7ede182293 100644 --- a/docs/content/installation/building-nginx-ingress-controller.md +++ b/docs/content/installation/build-nginx-ingress-controller.md @@ -3,14 +3,16 @@ description: docs: DOCS-1453 doctypes: - installation -title: Building NGINX Ingress Controller +title: Build NGINX Ingress Controller toc: true weight: 200 --- -Learn how to build an NGINX Ingress Controller image from source code and upload it to a private Docker registry. You'll also find information on the Makefile targets and variables. +This document describes how to build an F5 NGINX Ingress Controller image from source code and upload it to a private Docker registry. -{{}}If you'd rather not build your own NGINX Ingress Controller image, see the [pre-built image options](#pre-built-images) at the end of this guide.{{}} +It also includes information on the Makefile targets and variables. + +{{}} If you do not need to build a custom image, see the [pre-built image options](#pre-built-images) at the end of this guide. {{}} ## Before you start @@ -22,7 +24,7 @@ To get started, you need the following software installed on your machine: - [OpenSSL](https://www.openssl.org/), optionally, if you would like to generate a self-signed certificate and a key for the default server. - For NGINX Plus users, download the certificate (_nginx-repo.crt_) and key (_nginx-repo.key_) from [MyF5](https://my.f5.com). -Although NGINX Ingress Controller is written in Golang, you don't need to have Golang installed. You can either download the precompiled binary file or build NGINX Ingress Controller in a Docker container. +Although NGINX Ingress Controller is written in Golang, you don't need to have Golang installed. You can download the precompiled binary file or build NGINX Ingress Controller in a Docker container. --- @@ -56,7 +58,7 @@ Get your system ready for building and pushing the NGINX Ingress Controller imag After setting up your environment, follow these steps to build the NGINX Ingress Controller image. -{{}}If you have a local Golang environment and want to build the binary yourself, remove `TARGET=download` from the make commands. If you don't have Golang but still want to build the binary, use `TARGET=container`.{{}} +{{< note >}} If you have a local Golang environment and want to build the binary yourself, remove `TARGET=download` from the make commands. If you don't have Golang but still want to build the binary, use `TARGET=container`. {{< /note >}} ### For NGINX @@ -100,7 +102,7 @@ After setting up your environment, follow these steps to build the NGINX Ingress **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_](#makefile-details). This version number is used for tracking and deployment purposes. -{{}}In the event a patch version of NGINX Plus is released, make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--pull --no-cache"` to the make command.{{}} +{{}} If a patch for NGINX Plus is released, make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--pull --no-cache"` to the make command. {{}} --- @@ -192,7 +194,7 @@ If you prefer not to build your own NGINX Ingress Controller image, you can use **NGINX Ingress Controller**: Download the image `nginx/nginx-ingress` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress) or [GitHub](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress). -**NGINX Plus Ingress Controller**: You have two options for this, both requiring an NGINX Ingress Controller subscription. +**NGINX Plus Ingress Controller**: You have two options for this: -- Download the image using your NGINX Ingress Controller subscription certificate and key. See the [Getting the F5 Registry NGINX Ingress Controller Image]({{< relref "installation/nic-images/pulling-ingress-controller-image.md" >}}) guide. -- Use your NGINX Ingress Controller subscription JWT token to get the image: Instructions are in [Getting the NGINX Ingress Controller Image with JWT]({{< relref "installation/nic-images/using-the-jwt-token-docker-secret.md" >}}). +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< relref "installation/nic-images/get-registry-image" >}}) topic. +- Use your NGINX Ingress Controller subscription JWT token to get the image. View the [Get the NGINX Ingress Controller image with JWT]({{< relref "installation/nic-images/get-image-using-jwt.md" >}}) topic. diff --git a/docs/content/installation/ingress-nginx.md b/docs/content/installation/ingress-nginx.md index adfce0953c..c20c842f1d 100644 --- a/docs/content/installation/ingress-nginx.md +++ b/docs/content/installation/ingress-nginx.md @@ -4,12 +4,12 @@ doctypes: - tutorial tags: - docs -title: Migrating from Ingress-NGINX Controller to NGINX Ingress Controller +title: Migrate from Ingress-NGINX Controller to NGINX Ingress Controller toc: true weight: 500 --- -This document describes how to migrate from the community-maintained Ingress-NGINX Controller to the F5 NGINX Ingress Controller. +This document describes how to migrate from the community-maintained Ingress-NGINX Controller to F5 NGINX Ingress Controller. ## Overview diff --git a/docs/content/installation/installing-nic/installation-with-helm.md b/docs/content/installation/installing-nic/installation-with-helm.md index 309c7334eb..42a859b0f6 100644 --- a/docs/content/installation/installing-nic/installation-with-helm.md +++ b/docs/content/installation/installing-nic/installation-with-helm.md @@ -1,36 +1,37 @@ --- docs: DOCS-602 -doctypes: -- '' title: Installation with Helm toc: true weight: 100 --- -This document explains how to install NGINX Ingress Controller using [Helm](https://helm.sh/). +This document explains how to install F5 NGINX Ingress Controller using [Helm](https://helm.sh/). -## Before you start +## Before you begin -{{}} All documentation should only be used with the latest stable release, indicated on [the releases page]({{< relref "releases.md" >}}) of the GitHub repository. {{}} +{{< note >}} All documentation should only be used with the latest stable release, indicated on [the releases page]({{< relref "releases.md" >}}) of the GitHub repository. {{< /note >}} -- A [Kubernetes Version Supported by the Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/technical-specifications/#supported-kubernetes-versions) +- A [Kubernetes Version Supported by NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/technical-specifications/#supported-kubernetes-versions) - Helm 3.0+. - If you’d like to use NGINX Plus: - - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/nic-images/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` or `controller.serviceAccount.imagePullSecretsNames` parameter. - - Alternatively, pull an NGINX Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/nic-images/pulling-ingress-controller-image" >}}). - - Alternatively, you can NGINX build an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/building-nginx-ingress-controller.md" >}}). + - Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< relref "installation/nic-images/get-registry-image.md" >}}) topic. + - The [Get the NGINX Ingress Controller image with JWT]({{< relref "installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. + - The [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry. - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. -- To use App Protect DoS, install the App Protect DoS Arbitrator [Helm Chart](https://github.com/nginxinc/nap-dos-arbitrator-helm-chart) in the same namespace as NGINX Ingress Controller. If you install multiple NGINX Ingress Controllers in the same namespace, they will need to share the same Arbitrator because there can only be one Arbitrator in a single namespace. -## CRDs +--- + +## Custom Resource Definitions -By default, the Ingress Controller requires a number of custom resource definitions (CRDs) installed in the cluster. The Helm client will install those CRDs. If the CRDs are not installed, the Ingress Controller pods will not become `Ready`. +NGINX Ingress Controller requires custom resource definitions (CRDs) installed in the cluster, which Helm will install. If the CRDs are not installed, NGINX Ingress Controller pods will not become `Ready`. If you do not use the custom resources that require those CRDs (which corresponds to `controller.enableCustomResources` set to `false` and `controller.appprotect.enable` set to `false` and `controller.appprotectdos.enable` set to `false`), the installation of the CRDs can be skipped by specifying `--skip-crds` for the helm install command. -### Upgrading the CRDs +--- + +### Upgrade the CRDs -To upgrade the CRDs, pull the chart sources as described in [Pulling the Chart](#pulling-the-chart) and then run: +To upgrade the CRDs, pull the chart sources as described in [Pull the Chart](#pull-the-chart) and then run: ```shell kubectl apply -f crds/ @@ -38,32 +39,32 @@ 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/v{{< nic-version >}}/deploy/crds.yaml ``` In the above command, `v{{< nic-version >}}` represents the version of NGINX Ingress Controller release rather than the Helm chart version. -{{}}The following warning is expected and can be ignored: `Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply`. +{{< note >}} The following warning is expected and can be ignored: `Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply`. -Make sure to check the [release notes](https://www.github.com/nginxinc/kubernetes-ingress/releases) for a new release for any special upgrade procedures. -{{}} +Check the [release notes](https://www.github.com/nginxinc/kubernetes-ingress/releases) for a new release for any special upgrade procedures. +{{< /note >}} -### Uninstalling the CRDs +### Uninstall the CRDs -To remove the CRDs, pull the chart sources as described in [Pulling the Chart](#pulling-the-chart) and then run: +To remove the CRDs, pull the chart sources as described in [Pull the Chart](#pull-the-chart) and then run: ```shell kubectl delete -f crds/ ``` -{{}}This command will delete all the corresponding custom resources in your cluster across all namespaces. Please ensure there are no custom resources that you want to keep and there are no other Ingress Controller releases running in the cluster.{{}} +{{< warning >}} This command will delete all the corresponding custom resources in your cluster across all namespaces. Please ensure there are no custom resources that you want to keep and there are no other NGINX Ingress Controller instances running in the cluster. {{< /warning >}} -## Managing the Chart via OCI Registry +## Manage the chart with OCI Registry -### Installing the Chart +### Install the chart -To install the chart with the release name my-release (my-release is the name that you choose): +Run the following commands to install the chart with the release name my-release (my-release is the name that you choose): - For NGINX: @@ -71,17 +72,17 @@ To install the chart with the release name my-release (my-release is the name th helm install my-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version {{< nic-helm-version >}} ``` -- For NGINX Plus: (assuming you have pushed the Ingress Controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`) +- For NGINX Plus: (This assumes you have pushed NGINX Ingress Controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`) ```shell helm install my-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version {{< nic-helm-version >}} --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true ``` -This will install the latest `edge` version of the Ingress Controller from GitHub Container Registry. If you prefer to use Docker Hub, you can replace `ghcr.io/nginxinc/charts/nginx-ingress` with `registry-1.docker.io/nginxcharts/nginx-ingress`. +These commands install the latest `edge` version of NGINX Ingress Controller from GitHub Container Registry. If you prefer using Docker Hub, you can replace `ghcr.io/nginxinc/charts/nginx-ingress` with `registry-1.docker.io/nginxcharts/nginx-ingress`. -### Upgrading the Chart +### Upgrade the chart -Helm does not upgrade the CRDs during a release upgrade. Before you upgrade a release, see [Upgrading the CRDs](#upgrading-the-crds). +Helm does not upgrade the CRDs during a release upgrade. Before you upgrade a release, see [Upgrade the CRDs](#upgrade-the-crds). To upgrade the release `my-release`: @@ -89,7 +90,7 @@ To upgrade the release `my-release`: helm upgrade my-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version {{< nic-helm-version >}} ``` -### Uninstalling the Chart +### Uninstall the chart To uninstall/delete the release `my-release`: @@ -99,9 +100,9 @@ helm uninstall my-release The command removes all the Kubernetes components associated with the release and deletes the release. -Uninstalling the release does not remove the CRDs. To remove the CRDs, see [Uninstalling the CRDs](#uninstalling-the-crds). +Uninstalling the release does not remove the CRDs. To remove the CRDs, see [Uninstall the CRDs](#uninstall-the-crds). -### Edge Version +### Edge version To test the latest changes in NGINX Ingress Controller before a new release, you can install the `edge` version. This version is built from the `main` branch of the NGINX Ingress Controller repository. You can install the `edge` version by specifying the `--version` flag with the value `0.0.0-edge`: @@ -110,15 +111,13 @@ You can install the `edge` version by specifying the `--version` flag with the v helm install my-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.0.0-edge ``` -> **Warning** -> -> The `edge` version is not intended for production use. It is intended for testing and development purposes only. +{{< warning >}} The `edge` version is not intended for production use. It is intended for testing and development purposes only. {{< /warning >}} -## Managing the Chart via Sources +## Manage the chart with Sources -### Pulling the Chart +### Pull the chart -This step is required if you're installing the chart using its sources. Additionally, the step is also required for managing the custom resource definitions (CRDs), which the Ingress Controller requires by default, or for upgrading/deleting the CRDs. +This step is required if you're installing the chart using its sources. It also manages the custom resource definitions (CRDs) which NGINX Ingress Controller requires, and for upgrading or deleting the CRDs. 1. Pull the chart sources: @@ -132,7 +131,7 @@ This step is required if you're installing the chart using its sources. Addition cd nginx-ingress ``` -### Installing the Chart +### Install the chart To install the chart with the release name my-release (my-release is the name that you choose): @@ -150,9 +149,9 @@ To install the chart with the release name my-release (my-release is the name th 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. -### Upgrading the Chart +### Upgrade the chart -Helm does not upgrade the CRDs during a release upgrade. Before you upgrade a release, see [Upgrading the CRDs](#upgrading-the-crds). +Helm does not upgrade the CRDs during a release upgrade. Before you upgrade a release, see [Upgrade the CRDs](#upgrade-the-crds). To upgrade the release `my-release`: @@ -160,7 +159,7 @@ To upgrade the release `my-release`: helm upgrade my-release . ``` -### Uninstalling the Chart +### Uninstall the chart To uninstall/delete the release `my-release`: @@ -170,21 +169,20 @@ helm uninstall my-release The command removes all the Kubernetes components associated with the release and deletes the release. -Uninstalling the release does not remove the CRDs. To remove the CRDs, see [Uninstalling the CRDs](#uninstalling-the-crds). +Uninstalling the release does not remove the CRDs. To remove the CRDs, see [Uninstall the CRDs](#uninstall-the-crds). - -## Upgrading without downtime +## Upgrade without downtime ### Background In NGINX Ingress Controller version 3.1.0, [changes were introduced](https://github.com/nginxinc/kubernetes-ingress/pull/3606) to Helm resource names, labels and annotations to fit with Helm best practices. When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated due to the aforementioned changes, which will result in downtime. -Although the advisory is to update all resources in accordance with new naming convention, to avoid the downtime please follow the steps listed in this page. +Although the advisory is to update all resources in accordance with new naming convention, to avoid downtime follow the steps listed below. -### Upgrade Steps +### Upgrade steps -{{}} The following steps apply to both 2.x and 3.0.x releases.{{}} +{{< note >}} The following steps apply to both 2.x and 3.0.x releases. {{}} The steps you should follow depend on the Helm release name: @@ -287,18 +285,20 @@ The steps you should follow depend on the Helm release name: {{}} -## Running Multiple Ingress Controllers +## Run multiple NGINX Ingress Controllers + +If you are running NGINX Ingress Controller releases in your cluster with custom resources enabled, the releases will share a single version of the CRDs. -If you are running multiple Ingress Controller releases in your cluster with enabled custom resources, the releases will share a single version of the CRDs. As a result, make sure that the Ingress Controller versions match the version of the CRDs. Additionally, when uninstalling a release, ensure that you don’t remove the CRDs until there are no other Ingress Controller releases running in the cluster. +Ensure the NGINX Ingress Controller versions match the version of the CRDs. When uninstalling a release, ensure that you don’t remove the CRDs until there are no other NGINX Ingress Controller releases running in the cluster. -See [running multiple Ingress Controllers]({{< relref "installation/running-multiple-ingress-controllers.md" >}}) for more details. +The [Run multiple NGINX Ingress Controllers]({{< relref "installation/run-multiple-ingress-controllers.md" >}}) topic has more details. ## Configuration The following tables lists the configurable parameters of the NGINX Ingress Controller chart and their default values. {{< table >}} -{{}} +{{}} |Parameter | Description | Default | | --- | --- | --- | | **controller.name** | The name of the Ingress Controller daemonset or deployment. | Autogenerated | @@ -479,8 +479,3 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont |**nginxAgent.customConfigMap** | The name of a custom ConfigMap to use instead of the one provided by default. | "" | {{}} {{< /table >}} - -## Notes - -- The values-icp.yaml file is used for deploying the Ingress Controller on IBM Cloud Private. See the [blog post](https://www.nginx.com/blog/nginx-ingress-controller-ibm-cloud-private/) for more details. -- The values-nsm.yaml file is used for deploying the Ingress Controller with NGINX Service Mesh. See the NGINX Service Mesh [docs](https://docs.nginx.com/nginx-service-mesh/tutorials/kic/deploy-with-kic/) for more details. diff --git a/docs/content/installation/installing-nic/installation-with-manifests.md b/docs/content/installation/installing-nic/installation-with-manifests.md index bfa0d847f9..f893b42003 100644 --- a/docs/content/installation/installing-nic/installation-with-manifests.md +++ b/docs/content/installation/installing-nic/installation-with-manifests.md @@ -13,17 +13,15 @@ This guide explains how to use Manifests to install F5 NGINX Ingress Controller, ### Get the NGINX Controller Image -{{}} Always use the latest stable release listed on the [releases page]({{< relref "releases.md" >}}). {{}} +{{< note >}} Always use the latest stable release listed on the [releases page]({{< relref "releases.md" >}}). {{< /note >}} Choose one of the following methods to get the NGINX Ingress Controller image: - **NGINX Ingress Controller**: Download the image `nginx/nginx-ingress` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress). - **NGINX Plus Ingress Controller**: You have two options for this, both requiring an NGINX Ingress Controller subscription. - - - Download the image using your NGINX Ingress Controller subscription certificate and key. Read the [Getting the F5 Registry NGINX Ingress Controller Image]({{< relref "installation/nic-images/pulling-ingress-controller-image.md" >}}) guide. - - Use your NGINX Ingress Controller subscription JWT token to get the image: Read the [Getting the NGINX Ingress Controller Image with JWT]({{< relref "installation/nic-images/using-the-jwt-token-docker-secret.md" >}}). - -- **Build your own image**: To build your own image, follow the [Building NGINX Ingress Controller]({{< relref "installation/building-nginx-ingress-controller.md" >}}) guide. + - Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< relref "installation/nic-images/get-registry-image.md" >}}) topic. + - The [Get the NGINX Ingress Controller image with JWT]({{< relref "installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. +- **Build your own image**: To build your own image, follow the [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md" >}}) topic. ### Clone the repository @@ -245,18 +243,18 @@ Connect to ports 80 and 443 using the IP address of any node in the cluster wher kubectl delete namespace nginx-ingress ``` -2. **Remove the cluster role and cluster role binding**: +1. **Remove the cluster role and cluster role binding**: ```shell kubectl delete clusterrole nginx-ingress kubectl delete clusterrolebinding nginx-ingress ``` -3. **Delete the Custom Resource Definitions**: +1. **Delete the Custom Resource Definitions**: - {{}} +{{}} - {{%tab name="Deleting CRDs from single YAML"%}} +{{%tab name="Deleting CRDs from single YAML"%}} 1. Delete core custom resource definitions: ```shell @@ -274,23 +272,23 @@ Connect to ports 80 and 443 using the IP address of any node in the cluster wher ``` {{%/tab%}} - {{%tab name="Deleting CRDs after cloning the repo"%}} +{{%tab name="Deleting CRDs after cloning the repo"%}} - 1. Delete core custom resource definitions: - ```shell - kubectl delete -f config/crd/bases/crds.yaml - ``` - 2. Delete custom resource definitions for the NGINX App Protect WAF module: +1. Delete core custom resource definitions: +```shell +kubectl delete -f config/crd/bases/crds.yaml +``` +2. Delete custom resource definitions for the NGINX App Protect WAF module: - ```shell - kubectl apply -f config/crd/bases/crds-nap-waf.yaml - ``` +```shell +kubectl apply -f config/crd/bases/crds-nap-waf.yaml +``` - 3. Delete custom resource definitions for the NGINX App Protect DoS module: - ```shell - kubectl apply -f config/crd/bases/crds-nap-dos.yaml - ``` +3. Delete custom resource definitions for the NGINX App Protect DoS module: +```shell +kubectl apply -f config/crd/bases/crds-nap-dos.yaml +``` - {{%/tab%}} +{{%/tab%}} - {{}} +{{}} diff --git a/docs/content/installation/installing-nic/installation-with-operator.md b/docs/content/installation/installing-nic/installation-with-operator.md index de4387aad8..2ccb083a7d 100644 --- a/docs/content/installation/installing-nic/installation-with-operator.md +++ b/docs/content/installation/installing-nic/installation-with-operator.md @@ -2,7 +2,7 @@ docs: DOCS-604 doctypes: - '' -title: Installation with the NGINX Ingress Operator +title: Installation with NGINX Ingress Operator toc: true weight: 300 --- @@ -11,19 +11,17 @@ This document explains how to use NGINX Ingress Operator to install NGINX Ingres ## Before you start -{{}} We recommend the most recent stable version of NGINX Ingress Controller, available on the GitHub repository's [releases page]({{< relref "releases.md" >}}). {{}} +{{< note >}} We recommend the most recent stable version of NGINX Ingress Controller, available on the GitHub repository's [releases page]({{< relref "releases.md" >}}). {{< /note >}} 1. Make sure you have access to the NGINX Ingress Controller image: - - For NGINX Ingress Controller, use the image `nginx/nginx-ingress` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress). - - For NGINX Plus Ingress Controller, see [here]({{< relref "installation/nic-images/pulling-ingress-controller-image" >}}) for details on how to pull the image from the F5 Docker registry. - - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here]({{< relref "installation/nic-images/using-the-jwt-token-docker-secret" >}}). - - It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here]({{< relref "installation/building-nginx-ingress-controller.md" >}})). - -2. Install the NGINX Ingress Operator following the [instructions](https://github.com/nginxinc/nginx-ingress-helm-operator/blob/main/docs/installation.md). -3. Create the SecurityContextConstraint as outlined in the ["Getting Started" instructions](https://github.com/nginxinc/nginx-ingress-helm-operator/blob/main/README.md#getting-started). + - For NGINX Plus Ingress Controller, view the [Get the F5 Registry NGINX Ingress Controller image]({{< relref "installation/nic-images/get-registry-image.md" >}}) topic for details on how to pull the image from the F5 Docker registry. + - The [Get the NGINX Ingress Controller image with JWT]({{< relref "installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. + - The [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry. +1. Install the NGINX Ingress Operator following the [instructions](https://github.com/nginxinc/nginx-ingress-helm-operator/blob/main/docs/installation.md). +1. Create the SecurityContextConstraint as outlined in the ["Getting Started" instructions](https://github.com/nginxinc/nginx-ingress-helm-operator/blob/main/README.md#getting-started). -{{}} If you're upgrading your operator installation to a later release, navigate [here](https://github.com/nginxinc/nginx-ingress-helm-operator/blob/main/helm-charts/nginx-ingress) and run `kubectl apply -f crds/` or `oc apply -f crds/` as a prerequisite{{}} +{{< note >}} If you're upgrading your operator installation to a later release, navigate [here](https://github.com/nginxinc/nginx-ingress-helm-operator/blob/main/helm-charts/nginx-ingress) and run `kubectl apply -f crds/` or `oc apply -f crds/` as a prerequisite {{< /note >}} ## Create the NGINX Ingress Controller manifest @@ -50,7 +48,7 @@ spec: imagePullSecretName: "" ``` -{{}}For NGINX Plus, change the `image.repository` and `image.tag` values and change `nginxPlus` to `True`. If required, set the `serviceAccount.imagePullSecretName` or `serviceAccount.imagePullSecretsNames` to the name of the pre-created docker config secret that should be associated with the ServiceAccount.{{}} +{{< note >}} For NGINX Plus, change the `image.repository` and `image.tag` values and change `nginxPlus` to `True`. If required, set the `serviceAccount.imagePullSecretName` or `serviceAccount.imagePullSecretsNames` to the name of the pre-created docker config secret that should be associated with the ServiceAccount. {{< /note >}} ## Deploy NGINX Ingress Controller diff --git a/docs/content/installation/integrations/app-protect-dos/configuration.md b/docs/content/installation/integrations/app-protect-dos/configuration.md index 2c49791866..8362dd3fbb 100644 --- a/docs/content/installation/integrations/app-protect-dos/configuration.md +++ b/docs/content/installation/integrations/app-protect-dos/configuration.md @@ -7,7 +7,11 @@ toc: true weight: 200 --- -> Check out the complete [NGINX Ingress Controller with App Protect DoS example for VirtualServer](https://github.com/nginxinc/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/app-protect-dos) and the [NGINX Ingress Controller with App Protect DoS example for Ingress](https://github.com/nginxinc/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-dos). +{{< tip >}} + + Check out the complete [NGINX Ingress Controller with App Protect DoS example for VirtualServer](https://github.com/nginxinc/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/app-protect-dos) and the [NGINX Ingress Controller with App Protect DoS example for Ingress](https://github.com/nginxinc/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-dos). + +{{< /tip >}} ## App Protect DoS Configuration diff --git a/docs/content/installation/integrations/app-protect-dos/installation.md b/docs/content/installation/integrations/app-protect-dos/installation.md index 5545d651b5..1a5bd14247 100644 --- a/docs/content/installation/integrations/app-protect-dos/installation.md +++ b/docs/content/installation/integrations/app-protect-dos/installation.md @@ -71,7 +71,7 @@ Follow these steps to build the NGINX Controller Image with NGINX App Protect Do make debian-image-dos-plus PREFIX=/nginx-plus-ingress TARGET=download ``` - **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}). This version number is used for tracking and deployment purposes. + **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_]({{< relref "installation/build-nginx-ingress-controller.md#makefile-details" >}}). This version number is used for tracking and deployment purposes. {{}}In the event a patch version of NGINX Plus is released, make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--pull --no-cache"` to the make command.{{}} @@ -88,7 +88,7 @@ Follow these steps to build the NGINX Controller Image with NGINX App Protect Do
-{{}}For the complete list of _Makefile_ targets and customizable variables, see the [Building NGINX Ingress Controller]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}) guide{{}} +{{< see-also >}} For the complete list of _Makefile_ targets and customizable variables, see the [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md#makefile-details" >}}) topic. {{}} --- @@ -176,6 +176,8 @@ kubectl apply -f config/crd/bases/appprotectdos.f5.com_dosprotectedresources.yam ## Install the App Protect DoS Arbitrator +{{< note >}} If you install multiple NGINX Ingress Controllers in the same namespace, they will need to share the same Arbitrator because there can only be one Arbitrator in a single namespace. {{< /note >}} + ### Helm Chart The App Protect DoS Arbitrator can be installed using the [NGINX App Protect DoS Helm Chart](https://github.com/nginxinc/nap-dos-arbitrator-helm-chart). @@ -224,5 +226,5 @@ For more information, see the [Configuration guide]({{< relref "installation/int If you prefer not to build your own NGINX Ingress Controller image, you can use pre-built images. Here are your options: -- Download the image using your NGINX Ingress Controller subscription certificate and key. See the [Getting the F5 Registry NGINX Ingress Controller Image]({{< relref "installation/nic-images/pulling-ingress-controller-image.md" >}}) guide. -- Use your NGINX Ingress Controller subscription JWT token to get the image: Instructions are in [Getting the NGINX Ingress Controller Image with JWT]({{< relref "installation/nic-images/using-the-jwt-token-docker-secret.md" >}}). +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< relref "installation/nic-images/get-registry-image.md" >}}) topic. + - The [Get the NGINX Ingress Controller image with JWT]({{< relref "installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. diff --git a/docs/content/installation/integrations/app-protect-dos/troubleshooting-app-protect-dos.md b/docs/content/installation/integrations/app-protect-dos/troubleshoot-app-protect-dos.md similarity index 99% rename from docs/content/installation/integrations/app-protect-dos/troubleshooting-app-protect-dos.md rename to docs/content/installation/integrations/app-protect-dos/troubleshoot-app-protect-dos.md index ad8aee8705..29efe18a6f 100644 --- a/docs/content/installation/integrations/app-protect-dos/troubleshooting-app-protect-dos.md +++ b/docs/content/installation/integrations/app-protect-dos/troubleshoot-app-protect-dos.md @@ -2,7 +2,7 @@ docs: DOCS-1456 doctypes: - '' -title: Troubleshooting NGINX App Protect DoS +title: Troubleshoot NGINX App Protect DoS toc: true weight: 400 --- diff --git a/docs/content/installation/integrations/app-protect-waf-v5/installation.md b/docs/content/installation/integrations/app-protect-waf-v5/installation.md index 09a6d50fdf..2a8da83e4b 100644 --- a/docs/content/installation/integrations/app-protect-waf-v5/installation.md +++ b/docs/content/installation/integrations/app-protect-waf-v5/installation.md @@ -74,13 +74,13 @@ Follow these steps to build the NGINX Controller Image with NGINX App Protect WA make debian-image-nap-v5-plus PREFIX=/nginx-plus-ingress TARGET=download ``` - **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}). This version number is used for tracking and deployment purposes. + **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_]({{< relref "installation/build-nginx-ingress-controller.md#makefile-details" >}}). This version number is used for tracking and deployment purposes. {{}} In the event a patch of NGINX Plus is released, make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--pull --no-cache"` to the make command. {{}} ### Makefile targets {#makefile-targets} -Create Docker image for Ingress Controller (Alpine with NGINX Plus, NGINX App Protect WAF v5 and FIPS) +Create Docker image for NGINX Ingress Controller (Alpine with NGINX Plus, NGINX App Protect WAF v5 and FIPS) {{}} | Makefile Target | Description | Compatible Systems | @@ -93,7 +93,7 @@ Create Docker image for Ingress Controller (Alpine with NGINX Plus, NGINX App Pr
-{{}} For the complete list of _Makefile_ targets and customizable variables, see the [Building NGINX Ingress Controller]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}) guide. {{}} +{{}} For the complete list of _Makefile_ targets and customizable variables, see the [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md#makefile-details" >}}) guide. {{}} If you intend to use [external references](/nginx-app-protect-waf/v5/configuration-guide/configuration/#external-references) in NGINX App Protect WAF policies, you may want to provide a custom CA certificate to authenticate with the hosting server. @@ -344,17 +344,11 @@ For more information, see the [Configuration guide]({{< relref "installation/int If you prefer not to build your own NGINX Ingress Controller image, you can use pre-built images. Here are your options: -- Download the image using your NGINX Ingress Controller subscription certificate and key. See the [Getting the F5 Registry NGINX Ingress Controller Image]({{< relref "installation/nic-images/pulling-ingress-controller-image.md" >}}) guide. -- Use your NGINX Ingress Controller subscription JWT token to get the image: Follow the instructions in [Getting the NGINX Ingress Controller Image with JWT]({{< relref "installation/nic-images/using-the-jwt-token-docker-secret.md" >}}). - ---- - -## [NGINX App Protect WAF v5 version](https://docs.nginx.com/nginx-app-protect-waf/v5/releases/) +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< relref "installation/nic-images/get-registry-image.md" >}}) topic. +- The [Get the NGINX Ingress Controller image with JWT]({{< relref "installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. {{< bootstrap-table "table table-bordered table-striped table-responsive" >}} | NIC Version | App Protect WAFv5 Version | Config Manager | Enforcer | | --- | --- | --- | --- | | 3.6.2 | 32_5.48 | 5.2.0 | 5.2.0 | {{% /bootstrap-table %}} - -{{< note >}} F5 recommends to re-compile your NGINX AppProtect WAF Policy Bundles with each release of NGINX Ingress Controller. This will ensure your Policies remain compatible and are compiled with the latest Attack Signatures, Bot Signatures, and Threat Campaigns.{{< /note >}} diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md new file mode 100644 index 0000000000..46ad91d8b3 --- /dev/null +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -0,0 +1,352 @@ +--- +docs: DOCS-000 +title: Compile NGINX App Protect WAF policies using NGINX Instance Manager +toc: true +weight: 300 +--- + +## Overview + +This guide describes how to use F5 NGINX Instance Manager to compile NGINX App Protect WAF Policies for use with NGINX Ingress Controller. + +NGINX App Protect WAF uses policies to configure which security features are set. When these policies are changed, they need to be compiled so that the engine can begin to use them. Compiling policies can take a large amount of time and resources. You can do this with the NGINX Instance Manager. This reduces the impact on a NGINX Ingress Controller deployment. + +By using NGINX Instance Manager to compile WAF policies, the policy bundle can also be used immediately by NGINX Ingress Controller without reloading. + +The following steps describe how to use the NGINX Instance Manager API to create a new security policy, compile a bundle, then add it to NGINX Ingress Controller. + +## Before you start +### Requirements +- A working [NGINX Management Suite](https://docs.nginx.com/nginx-management-suite/installation/) instance. +- An [NGINX Management Suite user](https://docs.nginx.com/nginx-management-suite/admin-guides/rbac/rbac-getting-started/) for API requests. +- A NGINX Ingress Controller [deployment with NGINX App Protect WAF]({{< relref "/installation/integrations/app-protect-waf/installation.md" >}}). + +## Create a new security policy + +{{< tip >}} You can skip this step if you intend to use an existing security policy. {{< /tip >}} + +Create a [new security policy](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy) using the API: this will require the use of a tool such as [`curl`](https://curl.se/) or [Postman](https://www.postman.com/) + +Create the file `simple-policy.json` with the contents below: + +```json +{ + "metadata": { + "name": "Nginxbundletest", + "displayName": "Nginxbundletest", + "description": "Ignore cross-site scripting is a security policy that intentionally ignores cross site scripting." + }, + "content": "ewoJInBvbGljeSI6IHsKCQkibmFtZSI6ICJzaW1wbGUtYmxvY2tpbmctcG9saWN5IiwKCQkic2lnbmF0dXJlcyI6IFsKCQkJewoJCQkJInNpZ25hdHVyZUlkIjogMjAwMDAxODM0LAoJCQkJImVuYWJsZWQiOiBmYWxzZQoJCQl9CgkJXSwKCQkidGVtcGxhdGUiOiB7CgkJCSJuYW1lIjogIlBPTElDWV9URU1QTEFURV9OR0lOWF9CQVNFIgoJCX0sCgkJImFwcGxpY2F0aW9uTGFuZ3VhZ2UiOiAidXRmLTgiLAoJCSJlbmZvcmNlbWVudE1vZGUiOiAiYmxvY2tpbmciCgl9Cn0=" +} +``` + +{{< warning >}} The `content` value must be base64 encoded or you will encounter an error. {{< /warning >}} + +Upload the policy JSON files with the API, which is the same method to create the bundle later. + +In the same directory you created `simple-policy.json`, create a POST request for NGINX Instance Manager using the API. + +```shell +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " \ + -d @simple-policy.json +``` + +You should receive an API response similar to the following output, indicating the policy has been successfully created. + +```json +{ + "metadata": { + "created": "2024-06-12T20:28:08.152171922Z", + "description": "Ignore cross-site scripting is a security policy that intentionally ignores cross site scripting.", + "displayName": "Nginxbundletest", + "externalId": "", + "externalIdType": "", + "modified": "2024-06-12T20:28:08.152171922Z", + "name": "Nginxbundletest", + "revisionTimestamp": "2024-06-12T20:28:08.152171922Z", + "uid": "6af9f261-658b-4be1-b07a-cebd83e917a1" + }, + "selfLink": { + "rel": "/api/platform/v1/security/policies/6af9f261-658b-4be1-b07a-cebd83e917a1" + } +} +``` + +{{< important >}} + +Take note of the *uid* field: `"uid": "6af9f261-658b-4be1-b07a-cebd83e917a1"` +It is one of two unique IDs we will use to download the bundle: it will be referenced as *policy-UID*. + +{{< /important >}} + +## Create a new security bundle + +Once you have created (Or selected) a security policy, [create a security bundle](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy-bundles) using the API. The version in the bundle you create **must** match the WAF compiler version you intend to use. + +You can check which version is installed in NGINX Instance Manager by checking the operating system packages. If the wrong version is noted in the JSON payload, you will receive an error similar to below: + +```text +{"code":13018,"message":"Error compiling the security policy set: One or more of the specified compiler versions does not exist. Check the compiler versions, then try again."} +``` + +Create the file `security-policy-bundles.json`: + +```json +{ + "bundles": [ + { + "appProtectWAFVersion": "4.815.0", + "policyName": "Nginxbundletest", + "policyUID": "", + "attackSignatureVersionDateTime": "latest", + "threatCampaignVersionDateTime": "latest" + } + ] +} +``` + +The *policyUID* value is left blank, as it is generated as part of the creating the bundle. + +Send a POST request to create the bundle through the API: + +```shell +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ + -H "Authorization: Bearer " \ + -d @security-policy-bundles.json +``` + +You should receive a response similar to the following: + +```json +{ + "items": [ + { + "compilationStatus": { + "message": "", + "status": "compiling" + }, + "content": "", + "metadata": { + "appProtectWAFVersion": "4.815.0", + "attackSignatureVersionDateTime": "2024.02.21", + "created": "2024-06-12T13:28:20.023775785-07:00", + "modified": "2024-06-12T13:28:20.023775785-07:00", + "policyName": "Nginxbundletest", + "policyUID": "6af9f261-658b-4be1-b07a-cebd83e917a1", + "threatCampaignVersionDateTime": "2024.02.25", + "uid": "cbdf9577-6d81-43d6-8ce1-2e3d4714e8b5" + } + } + ] +} +``` + +You can use the API to list the security bundles, verifying the new addition: + +```shell +curl --location 'https://127.0.0.1/api/platform/v1/security/policies/bundles' \ +-H "Authorization: Bearer " +``` +```json +{ + "items": [ + { + "compilationStatus": { + "message": "", + "status": "compiled" + }, + "content": "", + "metadata": { + "appProtectWAFVersion": "4.815.0", + "attackSignatureVersionDateTime": "2024.02.21", + "created": "2024-06-13T09:09:10.809-07:00", + "modified": "2024-06-13T09:09:20-07:00", + "policyName": "Nginxbundletest", + "policyUID": "ec8681eb-1e25-4b71-93bd-b91f67c5ac99", + "threatCampaignVersionDateTime": "2024.02.25", + "uid": "de08b324-99d8-4155-b2eb-fe687b21034e" + } + } + ] +} +``` + +{{< important >}} + +Take note of the *uid* field: `"uid": "de08b324-99d8-4155-b2eb-fe687b21034e"` + +It is one of two unique IDs we will use to download the bundle: it will be referenced as *bundle-UID*. + +{{< /important >}} + +## Download the security bundle + +Use a GET request to download the security bundle using the policy and bundle IDs: + +```shell +curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies//bundles/" -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz +``` + +This GET request uses the policy and bundle IDs from the previous examples: + +```shell +curl -X GET -k 'https://127.0.0.1/api/platform/v1/security/policies/6af9f261-658b-4be1-b07a-cebd83e917a1/bundles/de08b324-99d8-4155-b2eb-fe687b21034e' \ + -H "Authorization: Basic YWRtaW46UncxQXBQS3lRRTRuQXRXOFRYa1J4ZFdVSWVTSGtU" \ + | jq -r '.content' | base64 -d > security-policy-bundle.tgz +``` + +## Add volumes and volumeMounts to NGINX Ingress Controller + +To use WAF security bundles, your NGINX Ingress Controller instance must have *volumes* and *volumeMounts*. Precise paths are used to detect when bundles are uploaded to the cluster. + +Here is an example of what to add: + +```yaml +volumes: +- name: +persistentVolumeClaim: + claimName: + +volumeMounts: +- name: + mountPath: /etc/nginx/waf/bundles +``` + +A full example of a deployment file with `volumes` and `volumeMounts` could look like the following: + +```yaml + +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + app.kubernetes.io/name: nginx-ingress + #annotations: + #prometheus.io/scrape: "true" + #prometheus.io/port: "9113" + #prometheus.io/scheme: http + spec: + serviceAccountName: nginx-ingress + automountServiceAccountToken: true + securityContext: + seccompProfile: + type: RuntimeDefault + volumes: + - name: nginx-bundle-mount + emptydir: {} + containers: + - image: + imagePullPolicy: IfNotPresent + name: nginx-ingress + ports: + - name: http + containerPort: 80 + - name: https + containerPort: 443 + - name: readiness-port + containerPort: 8081 + - name: prometheus + containerPort: 9113 + readinessProbe: + httpGet: + path: /nginx-ready + port: readiness-port + periodSeconds: 1 + resources: + requests: + cpu: "100m" + memory: "128Mi" + #limits: + # cpu: "1" + # memory: "1Gi" + securityContext: + allowPrivilegeEscalation: false + runAsUser: 101 #nginx + runAsNonRoot: true + capabilities: + drop: + - ALL + add: + - NET_BIND_SERVICE + volumeMounts: + - name: bundle-mount + mountPath: /etc/nginx/waf/bundles + env: + - name: POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + args: + - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config + - -report-ingress-status + - -external-service=nginx-ingress +``` + +## Create WAF policy + +To process a bundle, you must create a new WAF policy. This policy is added to `/etc/nginx/waf/bundles`, allowing NGINX Ingress Controller to load it into WAF. + +The example below shows the required WAF policy, and the *apBundle* and *apLogConf* fields you must use for the security bundle binary file (A tar ball). + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: Policy +metadata: + name: +spec: + waf: + enable: true + apBundle: ".tgz" + securityLogs: + - enable: true + apLogBundle: ".tgz" + logDest: "" +``` + +## Create VirtualServer resource and apply policy + +Once the WAF policy has been created, link it to your *virtualServer resource*. + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: webapp +spec: + host: webapp.example.com + policies: + - name: + upstreams: + - name: webapp + service: webapp-svc + port: 80 + routes: + - path: / + action: + pass: webapp +``` + +## Upload the security bundle + +To finish adding a security bundle, the binary file to the NGINX Ingress Controller pods. + +```shell +kubectl cp /your/local/path/.tgz /:etc/nginx/waf/bundles.tgz +``` + +Once the bundle has been uploaded to the cluster, NGINX Ingress Controller will detect and automatically load the new WAF policy. diff --git a/docs/content/installation/integrations/app-protect-waf/configuration.md b/docs/content/installation/integrations/app-protect-waf/configuration.md index 21365c5af6..423430dbd6 100644 --- a/docs/content/installation/integrations/app-protect-waf/configuration.md +++ b/docs/content/installation/integrations/app-protect-waf/configuration.md @@ -1,10 +1,8 @@ --- -docs: DOCS-578 -doctypes: -- '' title: Configuration toc: true weight: 200 +docs: DOCS-578 --- This document explains how to use F5 NGINX Ingress Controller to configure NGINX App Protect WAF. @@ -113,7 +111,11 @@ To add the [log configurations](/nginx-app-protect-waf/v4/logging-overview/secur 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. +{{< 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. + +{{< /note >}} 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: @@ -150,16 +152,26 @@ spec: 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 >}} + +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 "installation/integrations/app-protect-waf/troubleshooting-app-protect-waf.md#nginx-fails-to-start-or-reload" >}}) for more information. +`APUserSig` resources increase the reload time of NGINX Plus compared with `APPolicy` and `APLogConf` resources. Read [NGINX fails to start or reload]({{< relref "installation/integrations/app-protect-waf/troubleshoot-app-protect-waf.md#nginx-fails-to-start-or-reload" >}}) for more information. + +{{< /note >}} 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. - > **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 User-Defined signature. There is no need to reference the user defined signature resource in the Policy or Ingress resources. +{{< 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 User-Defined signature. There is no need to reference the user defined signature resource in the Policy or Ingress resources. + +{{< /note >}} For example, say you want to create the following user defined signature: diff --git a/docs/content/installation/integrations/app-protect-waf/installation.md b/docs/content/installation/integrations/app-protect-waf/installation.md index 0b77ed2754..453e5917cf 100644 --- a/docs/content/installation/integrations/app-protect-waf/installation.md +++ b/docs/content/installation/integrations/app-protect-waf/installation.md @@ -62,7 +62,7 @@ Follow these steps to build the NGINX Controller Image with NGINX App Protect WA make debian-image-dos-plus PREFIX=/nginx-plus-ingress TARGET=download ``` - **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}). This version number is used for tracking and deployment purposes. + **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_]({{< relref "installation/build-nginx-ingress-controller.md#makefile-details" >}}). This version number is used for tracking and deployment purposes. {{}} In the event a patch of NGINX Plus is released, make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--pull --no-cache"` to the make command. {{}} @@ -79,7 +79,7 @@ Follow these steps to build the NGINX Controller Image with NGINX App Protect WA
-{{}} For the complete list of _Makefile_ targets and customizable variables, see the [Building NGINX Ingress Controller]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}) guide. {{}} +{{< see-also >}} For the complete list of _Makefile_ targets and customizable variables, see the [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md#makefile-details" >}}) topic. {{}} --- @@ -217,5 +217,5 @@ For more information, see the [Configuration guide]({{< relref "installation/int If you prefer not to build your own NGINX Ingress Controller image, you can use pre-built images. Here are your options: -- Download the image using your NGINX Ingress Controller subscription certificate and key. See the [Getting the F5 Registry NGINX Ingress Controller Image]({{< relref "installation/nic-images/pulling-ingress-controller-image.md" >}}) guide. -- Use your NGINX Ingress Controller subscription JWT token to get the image: Instructions are in [Getting the NGINX Ingress Controller Image with JWT]({{< relref "installation/nic-images/using-the-jwt-token-docker-secret.md" >}}). +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< relref "installation/nic-images/get-registry-image.md" >}}) topic. +- The [Get the NGINX Ingress Controller image with JWT]({{< relref "installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. diff --git a/docs/content/installation/integrations/app-protect-waf/troubleshooting-app-protect-waf.md b/docs/content/installation/integrations/app-protect-waf/troubleshoot-app-protect-waf.md similarity index 98% rename from docs/content/installation/integrations/app-protect-waf/troubleshooting-app-protect-waf.md rename to docs/content/installation/integrations/app-protect-waf/troubleshoot-app-protect-waf.md index f005c9ebf0..9e89c71f1f 100644 --- a/docs/content/installation/integrations/app-protect-waf/troubleshooting-app-protect-waf.md +++ b/docs/content/installation/integrations/app-protect-waf/troubleshoot-app-protect-waf.md @@ -1,15 +1,13 @@ --- -docs: DOCS-0000 -doctypes: -- '' -title: Troubleshooting NGINX App Protect WAF +title: Troubleshoot NGINX App Protect WAF toc: true weight: 300 +docs: DOCS-0000 --- This document describes how to troubleshoot problems when using NGINX Ingress Controller and the NGINX App Protect WAF module version 5. -For general troubleshooting of NGINX Ingress Controller, check the general [troubleshooting]({{< relref "troubleshooting/troubleshoot-common" >}}) documentation. +For general troubleshooting of NGINX Ingress Controller, check the general [troubleshooting]({{< relref "troubleshooting/troubleshoot-common.md" >}}) documentation. {{< see-also >}} You can find more troubleshooting tips in the NGINX App Protect WAF [troubleshooting guide](/nginx-app-protect/v5/troubleshooting/) {{< /see-also >}}. diff --git a/docs/content/installation/integrations/f5-ingresslink.md b/docs/content/installation/integrations/f5-ingresslink.md index dec6e79ec5..0a068ec0e8 100644 --- a/docs/content/installation/integrations/f5-ingresslink.md +++ b/docs/content/installation/integrations/f5-ingresslink.md @@ -7,9 +7,9 @@ toc: true weight: 400 --- -Learn how to use NGINX Ingress Controller with F5 IngressLink to configure your F5 BIG-IP device. +Learn how to use F5 IngressLink with NGINX Ingress Controller to configure your F5 BIG-IP device. -F5 IngressLink is the integration between NGINX Ingress Controller and [F5 BIG-IP Container Ingress Services](https://clouddocs.f5.com/containers/latest/) (CIS) that configures an F5 BIG-IP device as a load balancer for NGINX Ingress Controller pods. +F5 IngressLink is an integration between NGINX Ingress Controller and [F5 BIG-IP Container Ingress Services](https://clouddocs.f5.com/containers/latest/) (CIS) that configures an F5 BIG-IP device as a load balancer for NGINX Ingress Controller pods. ## Install NGINX Ingress Controller with the integration enabled diff --git a/docs/content/installation/integrations/opentracing.md b/docs/content/installation/integrations/opentracing.md index 2d10ff1fdf..3310813806 100644 --- a/docs/content/installation/integrations/opentracing.md +++ b/docs/content/installation/integrations/opentracing.md @@ -7,16 +7,16 @@ toc: true weight: 500 --- -Learn how to use OpenTracing with NGINX Ingress Controller. +Learn how to use OpenTracing with F5 NGINX Ingress Controller. NGINX Ingress Controller supports [OpenTracing](https://opentracing.io/) with the third-party module [opentracing-contrib/nginx-opentracing](https://github.com/opentracing-contrib/nginx-opentracing). ## Prerequisites -1. Use an Ingress Controller image that contains OpenTracing. +1. Use a NGINX Ingress Controller image that contains OpenTracing. - You can find the images that include OpenTracing listed [in the technical specs doc]({{< relref "technical-specifications.md#supported-docker-images" >}}). - - Alternatively, you can [build your own image]({{< relref "installation/building-nginx-ingress-controller.md" >}}) using `debian-image` (or `alpine-image`) for NGINX or `debian-image-plus` (or `alpine-image-plus`) for NGINX Plus. + - Alternatively, you follow [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md" >}}) using `debian-image` (or `alpine-image`) for NGINX or `debian-image-plus` (or `alpine-image-plus`) for NGINX Plus. - [Jaeger](https://github.com/jaegertracing/jaeger-client-cpp), [Zipkin](https://github.com/rnburn/zipkin-cpp-opentracing) and [Datadog](https://github.com/DataDog/dd-opentracing-cpp/) tracers are installed by default. 1. Enable snippets annotations by setting the [`enable-snippets`]({{< relref "configuration/global-configuration/command-line-arguments#cmdoption-enable-snippets" >}}) command-line argument to true. diff --git a/docs/content/installation/nic-images/_index.md b/docs/content/installation/nic-images/_index.md index 1d740ffaaa..41ac35081f 100644 --- a/docs/content/installation/nic-images/_index.md +++ b/docs/content/installation/nic-images/_index.md @@ -1,5 +1,5 @@ --- -title: NGINX Ingress Controller Images +title: NGINX Ingress Controller images description: weight: 300 --- diff --git a/docs/content/installation/nic-images/using-the-jwt-token-docker-secret.md b/docs/content/installation/nic-images/get-image-using-jwt.md similarity index 91% rename from docs/content/installation/nic-images/using-the-jwt-token-docker-secret.md rename to docs/content/installation/nic-images/get-image-using-jwt.md index f328a568f0..5475a94d5c 100644 --- a/docs/content/installation/nic-images/using-the-jwt-token-docker-secret.md +++ b/docs/content/installation/nic-images/get-image-using-jwt.md @@ -2,29 +2,34 @@ docs: DOCS-1454 doctypes: - '' -title: Getting the NGINX Ingress Controller Image with JWT +title: Get the NGINX Ingress Controller image with JWT toc: true weight: 150 --- -Follow the steps in this document to pull the NGINX Plus Ingress Controller image from the F5 Docker registry into your Kubernetes cluster using your JWT token. +This document describes how to pull the F5 NGINX Plus Ingress Controller image from the F5 Docker registry into your Kubernetes cluster using your JWT token. ## Overview -{{}} +{{< important >}} + An NGINX Plus subscription certificate and key will not work with the F5 Docker registry. For NGINX Ingress Controller, you must have an NGINX Ingress Controller subscription -- download the NGINX Plus Ingress Controller (per instance) JWT access token from [MyF5](https://my.f5.com). -To list the available image tags using the Docker registry API, you will also need to download the NGINX Plus Ingress Controller (per instance) certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) from [MyF5](https://my.f5.com).{{}} +To list the available image tags using the Docker registry API, you will also need to download the NGINX Plus Ingress Controller (per instance) certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) from [MyF5](https://my.f5.com). + +{{< /important >}} {{< note >}} + You can also get the image using alternative methods: -* You can use Docker to pull an NGINX Ingress Controller image with NGINX Plus and push it to your private registry by following the ["Pulling the Ingress Controller Image"]({{< relref "installation/nic-images/pulling-ingress-controller-image" >}}) documentation. -* You can build an NGINX Ingress Controller image by following the ["Information on how to build an Ingress Controller image"]({{< relref "installation/building-nginx-ingress-controller" >}}) documentation. +* You can use Docker to pull an NGINX Ingress Controller image with NGINX Plus and push it to your private registry by following the [Get NGINX Ingress Controller from the F5 Registry]({{< relref "installation/nic-images/get-registry-image.md" >}}) topic. +* You can follow the [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md" >}}) topic. + +If you would like to use an NGINX Ingress Controller image with NGINX open source, we provide the image through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). -If you would like to use an NGINX Ingress Controller image using NGINX open source, we provide the image through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). {{< /note >}} ## Before You Begin diff --git a/docs/content/installation/nic-images/pulling-ingress-controller-image.md b/docs/content/installation/nic-images/get-registry-image.md similarity index 91% rename from docs/content/installation/nic-images/pulling-ingress-controller-image.md rename to docs/content/installation/nic-images/get-registry-image.md index 3a1cedb5d5..b76393f8ef 100644 --- a/docs/content/installation/nic-images/pulling-ingress-controller-image.md +++ b/docs/content/installation/nic-images/get-registry-image.md @@ -2,12 +2,14 @@ docs: DOCS-605 doctypes: - install -title: Getting the F5 Registry NGINX Ingress Controller Image +title: Get NGINX Ingress Controller from the F5 Registry toc: true weight: 100 --- -Learn how to pull an F5 NGINX Plus Ingress Controller image, including those with NGINX App Protect WAF and NGINX App Protect DoS, from the official F5 Docker registry and upload it to your private registry. +Learn how to pull an F5 NGINX Plus Ingress Controller image from the official F5 Docker registry and upload it to your private registry. + +The F5 Registry images include versions with NGINX App Protect WAF and NGINX App Protect DoS. This guide covers the prerequisites, image tagging, and troubleshooting steps. @@ -195,6 +197,6 @@ If you encounter issues while following this guide, here are solutions to common You can also get the NGINX Ingress Controller image using the following alternate methods: -- [Install using a JWT token in a Docker Config Secret]({{< relref "using-the-jwt-token-docker-secret" >}}). -- [Build the Ingress Controller image]({{< relref "building-nginx-ingress-controller" >}}) using the source code from the GitHub repository and your NGINX Plus subscription certificate and key. -- For NGINX Ingress Controller based on NGINX OSS, you can pull the [nginx/nginx-ingress image](https://hub.docker.com/r/nginx/nginx-ingress/) from DockerHub. +- [Get the NGINX Ingress Controller image with JWT]({{< relref "get-image-using-jwt.md" >}}). +- [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md" >}}) using the source code from the GitHub repository and your NGINX Plus subscription certificate and key. +- For NGINX Ingress Controller using NGINX OSS, you can pull the [nginx/nginx-ingress image](https://hub.docker.com/r/nginx/nginx-ingress/) from DockerHub. diff --git a/docs/content/installation/nic-images/using-aws-marketplace-image.md b/docs/content/installation/nic-images/use-aws-image.md similarity index 98% rename from docs/content/installation/nic-images/using-aws-marketplace-image.md rename to docs/content/installation/nic-images/use-aws-image.md index 40f64af7c8..2ae9ffac56 100644 --- a/docs/content/installation/nic-images/using-aws-marketplace-image.md +++ b/docs/content/installation/nic-images/use-aws-image.md @@ -2,7 +2,7 @@ docs: DOCS-607 doctypes: - '' -title: Using the AWS Marketplace NGINX Ingress Controller Image +title: Use the AWS Marketplace NGINX Ingress Controller image toc: true weight: 200 --- diff --git a/docs/content/installation/nic-images/using-gcp-marketplace-package.md b/docs/content/installation/nic-images/use-gcp-image.md similarity index 98% rename from docs/content/installation/nic-images/using-gcp-marketplace-package.md rename to docs/content/installation/nic-images/use-gcp-image.md index ff362c1c58..7b6f9c27b1 100644 --- a/docs/content/installation/nic-images/using-gcp-marketplace-package.md +++ b/docs/content/installation/nic-images/use-gcp-image.md @@ -2,7 +2,7 @@ docs: DOCS-1455 doctypes: - '' -title: Using the GCP Marketplace NGINX Ingress Controller Image +title: Use the GCP Marketplace NGINX Ingress Controller image toc: true weight: 300 --- diff --git a/docs/content/installation/running-multiple-ingress-controllers.md b/docs/content/installation/run-multiple-ingress-controllers.md similarity index 74% rename from docs/content/installation/running-multiple-ingress-controllers.md rename to docs/content/installation/run-multiple-ingress-controllers.md index 6198ee64f9..96f3465f3a 100644 --- a/docs/content/installation/running-multiple-ingress-controllers.md +++ b/docs/content/installation/run-multiple-ingress-controllers.md @@ -2,24 +2,27 @@ docs: DOCS-606 doctypes: - '' -title: Running Multiple NGINX Ingress Controllers +title: Run multiple NGINX Ingress Controllers toc: true weight: 400 --- -This document describes how to run multiple NGINX Ingress Controllers. +This document describes how to run multiple F5 NGINX Ingress Controller instances. It explains the following topics: - Ingress class concept. -- How to run NGINX Ingress Controller in the same cluster with another Ingress Controller, such as an Ingress Controller for a cloud HTTP load balancer, and prevent any conflicts between the Ingress Controllers. +- How to run NGINX Ingress Controller in the same cluster with another Ingress Controller and prevent conflicts between them. - How to run multiple NGINX Ingress Controllers. -{{< note >}}In this document we refer to the [Ingress]({{< relref "/configuration/ingress-resources/basic-configuration.md" >}}), [VirtualServer]({{< relref "/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-specification" >}}), [VirtualServerRoute]({{< relref "/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserverroute-specification" >}}), and [TransportServer]({{< relref "/configuration/transportserver-resource.md" >}}) resources as "configuration resources".{{< /note >}} +{{< note >}} This document refers to [Ingress]({{< relref "/configuration/ingress-resources/basic-configuration.md" >}}), [VirtualServer]({{< relref "/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-specification" >}}), [VirtualServerRoute]({{< relref "/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserverroute-specification" >}}), and [TransportServer]({{< relref "/configuration/transportserver-resource.md" >}}) resources as "configuration resources".{{< /note >}} + +--- ## Ingress class -Thanks to the Ingress class concept, multiple Ingress Controllers can coexist in one cluster. The Ingress class has the following characteristics: +The [IngressClass](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class) resource allows for multiple Ingress Controller to operate in the same cluster. It also allow developers to select which Ingress Controller implementation to use for their Ingress resource. +The IngressClass has the following characteristics: - Every Ingress Controller must only handle Ingress resources for its particular class. - Ingress resources need to have the `ingressClassName` field set to the value of the class of the Ingress Controller the user wants to use. @@ -32,13 +35,17 @@ The default Ingress class of NGINX Ingress Controller is `nginx`, which means th {{< note >}}- If the class of an Ingress resource is not set, Kubernetes will set it to the class of the default Ingress Controller. To make the Ingress Controller the default one, the `ingressclass.kubernetes.io/is-default-class` property must be set on the IngressClass resource. To learn more, see Step 3 *Create an IngressClass resource* of the [Create Common Resources]({{< relref "installation/installing-nic/installation-with-manifests.md#create-common-resources" >}}) section. - For VirtualServer, VirtualServerRoute, Policy and TransportServer resources, NGINX Ingress Controller will always handle resources with an empty class.{{< /note >}} -## Running NGINX Ingress Controller and another Ingress Controller +--- + +## Run NGINX Ingress Controller and another Ingress Controller It is possible to run NGINX Ingress Controller and an Ingress Controller for another load balancer in the same cluster. This is often the case if you create your cluster through a cloud provider's managed Kubernetes service that by default might include the Ingress Controller for the HTTP load balancer of the cloud provider, and you want to use NGINX Ingress Controller. -To make sure that NGINX Ingress Controller handles specific configuration resources, update those resources with the class set to `nginx` (or the Ingress class value that you configured in NGINX Ingress Controller). +To make sure that NGINX Ingress Controller handles specific configuration resources, update those resources with the class set to the value that is configured in NGINX Ingress Controller. By default, this is `nginx`. + +--- -## Running multiple NGINX Ingress Controllers +## Run multiple NGINX Ingress Controllers When running NGINX Ingress Controller, you have the following options with regards to which configuration resources it handles: diff --git a/docs/content/logging-and-monitoring/prometheus.md b/docs/content/logging-and-monitoring/prometheus.md index 7f8708f98d..ef512d7d98 100644 --- a/docs/content/logging-and-monitoring/prometheus.md +++ b/docs/content/logging-and-monitoring/prometheus.md @@ -34,7 +34,7 @@ If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the ### Using Helm -If you're using *Helm* to install the Ingress Controller, to enable Prometheus metrics, configure the `prometheus.*` parameters of the Helm chart. See the [Installation with Helm]({{< relref "/installation/installing-nic/installation-with-helm.md" >}}) doc. +If you're using *Helm* to install the Ingress Controller, to enable Prometheus metrics, configure the `prometheus.*` parameters of the Helm chart. See the [Installation with Helm]({{< relref "installation/installing-nic/installation-with-helm.md">}}) doc. ### Using ServiceMonitor diff --git a/docs/content/overview/about.md b/docs/content/overview/about.md index 51415a7a82..c10f45d0f3 100644 --- a/docs/content/overview/about.md +++ b/docs/content/overview/about.md @@ -10,6 +10,8 @@ This document describes the F5 NGINX Ingress Controller, an Ingress Controller i --- +--- + NGINX Ingress Controller is an [Ingress Controller]({{< relref "glossary.md#ingress-controller">}}) implementation for NGINX and NGINX Plus that can load balance Websocket, gRPC, TCP and UDP applications. It supports standard [Ingress]({{< relref "glossary.md#ingress">}}) features such as content-based routing and TLS/SSL termination. Several NGINX and NGINX Plus features are available as extensions to Ingress resources through [Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations">}}) and the [ConfigMap]({{< relref "configuration/global-configuration/configmap-resource">}}) resource. NGINX Ingress Controller supports the [VirtualServer and VirtualServerRoute resources]({{< relref "configuration/virtualserver-and-virtualserverroute-resources">}}) as alternatives to Ingress, enabling traffic splitting and advanced content-based routing. It also supports TCP, UDP and TLS Passthrough load balancing using [TransportServer resources]({{< relref "configuration/transportserver-resource">}}). diff --git a/docs/content/technical-specifications.md b/docs/content/technical-specifications.md index 301da66dae..45403f412c 100644 --- a/docs/content/technical-specifications.md +++ b/docs/content/technical-specifications.md @@ -67,7 +67,7 @@ _NGINX Plus images include NGINX Plus R32._ #### **F5 Container registry** -NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com`, explained in the [Get the NGINX Ingress Controller image with JWT]({{}}) and [Get the F5 Registry NGINX Ingress Controller image]({{}}) topics. +NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com`, explained in the [Get the NGINX Ingress Controller image with JWT]({{}}) and [Get the F5 Registry NGINX Ingress Controller image]({{}}) topics. {{< bootstrap-table "table table-striped table-bordered table-responsive" >}} |
Name
|
Base image
|
Third-party modules
| F5 Container Registry Image | Architectures | @@ -94,7 +94,7 @@ NGINX Plus images are available through the F5 Container registry `private-regis NGINX Plus images are available through the AWS Marketplace. -View the [Use the AWS Marketplace Ingress Controller image]({{< relref "/installation/nic-images/using-aws-marketplace-image.md" >}}) topic for details on how to set up the required IAM resources in your EKS cluster. +View the [Use the AWS Marketplace Ingress Controller image]({{< relref "/installation/nic-images/use-aws-image.md" >}}) topic for details on how to set up the required IAM resources in your EKS cluster. {{< bootstrap-table "table table-striped table-bordered table-responsive" >}} |
Name
|
Base image
|
Third-party modules
| AWS Marketplace Link | Architectures | @@ -110,7 +110,7 @@ View the [Use the AWS Marketplace Ingress Controller image]({{< relref "/install #### **Google Cloud Marketplace** NGINX Plus images are available through the Google Cloud Marketplace. -View the [Use the GCP Marketplace NGINX Ingress Controller image]({{< relref "/installation/nic-images/using-gcp-marketplace-package.md" >}}) topic for details on how to use them. +View the [Use the GCP Marketplace NGINX Ingress Controller image]({{< relref "/installation/nic-images/use-gcp-image.md" >}}) topic for details on how to use them. {{< bootstrap-table "table table-striped table-bordered table-responsive" >}} |
Name
|
Base image
|
Third-party modules
| GCP Marketplace Link | Architectures | diff --git a/docs/content/tutorials/oidc-custom-configuration.md b/docs/content/tutorials/oidc-custom-configuration.md index 70b1eabd28..975279162d 100644 --- a/docs/content/tutorials/oidc-custom-configuration.md +++ b/docs/content/tutorials/oidc-custom-configuration.md @@ -92,9 +92,15 @@ data: # Rest of configuration file truncated ``` -> **IMPORTANT** -> -> In Step 3 an NGINX Ingress Controller will be deployed/updated that will use this ConfigMap. Any changes made to this ConfigMap must be made **before** deploying/updating NGINX Ingress Controller. If an update is applied to the ConfigMap after NGINX Ingress Controller is deployed, it will not get applied. Applying any updates to the data in this ConfigMap will require NGINX Ingress Controller to be re-deployed. +{{< important >}} + +In the next step, NGINX Ingress Controller will be deployed using this ConfigMap. + +Any changes made to this ConfigMap must be made **before** deploying or updating NGINX Ingress Controller. If an update is applied to the ConfigMap after NGINX Ingress Controller is deployed, it will not be applied. + +Applying any updates to the data in this ConfigMap will require NGINX Ingress Controller to be re-deployed. + +{{< /important >}} ## Step 3 - Add Volume and VolumeMount to the Ingress Controller deployment diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index ab1934ec2b..e5eb76c3d9 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -277,6 +277,7 @@ Skip TLS verification for the NGINX Management Suite server. --- + ### -min-update-interval `` The minimum interval between updates to the NGINX Management Suite.