diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 34965011fc..d885de29e4 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -89,6 +89,6 @@ template: | ## Resources - Documentation -- https://docs.nginx.com/nginx-ingress-controller/ - - Configuration examples -- https://github.com/nginxinc/kubernetes-ingress/tree/v$RESOLVED_VERSION/examples and https://github.com/nginxinc/kubernetes-ingress/tree/v$RESOLVED_VERSION/examples-of-custom-resources + - Configuration examples -- https://github.com/nginxinc/kubernetes-ingress/tree/v$RESOLVED_VERSION/examples - Helm Chart -- https://github.com/nginxinc/kubernetes-ingress/tree/v$RESOLVED_VERSION/deployments/helm-chart - Operator -- https://github.com/nginxinc/nginx-ingress-operator/ diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a29b691311..ef68900038 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,7 +7,6 @@ on: paths-ignore: - 'docs/**' - 'examples/**' - - 'examples-of-custom-resources/**' - '**.md' tags: - 'v[0-9]+.[0-9]+.[0-9]+' @@ -17,7 +16,6 @@ on: paths-ignore: - 'docs/**' - 'examples/**' - - 'examples-of-custom-resources/**' - '**.md' types: - opened diff --git a/.github/workflows/fossa.yml b/.github/workflows/fossa.yml index 1502d406ac..8064d4d3e1 100644 --- a/.github/workflows/fossa.yml +++ b/.github/workflows/fossa.yml @@ -7,7 +7,6 @@ on: paths-ignore: - 'docs/**' - 'examples/**' - - 'examples-of-custom-resources/**' - '**.md' jobs: diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index ed66bba4ad..7f94998fe6 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -7,7 +7,6 @@ on: paths-ignore: - 'docs/**' - 'examples/**' - - 'examples-of-custom-resources/**' - '**.md' types: - opened diff --git a/README.md b/README.md index 5678a40a0d..fdbd95cea4 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ Read [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-plus 1. Install the NGINX Ingress controller using the Kubernetes [manifests](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) or the [helm chart](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/). 1. Configure load balancing for a simple web application: * Use the Ingress resource. See the [Cafe example](examples/complete-example). - * Or the VirtualServer resource. See the [Basic configuration](examples-of-custom-resources/basic-configuration) example. + * Or the VirtualServer resource. See the [Basic configuration](examples/custom-resources/basic-configuration) example. 1. See additional configuration [examples](examples). 1. Learn more about all available configuration and customization in the [docs](https://docs.nginx.com/nginx-ingress-controller/). diff --git a/docs/content/configuration/configuration-examples.md b/docs/content/configuration/configuration-examples.md index 14559b484d..1d3ab0fe17 100644 --- a/docs/content/configuration/configuration-examples.md +++ b/docs/content/configuration/configuration-examples.md @@ -1,7 +1,7 @@ --- title: Configuration Examples -description: +description: weight: 2000 doctypes: [""] toc: true @@ -10,4 +10,4 @@ toc: true Our [GitHub repo](https://github.com/nginxinc/kubernetes-ingress) includes a number of configuration examples: * [*Examples*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples) show how to use advanced NGINX features in Ingress resources with annotations. -* [*Examples of Custom Resources*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples-of-custom-resources) show how to use VirtualServer and VirtualServerResources for a few use cases. +* [*Examples of Custom Resources*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/custom-resources) show how to use VirtualServer and VirtualServerResources for a few use cases. diff --git a/docs/content/configuration/handling-host-and-listener-collisions.md b/docs/content/configuration/handling-host-and-listener-collisions.md index 220e893e1b..e0176db86f 100644 --- a/docs/content/configuration/handling-host-and-listener-collisions.md +++ b/docs/content/configuration/handling-host-and-listener-collisions.md @@ -79,7 +79,7 @@ Similarly, if `cafe-ingress` was created first, it will win `cafe.example.com` a It is possible to merge configuration for multiple Ingress resources for the same host. One common use case for this approach is distributing resources across multiple namespaces. See the [Cross-namespace Configuration](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration/) doc for more information. -It is *not* possible to merge the configurations for multiple VirtualServer resources for the same host. However, you can split the VirtualServers into multiple VirtualServerRoute resources, which a single VirtualServer can then reference. See the [corresponding example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples-of-custom-resources/cross-namespace-configuration) on GitHub. +It is *not* possible to merge the configurations for multiple VirtualServer resources for the same host. However, you can split the VirtualServers into multiple VirtualServerRoute resources, which a single VirtualServer can then reference. See the [corresponding example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/custom-resources/cross-namespace-configuration) on GitHub. It is *not* possible to merge configuration for multiple TransportServer resources. diff --git a/docs/content/configuration/ingress-resources/cross-namespace-configuration.md b/docs/content/configuration/ingress-resources/cross-namespace-configuration.md index b25d9698ad..9585973870 100644 --- a/docs/content/configuration/ingress-resources/cross-namespace-configuration.md +++ b/docs/content/configuration/ingress-resources/cross-namespace-configuration.md @@ -1,7 +1,7 @@ --- title: Cross-namespace Configuration -description: +description: weight: 2000 doctypes: [""] toc: true @@ -10,4 +10,4 @@ toc: true You can spread the Ingress configuration for a common host across multiple Ingress resources using Mergeable Ingress resources. Such resources can belong to the *same* or *different* namespaces. This enables easier management when using a large number of paths. See the [Mergeable Ingress Resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/mergeable-ingress-types) example on our GitHub. -As an alternative to Mergeable Ingress resources, you can use [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) for cross-namespace configuration. See the [Cross-Namespace Configuration](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples-of-custom-resources/cross-namespace-configuration) example on our GitHub. +As an alternative to Mergeable Ingress resources, you can use [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) for cross-namespace configuration. See the [Cross-Namespace Configuration](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/custom-resources/cross-namespace-configuration) example on our GitHub. diff --git a/docs/content/configuration/policy-resource.md b/docs/content/configuration/policy-resource.md index d0b788c3e4..650a1f0a23 100644 --- a/docs/content/configuration/policy-resource.md +++ b/docs/content/configuration/policy-resource.md @@ -1,7 +1,7 @@ --- title: Policy Resource -description: +description: weight: 1800 doctypes: [""] toc: true @@ -12,7 +12,7 @@ The Policy resource allows you to configure features like access control and rat The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -This document is the reference documentation for the Policy resource. An example of a Policy for access control is available in our [GitHub repo](https://github.com/nginxinc/kubernetes-ingress/blob/v2.0.3/examples-of-custom-resources/access-control). +This document is the reference documentation for the Policy resource. An example of a Policy for access control is available in our [GitHub repo](https://github.com/nginxinc/kubernetes-ingress/blob/v2.0.3/examples/custom-resources/access-control). ## Prerequisites @@ -32,17 +32,17 @@ spec: - 10.0.0.0/8 ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | |``accessControl`` | The access control policy based on the client IP address. | [accessControl](#accesscontrol) | No | |``ingressClassName`` | Specifies which Ingress Controller must handle the Policy resource. | ``string`` | No | -|``rateLimit`` | The rate limit policy controls the rate of processing requests per a defined key. | [rateLimit](#ratelimit) | No | -|``jwt`` | The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens. | [jwt](#jwt) | No | -|``ingressMTLS`` | The IngressMTLS policy configures client certificate verification. | [ingressMTLS](#ingressmtls) | No | -|``egressMTLS`` | The EgressMTLS policy configures upstreams authentication and certificate verification. | [egressMTLS](#egressmtls) | No | +|``rateLimit`` | The rate limit policy controls the rate of processing requests per a defined key. | [rateLimit](#ratelimit) | No | +|``jwt`` | The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens. | [jwt](#jwt) | No | +|``ingressMTLS`` | The IngressMTLS policy configures client certificate verification. | [ingressMTLS](#ingressmtls) | No | +|``egressMTLS`` | The EgressMTLS policy configures upstreams authentication and certificate verification. | [egressMTLS](#egressmtls) | No | |``waf`` | The WAF policy configures WAF and log configuration policies for [NGINX AppProtect](/nginx-ingress-controller/app-protect/installation/) | [WAF](#waf) | No | -{{% /table %}} +{{% /table %}} \* A policy must include exactly one policy. @@ -66,12 +66,12 @@ accessControl: > Note: The feature is implemented using the NGINX [ngx_http_access_module](http://nginx.org/en/docs/http/ngx_http_access_module.html). The Ingress Controller access control policy supports either allow or deny rules, but not both (as the module does). -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``allow`` | Allows access for the specified networks or addresses. For example, ``192.168.1.1`` or ``10.1.1.0/16``. | ``[]string`` | No | -|``deny`` | Denies access for the specified networks or addresses. For example, ``192.168.1.1`` or ``10.1.1.0/16``. | ``[]string`` | No | \* an accessControl must include either `allow` or `deny`. | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``allow`` | Allows access for the specified networks or addresses. For example, ``192.168.1.1`` or ``10.1.1.0/16``. | ``[]string`` | No | +|``deny`` | Denies access for the specified networks or addresses. For example, ``192.168.1.1`` or ``10.1.1.0/16``. | ``[]string`` | No | \* an accessControl must include either `allow` or `deny`. | +{{% /table %}} #### AccessControl Merging Behavior @@ -107,19 +107,19 @@ rateLimit: > 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). -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``rate`` | The rate of requests permitted. The rate is specified in requests per second (r/s) or requests per minute (r/m). | ``string`` | Yes | -|``key`` | The key to which the rate limit is applied. Can contain text, variables, or a combination of them. Variables must be surrounded by ``${}``. For example: ``${binary_remote_addr}``. Accepted variables are ``$binary_remote_addr``, ``$request_uri``, ``$url``, ``$http_``, ``$args``, ``$arg_``, ``$cookie_``. | ``string`` | Yes | -|``zoneSize`` | Size of the shared memory zone. Only positive values are allowed. Allowed suffixes are ``k`` or ``m``, if none are present ``k`` is assumed. | ``string`` | Yes | -|``delay`` | The delay parameter specifies a limit at which excessive requests become delayed. If not set all excessive requests are delayed. | ``int`` | No | -|``noDelay`` | Disables the delaying of excessive requests while requests are being limited. Overrides ``delay`` if both are set. | ``bool`` | No | -|``burst`` | Excessive requests are delayed until their number exceeds the ``burst`` size, in which case the request is terminated with an error. | ``int`` | No | -|``dryRun`` | Enables the dry run mode. In this mode, the rate limit is not actually applied, but the the number of excessive requests is accounted as usual in the shared memory zone. | ``bool`` | No | -|``logLevel`` | Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Allowed values are ``info``, ``notice``, ``warn`` or ``error``. Default is ``error``. | ``string`` | No | -|``rejectCode`` | Sets the status code to return in response to rejected requests. Must fall into the range ``400..599``. Default is ``503``. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``rate`` | The rate of requests permitted. The rate is specified in requests per second (r/s) or requests per minute (r/m). | ``string`` | Yes | +|``key`` | The key to which the rate limit is applied. Can contain text, variables, or a combination of them. Variables must be surrounded by ``${}``. For example: ``${binary_remote_addr}``. Accepted variables are ``$binary_remote_addr``, ``$request_uri``, ``$url``, ``$http_``, ``$args``, ``$arg_``, ``$cookie_``. | ``string`` | Yes | +|``zoneSize`` | Size of the shared memory zone. Only positive values are allowed. Allowed suffixes are ``k`` or ``m``, if none are present ``k`` is assumed. | ``string`` | Yes | +|``delay`` | The delay parameter specifies a limit at which excessive requests become delayed. If not set all excessive requests are delayed. | ``int`` | No | +|``noDelay`` | Disables the delaying of excessive requests while requests are being limited. Overrides ``delay`` if both are set. | ``bool`` | No | +|``burst`` | Excessive requests are delayed until their number exceeds the ``burst`` size, in which case the request is terminated with an error. | ``int`` | No | +|``dryRun`` | Enables the dry run mode. In this mode, the rate limit is not actually applied, but the the number of excessive requests is accounted as usual in the shared memory zone. | ``bool`` | No | +|``logLevel`` | Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Allowed values are ``info``, ``notice``, ``warn`` or ``error``. Default is ``error``. | ``string`` | No | +|``rejectCode`` | Sets the status code to return in response to rejected requests. Must fall into the range ``400..599``. Default is ``503``. | ``string`` | No | +{{% /table %}} > For each policy referenced in a VirtualServer and/or its VirtualServerRoutes, the 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, the Ingress Controller will generate two different rate limiting zones, one zone per VirtualServer. @@ -168,13 +168,13 @@ The value of the `${jwt_claim_user}` variable is the `user` claim of a JWT. For > Note: The feature is implemented using the NGINX Plus [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``secret`` | The name of the Kubernetes secret that stores the JWK. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/jwk``, and the JWK must be stored in the secret under the key ``jwk``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | -|``realm`` | The realm of the JWT. | ``string`` | Yes | -|``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 %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``secret`` | The name of the Kubernetes secret that stores the JWK. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/jwk``, and the JWK must be stored in the secret under the key ``jwk``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | +|``realm`` | The realm of the JWT. | ``string`` | Yes | +|``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 %}} #### JWT Merging Behavior @@ -222,13 +222,13 @@ We use the `requestHeaders` of the [Action.Proxy](/nginx-ingress-controller/conf > Note: The feature is implemented using the NGINX [ngx_http_ssl_module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html). -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``clientCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | -|``verifyClient`` | Verification for the client. Possible values are ``"on"``, ``"off"``, ``"optional"``, ``"optional_no_ca"``. The default is ``"on"``. | ``string`` | No | -|``verifyDepth`` | Sets the verification depth in the client certificates chain. The default is ``1``. | ``int`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``clientCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | +|``verifyClient`` | Verification for the client. Possible values are ``"on"``, ``"off"``, ``"optional"``, ``"optional_no_ca"``. The default is ``"on"``. | ``string`` | No | +|``verifyDepth`` | Sets the verification depth in the client certificates chain. The default is ``1``. | ``int`` | No | +{{% /table %}} #### IngressMTLS Merging Behavior @@ -257,19 +257,19 @@ egressMTLS: > Note: The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html). -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``tlsSecret`` | The name of the Kubernetes secret that stores the TLS certificate and key. It must be in the same namespace as the Policy resource. The secret must be of the type ``kubernetes.io/tls``, the certificate must be stored in the secret under the key ``tls.crt``, and the key must be stored under the key ``tls.key``, otherwise the secret will be rejected as invalid. | ``string`` | No | -|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``, otherwise the secret will be rejected as invalid. | ``string`` | No | -|``verifyServer`` | Enables verification of the upstream HTTPS server certificate. | ``bool`` | No | -|``verifyDepth`` | Sets the verification depth in the proxied HTTPS server certificates chain. The default is ``1``. | ``int`` | No | -|``sessionReuse`` | Enables reuse of SSL sessions to the upstreams. The default is ``true``. | ``bool`` | No | -|``serverName`` | Enables passing of the server name through ``Server Name Indication`` extension. | ``bool`` | No | -|``sslName`` | Allows overriding the server name used to verify the certificate of the upstream HTTPS server. | ``string`` | No | -|``ciphers`` | Specifies the enabled ciphers for requests to an upstream HTTPS server. The default is ``DEFAULT``. | ``string`` | No | -|``protocols`` | Specifies the protocols for requests to an upstream HTTPS server. The default is ``TLSv1 TLSv1.1 TLSv1.2``. | ``string`` | No | > Note: the value of ``ciphers`` and ``protocols`` is not validated by the Ingress Controller. As a result, NGINX can fail to reload the configuration. To ensure that the configuration for a VirtualServer/VirtualServerRoute that references the policy was successfully applied, check its [status](/nginx-ingress-controller/configuration/global-configuration/reporting-resources-status/#virtualserver-and-virtualserverroute-resources). The validation will be added in the future releases. | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``tlsSecret`` | The name of the Kubernetes secret that stores the TLS certificate and key. It must be in the same namespace as the Policy resource. The secret must be of the type ``kubernetes.io/tls``, the certificate must be stored in the secret under the key ``tls.crt``, and the key must be stored under the key ``tls.key``, otherwise the secret will be rejected as invalid. | ``string`` | No | +|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``, otherwise the secret will be rejected as invalid. | ``string`` | No | +|``verifyServer`` | Enables verification of the upstream HTTPS server certificate. | ``bool`` | No | +|``verifyDepth`` | Sets the verification depth in the proxied HTTPS server certificates chain. The default is ``1``. | ``int`` | No | +|``sessionReuse`` | Enables reuse of SSL sessions to the upstreams. The default is ``true``. | ``bool`` | No | +|``serverName`` | Enables passing of the server name through ``Server Name Indication`` extension. | ``bool`` | No | +|``sslName`` | Allows overriding the server name used to verify the certificate of the upstream HTTPS server. | ``string`` | No | +|``ciphers`` | Specifies the enabled ciphers for requests to an upstream HTTPS server. The default is ``DEFAULT``. | ``string`` | No | +|``protocols`` | Specifies the protocols for requests to an upstream HTTPS server. The default is ``TLSv1 TLSv1.1 TLSv1.2``. | ``string`` | No | > Note: the value of ``ciphers`` and ``protocols`` is not validated by the Ingress Controller. As a result, NGINX can fail to reload the configuration. To ensure that the configuration for a VirtualServer/VirtualServerRoute that references the policy was successfully applied, check its [status](/nginx-ingress-controller/configuration/global-configuration/reporting-resources-status/#virtualserver-and-virtualserverroute-resources). The validation will be added in the future releases. | +{{% /table %}} #### EgressMTLS Merging Behavior @@ -304,7 +304,7 @@ NGINX Plus will pass the ID of an authenticated user to the backend in the HTTP #### Prerequisites -For the OIDC feature to work, it is necessary to enable [zone synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/), otherwise NGINX Plus will fail to reload. Additionally, it is necessary to configure a resolver, so that NGINX Plus can resolve the IDP authorization endpoint. For an example of the necessary configuration see the documentation [here](https://github.com/nginxinc/kubernetes-ingress/blob/v2.0.3/examples-of-custom-resources/oidc#step-7---configure-nginx-plus-zone-synchronization-and-resolver). +For the OIDC feature to work, it is necessary to enable [zone synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/), otherwise NGINX Plus will fail to reload. Additionally, it is necessary to configure a resolver, so that NGINX Plus can resolve the IDP authorization endpoint. For an example of the necessary configuration see the documentation [here](https://github.com/nginxinc/kubernetes-ingress/blob/v2.0.3/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. @@ -312,17 +312,17 @@ For the OIDC feature to work, it is necessary to enable [zone synchronization](h The OIDC policy defines a few internal locations that can't be customized: `/_jwks_uri`, `/_token`, `/_refresh`, `/_id_token_validation`, `/logout`, `/_logout`. In addition, as explained below `/_codexch` is the default value for redirect URI, but can be customized. Specifying one of these locations as a route in the VirtualServer or VirtualServerRoute will result in a collision and NGINX Plus will fail to reload. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``clientID`` | The client ID provided by your OpenID Connect provider. | ``string`` | Yes | -|``clientSecret`` | The name of the Kubernetes secret that stores the client secret provided by your OpenID Connect provider. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/oidc``, and the secret under the key ``client-secret``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | -|``authEndpoint`` | URL for the authorization endpoint provided by your OpenID Connect provider. | ``string`` | Yes | -|``tokenEndpoint`` | URL for the token endpoint provided by your OpenID Connect provider. | ``string`` | Yes | -|``jwksURI`` | URL for the JSON Web Key Set (JWK) document provided by your OpenID Connect provider. | ``string`` | Yes | -|``scope`` | List of OpenID Connect scopes. Possible values are ``openid``, ``profile``, ``email``, ``address` and ``phone``. The scope ``openid`` always needs to be present and others can be added concatenating them with a ``+`` sign, for example ``openid+profile+email``. The default is ``openid``. | ``string`` | No | -|``redirectURI`` | Allows overriding the default redirect URI. The default is ``/_codexch``. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``clientID`` | The client ID provided by your OpenID Connect provider. | ``string`` | Yes | +|``clientSecret`` | The name of the Kubernetes secret that stores the client secret provided by your OpenID Connect provider. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/oidc``, and the secret under the key ``client-secret``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | +|``authEndpoint`` | URL for the authorization endpoint provided by your OpenID Connect provider. | ``string`` | Yes | +|``tokenEndpoint`` | URL for the token endpoint provided by your OpenID Connect provider. | ``string`` | Yes | +|``jwksURI`` | URL for the JSON Web Key Set (JWK) document provided by your OpenID Connect provider. | ``string`` | Yes | +|``scope`` | List of OpenID Connect scopes. Possible values are ``openid``, ``profile``, ``email``, ``address` and ``phone``. The scope ``openid`` always needs to be present and others can be added concatenating them with a ``+`` sign, for example ``openid+profile+email``. The default is ``openid``. | ``string`` | No | +|``redirectURI`` | Allows overriding the default redirect URI. The default is ``/_codexch``. | ``string`` | 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. @@ -376,15 +376,15 @@ waf: > Note: The feature is implemented using the NGINX Plus [NGINX App Protect Module](https://docs.nginx.com/nginx-app-protect/configuration/). -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``enable`` | Enables NGINX App Protect. | ``bool`` | Yes | -|``apPolicy`` | The [App Protect policy](/nginx-ingress-controller/app-protect/configuration/#app-protect-policies) of the WAF. Accepts an optional namespace. | ``string`` | No | -|``securityLog.enable`` | Enables security log. | ``bool`` | No | -|``securityLog.apLogConf`` | The [App Protect log conf](/nginx-ingress-controller/app-protect/configuration/#app-protect-logs) resource. Accepts an optional namespace. | ``string`` | No | -|``securityLog.logDest`` | The log destination for the security log. Accepted variables are ``syslog:server=:``, ``stderr``, ````. Default is ``"syslog:server=127.0.0.1:514"``. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables NGINX App Protect. | ``bool`` | Yes | +|``apPolicy`` | The [App Protect policy](/nginx-ingress-controller/app-protect/configuration/#app-protect-policies) of the WAF. Accepts an optional namespace. | ``string`` | No | +|``securityLog.enable`` | Enables security log. | ``bool`` | No | +|``securityLog.apLogConf`` | The [App Protect log conf](/nginx-ingress-controller/app-protect/configuration/#app-protect-logs) resource. Accepts an optional namespace. | ``string`` | No | +|``securityLog.logDest`` | The log destination for the security log. Accepted variables are ``syslog:server=:``, ``stderr``, ````. Default is ``"syslog:server=127.0.0.1:514"``. | ``string`` | No | +{{% /table %}} #### WAF Merging Behavior diff --git a/docs/content/configuration/transportserver-resource.md b/docs/content/configuration/transportserver-resource.md index a3e201279c..8a797c5bcb 100644 --- a/docs/content/configuration/transportserver-resource.md +++ b/docs/content/configuration/transportserver-resource.md @@ -9,7 +9,7 @@ toc: true The TransportServer resource allows you to configure TCP, UDP, and TLS Passthrough load balancing. The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -This document is the reference documentation for the TransportServer resource. To see additional examples of using the resource for specific use cases, go to the [examples-of-custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples-of-custom-resources) folder in our GitHub repo. +This document is the reference documentation for the TransportServer resource. To see additional examples of using the resource for specific use cases, go to the [examples/custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/custom-resources) folder in our GitHub repo. > **Feature Status**: The TransportServer resource is available as a preview feature[^1]: We might introduce some backward-incompatible changes to the resource definition. The feature is disabled by default. To enable it, set the [enable-preview-policies](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-enable-preview-policies) command-line argument of the Ingress Controller. diff --git a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md index bd072d43f5..756f40fdd9 100644 --- a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md @@ -1,6 +1,6 @@ --- title: VirtualServer and VirtualServerRoute Resources -description: +description: weight: 1600 doctypes: [""] aliases: @@ -11,7 +11,7 @@ toc: true The VirtualServer and VirtualServerRoute resources are new load balancing configuration, introduced in release 1.5 as an alternative to the Ingress resource. The resources enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. The resources are implemented as [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -This document is the reference documentation for the resources. To see additional examples of using the resources for specific use cases, go to the [examples-of-custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples-of-custom-resources) folder in our GitHub repo. +This document is the reference documentation for the resources. To see additional examples of using the resources for specific use cases, go to the [examples/custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/custom-resources) folder in our GitHub repo. ## VirtualServer Specification @@ -47,18 +47,18 @@ spec: pass: tea ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. Wildcard domains like ``*.example.com`` are not allowed. The ``host`` value needs to be unique among all Ingress and VirtualServer resources. See also [Handling Host and Listener Collisions](/nginx-ingress-controller/configuration/handling-host-and-listener-collisions). | ``string`` | Yes | -|``tls`` | The TLS termination configuration. | [tls](#virtualservertls) | No | -|``policies`` | A list of policies. | [[]policy](#virtualserverpolicy) | No | -|``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | -|``routes`` | A list of routes. | [[]route](#virtualserver-route) | No | -|``ingressClassName`` | Specifies which Ingress controller must handle the VirtualServer resource. | ``string`` | No | -|``http-snippets`` | Sets a custom snippet in the http context. | ``string`` | No | -|``server-snippets`` | Sets a custom snippet in server context. Overrides the ``server-snippets`` ConfigMap key. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. Wildcard domains like ``*.example.com`` are not allowed. The ``host`` value needs to be unique among all Ingress and VirtualServer resources. See also [Handling Host and Listener Collisions](/nginx-ingress-controller/configuration/handling-host-and-listener-collisions). | ``string`` | Yes | +|``tls`` | The TLS termination configuration. | [tls](#virtualservertls) | No | +|``policies`` | A list of policies. | [[]policy](#virtualserverpolicy) | No | +|``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | +|``routes`` | A list of routes. | [[]route](#virtualserver-route) | No | +|``ingressClassName`` | Specifies which Ingress controller must handle the VirtualServer resource. | ``string`` | No | +|``http-snippets`` | Sets a custom snippet in the http context. | ``string`` | No | +|``server-snippets`` | Sets a custom snippet in server context. Overrides the ``server-snippets`` ConfigMap key. | ``string`` | No | +{{% /table %}} ### VirtualServer.TLS @@ -69,12 +69,12 @@ redirect: enable: true ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``secret`` | The name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the VirtualServer. The secret must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that contain the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the host of the VirtualServer. | ``string`` | No | -|``redirect`` | The redirect configuration of the TLS for a VirtualServer. | [tls.redirect](#virtualservertlsredirect) | No | ### VirtualServer.TLS.Redirect | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``secret`` | The name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the VirtualServer. The secret must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that contain the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the host of the VirtualServer. | ``string`` | No | +|``redirect`` | The redirect configuration of the TLS for a VirtualServer. | [tls.redirect](#virtualservertlsredirect) | No | ### VirtualServer.TLS.Redirect | +{{% /table %}} ### VirtualServer.TLS.Redirect @@ -85,13 +85,13 @@ code: 301 basedOn: scheme ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``enable`` | Enables a TLS redirect for a VirtualServer. The default is ``False``. | ``boolean`` | No | -|``code`` | The status code of a redirect. The allowed values are: ``301``\ , ``302``\ , ``307``\ , ``308``. The default is ``301``. | ``int`` | No | -|``basedOn`` | The attribute of a request that NGINX will evaluate to send a redirect. The allowed values are ``scheme`` (the scheme of the request) or ``x-forwarded-proto`` (the ``X-Forwarded-Proto`` header of the request). The default is ``scheme``. | ``string`` | No | ### VirtualServer.Policy | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables a TLS redirect for a VirtualServer. The default is ``False``. | ``boolean`` | No | +|``code`` | The status code of a redirect. The allowed values are: ``301``\ , ``302``\ , ``307``\ , ``308``. The default is ``301``. | ``int`` | No | +|``basedOn`` | The attribute of a request that NGINX will evaluate to send a redirect. The allowed values are ``scheme`` (the scheme of the request) or ``x-forwarded-proto`` (the ``X-Forwarded-Proto`` header of the request). The default is ``scheme``. | ``string`` | No | ### VirtualServer.Policy | +{{% /table %}} The policy field references a [Policy resource](/nginx-ingress-controller/configuration/policy-resource/) by its name and optional namespace. For example: ```yaml @@ -100,12 +100,12 @@ name: access-control ### VirtualServer.Policy -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``name`` | The name of a policy. If the policy doesn't exist or invalid, NGINX will respond with an error response with the `500` status code. | ``string`` | Yes | -|``namespace`` | The namespace of a policy. If not specified, the namespace of the VirtualServer resource is used. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of a policy. If the policy doesn't exist or invalid, NGINX will respond with an error response with the `500` status code. | ``string`` | Yes | +|``namespace`` | The namespace of a policy. If not specified, the namespace of the VirtualServer resource is used. | ``string`` | No | +{{% /table %}} ### VirtualServer.Route @@ -116,18 +116,18 @@ The route defines rules for matching client requests to actions like passing a r pass: tea ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``path`` | The path of the route. NGINX will match it against the URI of a request. Possible values are: a prefix (\ ``/``\ , ``/path``\ ), an exact match (\ ``=/exact/match``\ ), a case insensitive regular expression (\ ``~*^/Bar.*\\.jpg``\ ) or a case sensitive regular expression (\ ``~^/foo.*\\.jpg``\ ). In the case of a prefix (must start with ``/``\ ) or an exact match (must start with ``=``\ ), the path must not include any whitespace characters, ``{``\ , ``}`` or ``;``. In the case of the regex matches, all double quotes ``"`` must be escaped and the match can't end in an unescaped backslash ``\``. The path must be unique among the paths of all routes of the VirtualServer. Check the [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive for more information. | ``string`` | Yes | -|``policies`` | A list of policies. The policies override the policies of the same type defined in the ``spec`` of the VirtualServer. See [Applying Policies](/nginx-ingress-controller/configuration/policy-resource/#applying-policies) for more details. | [[]policy](#virtualserverpolicy) | No | -|``action`` | The default action to perform for a request. | [action](#action) | No | -|``splits`` | The default splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | -|``matches`` | The matching rules for advanced content-based routing. Requires the default ``action`` or ``splits``. Unmatched requests will be handled by the default ``action`` or ``splits``. | [matches](#match) | No | -|``route`` | The name of a VirtualServerRoute resource that defines this route. If the VirtualServerRoute belongs to a different namespace than the VirtualServer, you need to include the namespace. For example, ``tea-namespace/tea``. | ``string`` | No | -|``errorPages`` | The custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code. | [[]errorPage](#errorpage) | No | -|``location-snippets`` | Sets a custom snippet in the location context. Overrides the ``location-snippets`` ConfigMap key. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``path`` | The path of the route. NGINX will match it against the URI of a request. Possible values are: a prefix (\ ``/``\ , ``/path``\ ), an exact match (\ ``=/exact/match``\ ), a case insensitive regular expression (\ ``~*^/Bar.*\\.jpg``\ ) or a case sensitive regular expression (\ ``~^/foo.*\\.jpg``\ ). In the case of a prefix (must start with ``/``\ ) or an exact match (must start with ``=``\ ), the path must not include any whitespace characters, ``{``\ , ``}`` or ``;``. In the case of the regex matches, all double quotes ``"`` must be escaped and the match can't end in an unescaped backslash ``\``. The path must be unique among the paths of all routes of the VirtualServer. Check the [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive for more information. | ``string`` | Yes | +|``policies`` | A list of policies. The policies override the policies of the same type defined in the ``spec`` of the VirtualServer. See [Applying Policies](/nginx-ingress-controller/configuration/policy-resource/#applying-policies) for more details. | [[]policy](#virtualserverpolicy) | No | +|``action`` | The default action to perform for a request. | [action](#action) | No | +|``splits`` | The default splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | +|``matches`` | The matching rules for advanced content-based routing. Requires the default ``action`` or ``splits``. Unmatched requests will be handled by the default ``action`` or ``splits``. | [matches](#match) | No | +|``route`` | The name of a VirtualServerRoute resource that defines this route. If the VirtualServerRoute belongs to a different namespace than the VirtualServer, you need to include the namespace. For example, ``tea-namespace/tea``. | ``string`` | No | +|``errorPages`` | The custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code. | [[]errorPage](#errorpage) | No | +|``location-snippets`` | Sets a custom snippet in the location context. Overrides the ``location-snippets`` ConfigMap key. | ``string`` | No | +{{% /table %}} \* -- a route must include exactly one of the following: `action`, `splits`, or `route`. @@ -185,14 +185,14 @@ spec: Note that each subroute must have a `path` that starts with the same prefix (here `/coffee`), which is defined in the route of the VirtualServer. Additionally, the `host` in the VirtualServerRoute must be the same as the `host` of the VirtualServer. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. Wildcard domains like ``*.example.com`` are not allowed. Must be the same as the ``host`` of the VirtualServer that references this resource. | ``string`` | Yes | -|``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | -|``subroutes`` | A list of subroutes. | [[]subroute](#virtualserverroutesubroute) | No | -|``ingressClassName`` | Specifies which Ingress controller must handle the VirtualServerRoute resource. Must be the same as the ``ingressClassName`` of the VirtualServer that references this resource. | ``string``_ | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. Wildcard domains like ``*.example.com`` are not allowed. Must be the same as the ``host`` of the VirtualServer that references this resource. | ``string`` | Yes | +|``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | +|``subroutes`` | A list of subroutes. | [[]subroute](#virtualserverroutesubroute) | No | +|``ingressClassName`` | Specifies which Ingress controller must handle the VirtualServerRoute resource. Must be the same as the ``ingressClassName`` of the VirtualServer that references this resource. | ``string``_ | No | +{{% /table %}} ### VirtualServerRoute.Subroute @@ -203,17 +203,17 @@ action: pass: coffee ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``path`` | The path of the subroute. NGINX will match it against the URI of a request. Possible values are: a prefix (\ ``/``\ , ``/path``\ ), an exact match (\ ``=/exact/match``\ ), a case insensitive regular expression (\ ``~*^/Bar.*\\.jpg``\ ) or a case sensitive regular expression (\ ``~^/foo.*\\.jpg``\ ). In the case of a prefix, the path must start with the same path as the path of the route of the VirtualServer that references this resource. In the case of an exact or regex match, the path must be the same as the path of the route of the VirtualServer that references this resource. In the case of a prefix or an exact match, the path must not include any whitespace characters, ``{``\ , ``}`` or ``;``. In the case of the regex matches, all double quotes ``"`` must be escaped and the match can't end in an unescaped backslash ``\``. The path must be unique among the paths of all subroutes of the VirtualServerRoute. | ``string`` | Yes | -|``policies`` | A list of policies. The policies override *all* policies defined in the route of the VirtualServer that references this resource. The policies also override the policies of the same type defined in the ``spec`` of the VirtualServer. See [Applying Policies](/nginx-ingress-controller/configuration/policy-resource/#applying-policies) for more details. | [[]policy](#virtualserverpolicy) | No | -|``action`` | The default action to perform for a request. | [action](#action) | No | -|``splits`` | The default splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | -|``matches`` | The matching rules for advanced content-based routing. Requires the default ``action`` or ``splits``. Unmatched requests will be handled by the default ``action`` or ``splits``. | [matches](#match) | No | -|``errorPages`` | The custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code. | [[]errorPage](#errorpage) | No | -|``location-snippets`` | Sets a custom snippet in the location context. Overrides the ``location-snippets`` of the VirtualServer (if set) or the ``location-snippets`` ConfigMap key. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``path`` | The path of the subroute. NGINX will match it against the URI of a request. Possible values are: a prefix (\ ``/``\ , ``/path``\ ), an exact match (\ ``=/exact/match``\ ), a case insensitive regular expression (\ ``~*^/Bar.*\\.jpg``\ ) or a case sensitive regular expression (\ ``~^/foo.*\\.jpg``\ ). In the case of a prefix, the path must start with the same path as the path of the route of the VirtualServer that references this resource. In the case of an exact or regex match, the path must be the same as the path of the route of the VirtualServer that references this resource. In the case of a prefix or an exact match, the path must not include any whitespace characters, ``{``\ , ``}`` or ``;``. In the case of the regex matches, all double quotes ``"`` must be escaped and the match can't end in an unescaped backslash ``\``. The path must be unique among the paths of all subroutes of the VirtualServerRoute. | ``string`` | Yes | +|``policies`` | A list of policies. The policies override *all* policies defined in the route of the VirtualServer that references this resource. The policies also override the policies of the same type defined in the ``spec`` of the VirtualServer. See [Applying Policies](/nginx-ingress-controller/configuration/policy-resource/#applying-policies) for more details. | [[]policy](#virtualserverpolicy) | No | +|``action`` | The default action to perform for a request. | [action](#action) | No | +|``splits`` | The default splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | +|``matches`` | The matching rules for advanced content-based routing. Requires the default ``action`` or ``splits``. Unmatched requests will be handled by the default ``action`` or ``splits``. | [matches](#match) | No | +|``errorPages`` | The custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code. | [[]errorPage](#errorpage) | No | +|``location-snippets`` | Sets a custom snippet in the location context. Overrides the ``location-snippets`` of the VirtualServer (if set) or the ``location-snippets`` ConfigMap key. | ``string`` | No | +{{% /table %}} \* -- a subroute must include exactly one of the following: `action` or `splits`. @@ -246,35 +246,35 @@ tls: **Note**: The WebSocket protocol is supported without any additional configuration. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``name`` | The name of the upstream. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``upstream-123`` are valid. The name must be unique among all upstreams of the resource. | ``string`` | Yes | -|``service`` | The name of a [service](https://kubernetes.io/docs/concepts/services-networking/service/). The service must belong to the same namespace as the resource. If the service doesn't exist, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. For NGINX Plus only, services of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) are also supported (check the [prerequisites](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/externalname-services#prerequisites)\ ). | ``string`` | Yes | -|``subselector`` | Selects the pods within the service using label keys and values. By default, all pods of the service are selected. Note: the specified labels are expected to be present in the pods when they are created. If the pod labels are updated, the Ingress Controller will not see that change until the number of the pods is changed. | ``map[string]string`` | No | -|``use-cluster-ip`` | Enables using the Cluster IP and port of the service instead of the default behavior of using the IP and port of the pods. When this field is enabled, the fields that configure NGINX behavior related to multiple upstream servers (like ``lb-method`` and ``next-upstream``) will have no effect, as the Ingress Controller will configure NGINX with only one upstream server that will match the service Cluster IP. | ``boolean`` | No | -|``port`` | The port of the service. If the service doesn't define that port, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. The port must fall into the range ``1..65535``. | ``uint16`` | Yes | -|``lb-method`` | The load [balancing method](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#choosing-a-load-balancing-method). To use the round-robin method, specify ``round_robin``. The default is specified in the ``lb-method`` ConfigMap key. | ``string`` | No | -|``fail-timeout`` | The time during which the specified number of unsuccessful attempts to communicate with an upstream server should happen to consider the server unavailable. See the [fail_timeout](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout) parameter of the server directive. The default is set in the ``fail-timeout`` ConfigMap key. | ``string`` | No | -|``max-fails`` | The number of unsuccessful attempts to communicate with an upstream server that should happen in the duration set by the ``fail-timeout`` to consider the server unavailable. See the [max_fails](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails) parameter of the server directive. The default is set in the ``max-fails`` ConfigMap key. | ``int`` | No | -|``max-conns`` | The maximum number of simultaneous active connections to an upstream server. See the [max_conns](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns) parameter of the server directive. By default there is no limit. Note: if keepalive connections are enabled, the total number of active and idle keepalive connections to an upstream server may exceed the ``max_conns`` value. | ``int`` | No | -|``keepalive`` | Configures the cache for connections to upstream servers. The value ``0`` disables the cache. See the [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) directive. The default is set in the ``keepalive`` ConfigMap key. | ``int`` | No | -|``connect-timeout`` | The timeout for establishing a connection with an upstream server. See the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) directive. The default is specified in the ``proxy-connect-timeout`` ConfigMap key. | ``string`` | No | -|``read-timeout`` | The timeout for reading a response from an upstream server. See the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) directive. The default is specified in the ``proxy-read-timeout`` ConfigMap key. | ``string`` | No | -|``send-timeout`` | The timeout for transmitting a request to an upstream server. See the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) directive. The default is specified in the ``proxy-send-timeout`` ConfigMap key. | ``string`` | No | -|``next-upstream`` | Specifies in which cases a request should be passed to the next upstream server. See the [proxy_next_upstream](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream) directive. The default is ``error timeout``. | ``string`` | No | -|``next-upstream-timeout`` | The time during which a request can be passed to the next upstream server. See the [proxy_next_upstream_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_timeout) directive. The ``0`` value turns off the time limit. The default is ``0``. | ``string`` | No | -|``next-upstream-tries`` | The number of possible tries for passing a request to the next upstream server. See the [proxy_next_upstream_tries](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_tries) directive. The ``0`` value turns off this limit. The default is ``0``. | ``int`` | No | -|``client-max-body-size`` | Sets the maximum allowed size of the client request body. See the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. The default is set in the ``client-max-body-size`` ConfigMap key. | ``string`` | No | -|``tls`` | The TLS configuration for the Upstream. | [tls](#upstreamtls) | No | -|``healthCheck`` | The health check configuration for the Upstream. See the [health_check](https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check) directive. Note: this feature is supported only in NGINX Plus. | [healthcheck](#upstreamhealthcheck) | No | -|``slow-start`` | The slow start allows an upstream server to gradually recover its weight from 0 to its nominal value after it has been recovered or became available or when the server becomes available after a period of time it was considered unavailable. By default, the slow start is disabled. See the [slow_start](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start) parameter of the server directive. Note: The parameter cannot be used along with the ``random``\ , ``hash`` or ``ip_hash`` load balancing methods and will be ignored. | ``string`` | No | -|``queue`` | Configures a queue for an upstream. A client request will be placed into the queue if an upstream server cannot be selected immediately while processing the request. By default, no queue is configured. Note: this feature is supported only in NGINX Plus. | [queue](#upstreamqueue) | No | -|``buffering`` | Enables buffering of responses from the upstream server. See the [proxy_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) directive. The default is set in the ``proxy-buffering`` ConfigMap key. | ``boolean`` | No | -|``buffers`` | Configures the buffers used for reading a response from the upstream server for a single connection. | [buffers](#upstreambuffers) | No | -|``buffer-size`` | Sets the size of the buffer used for reading the first part of a response received from the upstream server. See the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) directive. The default is set in the ``proxy-buffer-size`` ConfigMap key. | ``string`` | No | +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the upstream. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``upstream-123`` are valid. The name must be unique among all upstreams of the resource. | ``string`` | Yes | +|``service`` | The name of a [service](https://kubernetes.io/docs/concepts/services-networking/service/). The service must belong to the same namespace as the resource. If the service doesn't exist, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. For NGINX Plus only, services of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) are also supported (check the [prerequisites](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/externalname-services#prerequisites)\ ). | ``string`` | Yes | +|``subselector`` | Selects the pods within the service using label keys and values. By default, all pods of the service are selected. Note: the specified labels are expected to be present in the pods when they are created. If the pod labels are updated, the Ingress Controller will not see that change until the number of the pods is changed. | ``map[string]string`` | No | +|``use-cluster-ip`` | Enables using the Cluster IP and port of the service instead of the default behavior of using the IP and port of the pods. When this field is enabled, the fields that configure NGINX behavior related to multiple upstream servers (like ``lb-method`` and ``next-upstream``) will have no effect, as the Ingress Controller will configure NGINX with only one upstream server that will match the service Cluster IP. | ``boolean`` | No | +|``port`` | The port of the service. If the service doesn't define that port, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. The port must fall into the range ``1..65535``. | ``uint16`` | Yes | +|``lb-method`` | The load [balancing method](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#choosing-a-load-balancing-method). To use the round-robin method, specify ``round_robin``. The default is specified in the ``lb-method`` ConfigMap key. | ``string`` | No | +|``fail-timeout`` | The time during which the specified number of unsuccessful attempts to communicate with an upstream server should happen to consider the server unavailable. See the [fail_timeout](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout) parameter of the server directive. The default is set in the ``fail-timeout`` ConfigMap key. | ``string`` | No | +|``max-fails`` | The number of unsuccessful attempts to communicate with an upstream server that should happen in the duration set by the ``fail-timeout`` to consider the server unavailable. See the [max_fails](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails) parameter of the server directive. The default is set in the ``max-fails`` ConfigMap key. | ``int`` | No | +|``max-conns`` | The maximum number of simultaneous active connections to an upstream server. See the [max_conns](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns) parameter of the server directive. By default there is no limit. Note: if keepalive connections are enabled, the total number of active and idle keepalive connections to an upstream server may exceed the ``max_conns`` value. | ``int`` | No | +|``keepalive`` | Configures the cache for connections to upstream servers. The value ``0`` disables the cache. See the [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) directive. The default is set in the ``keepalive`` ConfigMap key. | ``int`` | No | +|``connect-timeout`` | The timeout for establishing a connection with an upstream server. See the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) directive. The default is specified in the ``proxy-connect-timeout`` ConfigMap key. | ``string`` | No | +|``read-timeout`` | The timeout for reading a response from an upstream server. See the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) directive. The default is specified in the ``proxy-read-timeout`` ConfigMap key. | ``string`` | No | +|``send-timeout`` | The timeout for transmitting a request to an upstream server. See the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) directive. The default is specified in the ``proxy-send-timeout`` ConfigMap key. | ``string`` | No | +|``next-upstream`` | Specifies in which cases a request should be passed to the next upstream server. See the [proxy_next_upstream](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream) directive. The default is ``error timeout``. | ``string`` | No | +|``next-upstream-timeout`` | The time during which a request can be passed to the next upstream server. See the [proxy_next_upstream_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_timeout) directive. The ``0`` value turns off the time limit. The default is ``0``. | ``string`` | No | +|``next-upstream-tries`` | The number of possible tries for passing a request to the next upstream server. See the [proxy_next_upstream_tries](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_tries) directive. The ``0`` value turns off this limit. The default is ``0``. | ``int`` | No | +|``client-max-body-size`` | Sets the maximum allowed size of the client request body. See the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. The default is set in the ``client-max-body-size`` ConfigMap key. | ``string`` | No | +|``tls`` | The TLS configuration for the Upstream. | [tls](#upstreamtls) | No | +|``healthCheck`` | The health check configuration for the Upstream. See the [health_check](https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check) directive. Note: this feature is supported only in NGINX Plus. | [healthcheck](#upstreamhealthcheck) | No | +|``slow-start`` | The slow start allows an upstream server to gradually recover its weight from 0 to its nominal value after it has been recovered or became available or when the server becomes available after a period of time it was considered unavailable. By default, the slow start is disabled. See the [slow_start](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start) parameter of the server directive. Note: The parameter cannot be used along with the ``random``\ , ``hash`` or ``ip_hash`` load balancing methods and will be ignored. | ``string`` | No | +|``queue`` | Configures a queue for an upstream. A client request will be placed into the queue if an upstream server cannot be selected immediately while processing the request. By default, no queue is configured. Note: this feature is supported only in NGINX Plus. | [queue](#upstreamqueue) | No | +|``buffering`` | Enables buffering of responses from the upstream server. See the [proxy_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) directive. The default is set in the ``proxy-buffering`` ConfigMap key. | ``boolean`` | No | +|``buffers`` | Configures the buffers used for reading a response from the upstream server for a single connection. | [buffers](#upstreambuffers) | No | +|``buffer-size`` | Sets the size of the buffer used for reading the first part of a response received from the upstream server. See the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) directive. The default is set in the ``proxy-buffer-size`` ConfigMap key. | ``string`` | No | |``ntlm`` | Allows proxying requests with NTLM Authentication. See the [ntlm](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ntlm) directive. In order for NTLM authentication to work, it is necessary to enable keepalive connections to upstream servers using the ``keepalive`` field. Note: this feature is supported only in NGINX Plus.| ``boolean`` | No | -{{% /table %}} +{{% /table %}} ### Upstream.Buffers The buffers field configures the buffers used for reading a response from the upstream server for a single connection: @@ -285,20 +285,20 @@ size: 8K ``` See the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive for additional information. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``number`` | Configures the number of buffers. The default is set in the ``proxy-buffers`` ConfigMap key. | ``int`` | Yes | -|``size`` | Configures the size of a buffer. The default is set in the ``proxy-buffers`` ConfigMap key. | ``string`` | Yes | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``number`` | Configures the number of buffers. The default is set in the ``proxy-buffers`` ConfigMap key. | ``int`` | Yes | +|``size`` | Configures the size of a buffer. The default is set in the ``proxy-buffers`` ConfigMap key. | ``string`` | Yes | +{{% /table %}} ### Upstream.TLS -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``enable`` | Enables HTTPS for requests to upstream servers. The default is ``False``\ , meaning that HTTP will be used. Note: by default, NGINX will not verify the upstream server certificate. To enable the verification, configure an [EgressMTLS Policy](/nginx-ingress-controller/configuration/policy-resource/#egressmtls). | ``boolean`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables HTTPS for requests to upstream servers. The default is ``False``\ , meaning that HTTP will be used. Note: by default, NGINX will not verify the upstream server certificate. To enable the verification, configure an [EgressMTLS Policy](/nginx-ingress-controller/configuration/policy-resource/#egressmtls). | ``boolean`` | No | +{{% /table %}} ### Upstream.Queue @@ -313,12 +313,12 @@ See [`queue`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue Note: This feature is supported only in NGINX Plus. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``size`` | The size of the queue. | ``int`` | Yes | -|``timeout`` | The timeout of the queue. A request cannot be queued for a period longer than the timeout. The default is ``60s``. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``size`` | The size of the queue. | ``int`` | Yes | +|``timeout`` | The timeout of the queue. A request cannot be queued for a period longer than the timeout. The default is ``60s``. | ``string`` | No | +{{% /table %}} ### Upstream.Healthcheck @@ -349,23 +349,23 @@ healthCheck: Note: This feature is supported only in NGINX Plus. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``enable`` | Enables a health check for an upstream server. The default is ``false``. | ``boolean`` | No | -|``path`` | The path used for health check requests. The default is ``/``. | ``string`` | No | -|``interval`` | The interval between two consecutive health checks. The default is ``5s``. | ``string`` | No | -|``jitter`` | The time within which each health check will be randomly delayed. By default, there is no delay. | ``string`` | No | -|``fails`` | The number of consecutive failed health checks of a particular upstream server after which this server will be considered unhealthy. The default is ``1``. | ``integer`` | No | -|``passes`` | The number of consecutive passed health checks of a particular upstream server after which the server will be considered healthy. The default is ``1``. | ``integer`` | No | -|``port`` | The port used for health check requests. By default, the port of the upstream is used. Note: in contrast with the port of the upstream, this port is not a service port, but a port of a pod. | ``integer`` | No | -|``tls`` | The TLS configuration used for health check requests. By default, the ``tls`` field of the upstream is used. | [upstream.tls](#upstreamtls) | No | -|``connect-timeout`` | The timeout for establishing a connection with an upstream server. By default, the ``connect-timeout`` of the upstream is used. | ``string`` | No | -|``read-timeout`` | The timeout for reading a response from an upstream server. By default, the ``read-timeout`` of the upstream is used. | ``string`` | No | -|``send-timeout`` | The timeout for transmitting a request to an upstream server. By default, the ``send-timeout`` of the upstream is used. | ``string`` | No | -|``headers`` | The request headers used for health check requests. NGINX Plus always sets the ``Host``\ , ``User-Agent`` and ``Connection`` headers for health check requests. | [[]header](#header) | No | -|``statusMatch`` | The expected response status codes of a health check. By default, the response should have status code 2xx or 3xx. Examples: ``"200"``\ , ``"! 500"``\ , ``"301-303 307"``. See the documentation of the [match](https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html?#match) directive. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables a health check for an upstream server. The default is ``false``. | ``boolean`` | No | +|``path`` | The path used for health check requests. The default is ``/``. | ``string`` | No | +|``interval`` | The interval between two consecutive health checks. The default is ``5s``. | ``string`` | No | +|``jitter`` | The time within which each health check will be randomly delayed. By default, there is no delay. | ``string`` | No | +|``fails`` | The number of consecutive failed health checks of a particular upstream server after which this server will be considered unhealthy. The default is ``1``. | ``integer`` | No | +|``passes`` | The number of consecutive passed health checks of a particular upstream server after which the server will be considered healthy. The default is ``1``. | ``integer`` | No | +|``port`` | The port used for health check requests. By default, the port of the upstream is used. Note: in contrast with the port of the upstream, this port is not a service port, but a port of a pod. | ``integer`` | No | +|``tls`` | The TLS configuration used for health check requests. By default, the ``tls`` field of the upstream is used. | [upstream.tls](#upstreamtls) | No | +|``connect-timeout`` | The timeout for establishing a connection with an upstream server. By default, the ``connect-timeout`` of the upstream is used. | ``string`` | No | +|``read-timeout`` | The timeout for reading a response from an upstream server. By default, the ``read-timeout`` of the upstream is used. | ``string`` | No | +|``send-timeout`` | The timeout for transmitting a request to an upstream server. By default, the ``send-timeout`` of the upstream is used. | ``string`` | No | +|``headers`` | The request headers used for health check requests. NGINX Plus always sets the ``Host``\ , ``User-Agent`` and ``Connection`` headers for health check requests. | [[]header](#header) | No | +|``statusMatch`` | The expected response status codes of a health check. By default, the response should have status code 2xx or 3xx. Examples: ``"200"``\ , ``"! 500"``\ , ``"301-303 307"``. See the documentation of the [match](https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html?#match) directive. | ``string`` | No | +{{% /table %}} ### Upstream.SessionCookie @@ -390,17 +390,17 @@ See the [`sticky`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html? Note: This feature is supported only in NGINX Plus. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``enable`` | Enables session persistence with a session cookie for an upstream server. The default is ``false``. | ``boolean`` | No | -|``name`` | The name of the cookie. | ``string`` | Yes | -|``path`` | The path for which the cookie is set. | ``string`` | No | -|``expires`` | The time for which a browser should keep the cookie. Can be set to the special value ``max``\ , which will cause the cookie to expire on ``31 Dec 2037 23:55:55 GMT``. | ``string`` | No | -|``domain`` | The domain for which the cookie is set. | ``string`` | No | -|``httpOnly`` | Adds the ``HttpOnly`` attribute to the cookie. | ``boolean`` | No | -|``secure`` | Adds the ``Secure`` attribute to the cookie. | ``boolean`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables session persistence with a session cookie for an upstream server. The default is ``false``. | ``boolean`` | No | +|``name`` | The name of the cookie. | ``string`` | Yes | +|``path`` | The path for which the cookie is set. | ``string`` | No | +|``expires`` | The time for which a browser should keep the cookie. Can be set to the special value ``max``\ , which will cause the cookie to expire on ``31 Dec 2037 23:55:55 GMT``. | ``string`` | No | +|``domain`` | The domain for which the cookie is set. | ``string`` | No | +|``httpOnly`` | Adds the ``HttpOnly`` attribute to the cookie. | ``boolean`` | No | +|``secure`` | Adds the ``Secure`` attribute to the cookie. | ``boolean`` | No | +{{% /table %}} ### Header @@ -410,12 +410,12 @@ name: Host value: example.com ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``name`` | The name of the header. | ``string`` | Yes | -|``value`` | The value of the header. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. | ``string`` | No | +{{% /table %}} ### Action @@ -428,14 +428,14 @@ In the example below, client requests are passed to an upstream `coffee`: pass: coffee ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``pass`` | Passes requests to an upstream. The upstream with that name must be defined in the resource. | ``string`` | No | -|``redirect`` | Redirects requests to a provided URL. | [action.redirect](#actionredirect) | No | -|``return`` | Returns a preconfigured response. | [action.return](#actionreturn) | No | -|``proxy`` | Passes requests to an upstream with the ability to modify the request/response (for example, rewrite the URI or modify the headers). | [action.proxy](#actionproxy) | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``pass`` | Passes requests to an upstream. The upstream with that name must be defined in the resource. | ``string`` | No | +|``redirect`` | Redirects requests to a provided URL. | [action.redirect](#actionredirect) | No | +|``return`` | Returns a preconfigured response. | [action.return](#actionreturn) | No | +|``proxy`` | Passes requests to an upstream with the ability to modify the request/response (for example, rewrite the URI or modify the headers). | [action.proxy](#actionproxy) | No | +{{% /table %}} \* -- an action must include exactly one of the following: `pass`, `redirect`, `return` or `proxy`. @@ -450,12 +450,12 @@ redirect: code: 301 ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``url`` | The URL to redirect the request to. Supported NGINX variables: ``$scheme``\ , ``$http_x_forwarded_proto``\ , ``$request_uri``\ , ``$host``. Variables must be enclosed in curly braces. For example: ``${host}${request_uri}``. | ``string`` | Yes | -|``code`` | The status code of a redirect. The allowed values are: ``301``\ , ``302``\ , ``307``\ , ``308``. The default is ``301``. | ``int`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``url`` | The URL to redirect the request to. Supported NGINX variables: ``$scheme``\ , ``$http_x_forwarded_proto``\ , ``$request_uri``\ , ``$host``. Variables must be enclosed in curly braces. For example: ``${host}${request_uri}``. | ``string`` | Yes | +|``code`` | The status code of a redirect. The allowed values are: ``301``\ , ``302``\ , ``307``\ , ``308``. The default is ``301``. | ``int`` | No | +{{% /table %}} ### Action.Return @@ -469,13 +469,13 @@ return: body: "Hello World\n" ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``code`` | The status code of the response. The allowed values are: ``2XX``, ``4XX`` or ``5XX``. The default is ``200``. | ``int`` | No | -|``type`` | The MIME type of the response. The default is ``text/plain``. | ``string`` | No | -|``body`` | The body of the response. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``Request is ${request_uri}\n``. | ``string`` | Yes | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``code`` | The status code of the response. The allowed values are: ``2XX``, ``4XX`` or ``5XX``. The default is ``200``. | ``int`` | No | +|``type`` | The MIME type of the response. The default is ``text/plain``. | ``string`` | No | +|``body`` | The body of the response. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``Request is ${request_uri}\n``. | ``string`` | Yes | +{{% /table %}} \* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing` and `$connections_waiting`. @@ -511,25 +511,25 @@ proxy: rewritePath: / ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``upstream`` | The name of the upstream which the requests will be proxied to. The upstream with that name must be defined in the resource. | ``string`` | Yes | -|``requestHeaders`` | The request headers modifications. | [action.Proxy.RequestHeaders](#actionproxyrequestheaders) | No | -|``responseHeaders`` | The response headers modifications. | [action.Proxy.ResponseHeaders](#actionproxyresponseheaders) | No | -|``rewritePath`` | The rewritten URI. If the route path is a regular expression (starts with ~), the rewritePath can include capture groups with ``$1-9``. For example `$1` for the first group, and so on. For more information, check the [rewrite](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples-of-custom-resources/rewrites) example. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``upstream`` | The name of the upstream which the requests will be proxied to. The upstream with that name must be defined in the resource. | ``string`` | Yes | +|``requestHeaders`` | The request headers modifications. | [action.Proxy.RequestHeaders](#actionproxyrequestheaders) | No | +|``responseHeaders`` | The response headers modifications. | [action.Proxy.ResponseHeaders](#actionproxyresponseheaders) | No | +|``rewritePath`` | The rewritten URI. If the route path is a regular expression (starts with ~), the rewritePath can include capture groups with ``$1-9``. For example `$1` for the first group, and so on. For more information, check the [rewrite](https://github.com/nginxinc/kubernetes-ingress/tree/v2.0.3/examples/custom-resources/rewrites) example. | ``string`` | No | +{{% /table %}} ### Action.Proxy.RequestHeaders The RequestHeaders field modifies the headers of the request to the proxied upstream server. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``pass`` | Passes the original request headers to the proxied upstream server. See the [proxy_pass_request_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_request_headers) directive for more information. Default is true. | ``bool`` | No | -|``set`` | Allows redefining or appending fields to present request headers passed to the proxied upstream servers. See the [proxy_set_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive for more information. | [[]header](#actionproxyrequestheaderssetheader) | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``pass`` | Passes the original request headers to the proxied upstream server. See the [proxy_pass_request_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_request_headers) directive for more information. Default is true. | ``bool`` | No | +|``set`` | Allows redefining or appending fields to present request headers passed to the proxied upstream servers. See the [proxy_set_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive for more information. | [[]header](#actionproxyrequestheaderssetheader) | No | +{{% /table %}} ### Action.Proxy.RequestHeaders.Set.Header @@ -545,12 +545,12 @@ name: Host value: example.com ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``name`` | The name of the header. | ``string`` | Yes | -|``value`` | The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. | ``string`` | No | +{{% /table %}} \* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing`, `$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`, `$ssl_client_cert`, `$ssl_client_escaped_cert`, `$ssl_client_fingerprint`, `$ssl_client_i_dn`, `$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`, `$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`, `$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`, `$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`, `$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`, `$jwt_claim_` (NGINX Plus only) and `$jwt_header_` (NGINX Plus only). @@ -558,14 +558,14 @@ value: example.com The ResponseHeaders field modifies the headers of the response to the client. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``hide`` | The headers that will not be passed* in the response to the client from a proxied upstream server. See the [proxy_hide_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header) directive for more information. | ``bool`` | No | -|``pass`` | Allows passing the hidden header fields* to the client from a proxied upstream server. See the [proxy_pass_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directive for more information. | ``[]string`` | No | -|``ignore`` | Disables processing of certain headers** to the client from a proxied upstream server. See the [proxy_ignore_headers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ignore_headers) directive for more information. | ``[]string`` | No | -|``add`` | Adds headers to the response to the client. | [[]addHeader](#addheader) | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``hide`` | The headers that will not be passed* in the response to the client from a proxied upstream server. See the [proxy_hide_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header) directive for more information. | ``bool`` | No | +|``pass`` | Allows passing the hidden header fields* to the client from a proxied upstream server. See the [proxy_pass_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directive for more information. | ``[]string`` | No | +|``ignore`` | Disables processing of certain headers** to the client from a proxied upstream server. See the [proxy_ignore_headers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ignore_headers) directive for more information. | ``[]string`` | No | +|``add`` | Adds headers to the response to the client. | [[]addHeader](#addheader) | No | +{{% /table %}} \* -- Default hidden headers are: `Date`, `Server`, `X-Pad` and `X-Accel-...`. @@ -580,13 +580,13 @@ value: My-Value always: true ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``name`` | The name of the header. | ``string`` | Yes | -|``value`` | The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. | ``string`` | No | -|``always`` | If set to true, add the header regardless of the response status code**. Default is false. See the [add_header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header) directive for more information. | ``bool`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. | ``string`` | No | +|``always`` | If set to true, add the header regardless of the response status code**. Default is false. See the [add_header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header) directive for more information. | ``bool`` | No | +{{% /table %}} \* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing`, `$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`, `$ssl_client_cert`, `$ssl_client_escaped_cert`, `$ssl_client_fingerprint`, `$ssl_client_i_dn`, `$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`, `$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`, `$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`, `$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`, `$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`, `$jwt_claim_` (NGINX Plus only) and `$jwt_header_` (NGINX Plus only). @@ -607,12 +607,12 @@ splits: pass: coffee-v2 ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``weight`` | The weight of an action. Must fall into the range ``1..99``. The sum of the weights of all splits must be equal to ``100``. | ``int`` | Yes | -|``action`` | The action to perform for a request. | [action](#action) | Yes | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``weight`` | The weight of an action. Must fall into the range ``1..99``. The sum of the weights of all splits must be equal to ``100``. | ``int`` | Yes | +|``action`` | The action to perform for a request. | [action](#action) | Yes | +{{% /table %}} ### Match @@ -656,13 +656,13 @@ action: pass: coffee ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``conditions`` | A list of conditions. Must include at least 1 condition. | [[]condition](#condition) | Yes | -|``action`` | The action to perform for a request. | [action](#action) | No | -|``splits`` | The splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``conditions`` | A list of conditions. Must include at least 1 condition. | [[]condition](#condition) | Yes | +|``action`` | The action to perform for a request. | [action](#action) | No | +|``splits`` | The splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | +{{% /table %}} \* -- a match must include exactly one of the following: `action` or `splits`. @@ -670,15 +670,15 @@ action: The condition defines a condition in a match. -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``header`` | The name of a header. Must consist of alphanumeric characters or ``-``. | ``string`` | No | -|``cookie`` | The name of a cookie. Must consist of alphanumeric characters or ``_``. | ``string`` | No | -|``argument`` | The name of an argument. Must consist of alphanumeric characters or ``_``. | ``string`` | No | -|``variable`` | The name of an NGINX variable. Must start with ``$``. See the list of the supported variables below the table. | ``string`` | No | -|``value`` | The value to match the condition against. How to define a value is shown below the table. | ``string`` | Yes | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``header`` | The name of a header. Must consist of alphanumeric characters or ``-``. | ``string`` | No | +|``cookie`` | The name of a cookie. Must consist of alphanumeric characters or ``_``. | ``string`` | No | +|``argument`` | The name of an argument. Must consist of alphanumeric characters or ``_``. | ``string`` | No | +|``variable`` | The name of an NGINX variable. Must start with ``$``. See the list of the supported variables below the table. | ``string`` | No | +|``value`` | The value to match the condition against. How to define a value is shown below the table. | ``string`` | Yes | +{{% /table %}} \* -- a condition must include exactly one of the following: `header`, `cookie`, `argument` or `variable`. @@ -712,13 +712,13 @@ errorPages: body: "Original resource not found, but success!" ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``codes`` | A list of error status codes. | ``[]int`` | Yes | -|``redirect`` | The redirect action for the given status codes. | [errorPage.Redirect](#errorpageredirect) | No | -|``return`` | The canned response action for the given status codes. | [errorPage.Return](#errorpagereturn) | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``codes`` | A list of error status codes. | ``[]int`` | Yes | +|``redirect`` | The redirect action for the given status codes. | [errorPage.Redirect](#errorpageredirect) | No | +|``return`` | The canned response action for the given status codes. | [errorPage.Return](#errorpagereturn) | No | +{{% /table %}} \* -- an errorPage must include exactly one of the following: `return` or `redirect`. @@ -735,12 +735,12 @@ redirect: url: ${scheme}://cafe.example.com/error.html ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``code`` | The status code of a redirect. The allowed values are: ``301``\ , ``302``\ , ``307``\ , ``308``. The default is ``301``. | ``int`` | No | -|``url`` | The URL to redirect the request to. Supported NGINX variables: ``$scheme``\ and ``$http_x_forwarded_proto``\. Variables must be enclosed in curly braces. For example: ``${scheme}``. | ``string`` | Yes | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``code`` | The status code of a redirect. The allowed values are: ``301``\ , ``302``\ , ``307``\ , ``308``. The default is ``301``. | ``int`` | No | +|``url`` | The URL to redirect the request to. Supported NGINX variables: ``$scheme``\ and ``$http_x_forwarded_proto``\. Variables must be enclosed in curly braces. For example: ``${scheme}``. | ``string`` | Yes | +{{% /table %}} ### ErrorPage.Return @@ -760,14 +760,14 @@ return: value: ${upstream_status} ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``code`` | The status code of the response. The default is the status code of the original response. | ``int`` | No | -|``type`` | The MIME type of the response. The default is ``text/html``. | ``string`` | No | -|``body`` | The body of the response. Supported NGINX variable: ``$upstream_status`` \ . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. | ``string`` | Yes | -|``headers`` | The custom headers of the response. | [errorPage.Return.Header](#errorpagereturnheader) | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``code`` | The status code of the response. The default is the status code of the original response. | ``int`` | No | +|``type`` | The MIME type of the response. The default is ``text/html``. | ``string`` | No | +|``body`` | The body of the response. Supported NGINX variable: ``$upstream_status`` \ . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. | ``string`` | Yes | +|``headers`` | The custom headers of the response. | [errorPage.Return.Header](#errorpagereturnheader) | No | +{{% /table %}} ### ErrorPage.Return.Header @@ -778,12 +778,12 @@ name: x-debug-original-statuses value: ${upstream_status} ``` -{{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``name`` | The name of the header. | ``string`` | Yes | -|``value`` | The value of the header. Supported NGINX variable: ``$upstream_status`` \ . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. | ``string`` | No | -{{% /table %}} +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. Supported NGINX variable: ``$upstream_status`` \ . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. | ``string`` | No | +{{% /table %}} ## Using VirtualServer and VirtualServerRoute diff --git a/examples-of-custom-resources/access-control/README.md b/examples/custom-resources/access-control/README.md similarity index 100% rename from examples-of-custom-resources/access-control/README.md rename to examples/custom-resources/access-control/README.md diff --git a/examples-of-custom-resources/access-control/access-control-policy-allow.yaml b/examples/custom-resources/access-control/access-control-policy-allow.yaml similarity index 100% rename from examples-of-custom-resources/access-control/access-control-policy-allow.yaml rename to examples/custom-resources/access-control/access-control-policy-allow.yaml diff --git a/examples-of-custom-resources/access-control/access-control-policy-deny.yaml b/examples/custom-resources/access-control/access-control-policy-deny.yaml similarity index 100% rename from examples-of-custom-resources/access-control/access-control-policy-deny.yaml rename to examples/custom-resources/access-control/access-control-policy-deny.yaml diff --git a/examples-of-custom-resources/access-control/virtual-server.yaml b/examples/custom-resources/access-control/virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/access-control/virtual-server.yaml rename to examples/custom-resources/access-control/virtual-server.yaml diff --git a/examples-of-custom-resources/access-control/webapp.yaml b/examples/custom-resources/access-control/webapp.yaml similarity index 100% rename from examples-of-custom-resources/access-control/webapp.yaml rename to examples/custom-resources/access-control/webapp.yaml diff --git a/examples-of-custom-resources/advanced-routing/README.md b/examples/custom-resources/advanced-routing/README.md similarity index 100% rename from examples-of-custom-resources/advanced-routing/README.md rename to examples/custom-resources/advanced-routing/README.md diff --git a/examples-of-custom-resources/advanced-routing/cafe-virtual-server.yaml b/examples/custom-resources/advanced-routing/cafe-virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/advanced-routing/cafe-virtual-server.yaml rename to examples/custom-resources/advanced-routing/cafe-virtual-server.yaml diff --git a/examples-of-custom-resources/advanced-routing/cafe.yaml b/examples/custom-resources/advanced-routing/cafe.yaml similarity index 100% rename from examples-of-custom-resources/advanced-routing/cafe.yaml rename to examples/custom-resources/advanced-routing/cafe.yaml diff --git a/examples-of-custom-resources/basic-configuration/README.md b/examples/custom-resources/basic-configuration/README.md similarity index 100% rename from examples-of-custom-resources/basic-configuration/README.md rename to examples/custom-resources/basic-configuration/README.md diff --git a/examples-of-custom-resources/basic-configuration/cafe-secret.yaml b/examples/custom-resources/basic-configuration/cafe-secret.yaml similarity index 100% rename from examples-of-custom-resources/basic-configuration/cafe-secret.yaml rename to examples/custom-resources/basic-configuration/cafe-secret.yaml diff --git a/examples-of-custom-resources/basic-configuration/cafe-virtual-server.yaml b/examples/custom-resources/basic-configuration/cafe-virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/basic-configuration/cafe-virtual-server.yaml rename to examples/custom-resources/basic-configuration/cafe-virtual-server.yaml diff --git a/examples-of-custom-resources/basic-configuration/cafe.yaml b/examples/custom-resources/basic-configuration/cafe.yaml similarity index 100% rename from examples-of-custom-resources/basic-configuration/cafe.yaml rename to examples/custom-resources/basic-configuration/cafe.yaml diff --git a/examples-of-custom-resources/basic-tcp-udp/README.md b/examples/custom-resources/basic-tcp-udp/README.md similarity index 100% rename from examples-of-custom-resources/basic-tcp-udp/README.md rename to examples/custom-resources/basic-tcp-udp/README.md diff --git a/examples-of-custom-resources/basic-tcp-udp/dns.yaml b/examples/custom-resources/basic-tcp-udp/dns.yaml similarity index 100% rename from examples-of-custom-resources/basic-tcp-udp/dns.yaml rename to examples/custom-resources/basic-tcp-udp/dns.yaml diff --git a/examples-of-custom-resources/basic-tcp-udp/global-configuration.yaml b/examples/custom-resources/basic-tcp-udp/global-configuration.yaml similarity index 100% rename from examples-of-custom-resources/basic-tcp-udp/global-configuration.yaml rename to examples/custom-resources/basic-tcp-udp/global-configuration.yaml diff --git a/examples-of-custom-resources/basic-tcp-udp/transport-server-tcp.yaml b/examples/custom-resources/basic-tcp-udp/transport-server-tcp.yaml similarity index 100% rename from examples-of-custom-resources/basic-tcp-udp/transport-server-tcp.yaml rename to examples/custom-resources/basic-tcp-udp/transport-server-tcp.yaml diff --git a/examples-of-custom-resources/basic-tcp-udp/transport-server-udp.yaml b/examples/custom-resources/basic-tcp-udp/transport-server-udp.yaml similarity index 100% rename from examples-of-custom-resources/basic-tcp-udp/transport-server-udp.yaml rename to examples/custom-resources/basic-tcp-udp/transport-server-udp.yaml diff --git a/examples-of-custom-resources/cross-namespace-configuration/README.md b/examples/custom-resources/cross-namespace-configuration/README.md similarity index 100% rename from examples-of-custom-resources/cross-namespace-configuration/README.md rename to examples/custom-resources/cross-namespace-configuration/README.md diff --git a/examples-of-custom-resources/cross-namespace-configuration/cafe-secret.yaml b/examples/custom-resources/cross-namespace-configuration/cafe-secret.yaml similarity index 100% rename from examples-of-custom-resources/cross-namespace-configuration/cafe-secret.yaml rename to examples/custom-resources/cross-namespace-configuration/cafe-secret.yaml diff --git a/examples-of-custom-resources/cross-namespace-configuration/cafe-virtual-server.yaml b/examples/custom-resources/cross-namespace-configuration/cafe-virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/cross-namespace-configuration/cafe-virtual-server.yaml rename to examples/custom-resources/cross-namespace-configuration/cafe-virtual-server.yaml diff --git a/examples-of-custom-resources/cross-namespace-configuration/coffee-virtual-server-route.yaml b/examples/custom-resources/cross-namespace-configuration/coffee-virtual-server-route.yaml similarity index 100% rename from examples-of-custom-resources/cross-namespace-configuration/coffee-virtual-server-route.yaml rename to examples/custom-resources/cross-namespace-configuration/coffee-virtual-server-route.yaml diff --git a/examples-of-custom-resources/cross-namespace-configuration/coffee.yaml b/examples/custom-resources/cross-namespace-configuration/coffee.yaml similarity index 100% rename from examples-of-custom-resources/cross-namespace-configuration/coffee.yaml rename to examples/custom-resources/cross-namespace-configuration/coffee.yaml diff --git a/examples-of-custom-resources/cross-namespace-configuration/namespaces.yaml b/examples/custom-resources/cross-namespace-configuration/namespaces.yaml similarity index 100% rename from examples-of-custom-resources/cross-namespace-configuration/namespaces.yaml rename to examples/custom-resources/cross-namespace-configuration/namespaces.yaml diff --git a/examples-of-custom-resources/cross-namespace-configuration/tea-virtual-server-route.yaml b/examples/custom-resources/cross-namespace-configuration/tea-virtual-server-route.yaml similarity index 100% rename from examples-of-custom-resources/cross-namespace-configuration/tea-virtual-server-route.yaml rename to examples/custom-resources/cross-namespace-configuration/tea-virtual-server-route.yaml diff --git a/examples-of-custom-resources/cross-namespace-configuration/tea.yaml b/examples/custom-resources/cross-namespace-configuration/tea.yaml similarity index 100% rename from examples-of-custom-resources/cross-namespace-configuration/tea.yaml rename to examples/custom-resources/cross-namespace-configuration/tea.yaml diff --git a/examples-of-custom-resources/custom-templates/README.md b/examples/custom-resources/custom-templates/README.md similarity index 100% rename from examples-of-custom-resources/custom-templates/README.md rename to examples/custom-resources/custom-templates/README.md diff --git a/examples-of-custom-resources/egress-mtls/README.md b/examples/custom-resources/egress-mtls/README.md similarity index 100% rename from examples-of-custom-resources/egress-mtls/README.md rename to examples/custom-resources/egress-mtls/README.md diff --git a/examples-of-custom-resources/egress-mtls/egress-mtls-secret.yaml b/examples/custom-resources/egress-mtls/egress-mtls-secret.yaml similarity index 100% rename from examples-of-custom-resources/egress-mtls/egress-mtls-secret.yaml rename to examples/custom-resources/egress-mtls/egress-mtls-secret.yaml diff --git a/examples-of-custom-resources/egress-mtls/egress-mtls.yaml b/examples/custom-resources/egress-mtls/egress-mtls.yaml similarity index 100% rename from examples-of-custom-resources/egress-mtls/egress-mtls.yaml rename to examples/custom-resources/egress-mtls/egress-mtls.yaml diff --git a/examples-of-custom-resources/egress-mtls/egress-trusted-ca-secret.yaml b/examples/custom-resources/egress-mtls/egress-trusted-ca-secret.yaml similarity index 100% rename from examples-of-custom-resources/egress-mtls/egress-trusted-ca-secret.yaml rename to examples/custom-resources/egress-mtls/egress-trusted-ca-secret.yaml diff --git a/examples-of-custom-resources/egress-mtls/secure-app.yaml b/examples/custom-resources/egress-mtls/secure-app.yaml similarity index 100% rename from examples-of-custom-resources/egress-mtls/secure-app.yaml rename to examples/custom-resources/egress-mtls/secure-app.yaml diff --git a/examples-of-custom-resources/egress-mtls/virtual-server.yaml b/examples/custom-resources/egress-mtls/virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/egress-mtls/virtual-server.yaml rename to examples/custom-resources/egress-mtls/virtual-server.yaml diff --git a/examples-of-custom-resources/ingress-mtls/README.md b/examples/custom-resources/ingress-mtls/README.md similarity index 100% rename from examples-of-custom-resources/ingress-mtls/README.md rename to examples/custom-resources/ingress-mtls/README.md diff --git a/examples-of-custom-resources/ingress-mtls/client-cert.pem b/examples/custom-resources/ingress-mtls/client-cert.pem similarity index 100% rename from examples-of-custom-resources/ingress-mtls/client-cert.pem rename to examples/custom-resources/ingress-mtls/client-cert.pem diff --git a/examples-of-custom-resources/ingress-mtls/client-key.pem b/examples/custom-resources/ingress-mtls/client-key.pem similarity index 100% rename from examples-of-custom-resources/ingress-mtls/client-key.pem rename to examples/custom-resources/ingress-mtls/client-key.pem diff --git a/examples-of-custom-resources/ingress-mtls/ingress-mtls-secret.yaml b/examples/custom-resources/ingress-mtls/ingress-mtls-secret.yaml similarity index 100% rename from examples-of-custom-resources/ingress-mtls/ingress-mtls-secret.yaml rename to examples/custom-resources/ingress-mtls/ingress-mtls-secret.yaml diff --git a/examples-of-custom-resources/ingress-mtls/ingress-mtls.yaml b/examples/custom-resources/ingress-mtls/ingress-mtls.yaml similarity index 100% rename from examples-of-custom-resources/ingress-mtls/ingress-mtls.yaml rename to examples/custom-resources/ingress-mtls/ingress-mtls.yaml diff --git a/examples-of-custom-resources/ingress-mtls/tls-secret.yaml b/examples/custom-resources/ingress-mtls/tls-secret.yaml similarity index 100% rename from examples-of-custom-resources/ingress-mtls/tls-secret.yaml rename to examples/custom-resources/ingress-mtls/tls-secret.yaml diff --git a/examples-of-custom-resources/ingress-mtls/virtual-server.yaml b/examples/custom-resources/ingress-mtls/virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/ingress-mtls/virtual-server.yaml rename to examples/custom-resources/ingress-mtls/virtual-server.yaml diff --git a/examples-of-custom-resources/ingress-mtls/webapp.yaml b/examples/custom-resources/ingress-mtls/webapp.yaml similarity index 100% rename from examples-of-custom-resources/ingress-mtls/webapp.yaml rename to examples/custom-resources/ingress-mtls/webapp.yaml diff --git a/examples-of-custom-resources/jwt/README.md b/examples/custom-resources/jwt/README.md similarity index 100% rename from examples-of-custom-resources/jwt/README.md rename to examples/custom-resources/jwt/README.md diff --git a/examples-of-custom-resources/jwt/jwk-secret.yaml b/examples/custom-resources/jwt/jwk-secret.yaml similarity index 100% rename from examples-of-custom-resources/jwt/jwk-secret.yaml rename to examples/custom-resources/jwt/jwk-secret.yaml diff --git a/examples-of-custom-resources/jwt/jwt.yaml b/examples/custom-resources/jwt/jwt.yaml similarity index 100% rename from examples-of-custom-resources/jwt/jwt.yaml rename to examples/custom-resources/jwt/jwt.yaml diff --git a/examples-of-custom-resources/jwt/token.jwt b/examples/custom-resources/jwt/token.jwt similarity index 100% rename from examples-of-custom-resources/jwt/token.jwt rename to examples/custom-resources/jwt/token.jwt diff --git a/examples-of-custom-resources/jwt/virtual-server.yaml b/examples/custom-resources/jwt/virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/jwt/virtual-server.yaml rename to examples/custom-resources/jwt/virtual-server.yaml diff --git a/examples-of-custom-resources/jwt/webapp.yaml b/examples/custom-resources/jwt/webapp.yaml similarity index 100% rename from examples-of-custom-resources/jwt/webapp.yaml rename to examples/custom-resources/jwt/webapp.yaml diff --git a/examples-of-custom-resources/oidc/README.md b/examples/custom-resources/oidc/README.md similarity index 100% rename from examples-of-custom-resources/oidc/README.md rename to examples/custom-resources/oidc/README.md diff --git a/examples-of-custom-resources/oidc/client-secret.yaml b/examples/custom-resources/oidc/client-secret.yaml similarity index 100% rename from examples-of-custom-resources/oidc/client-secret.yaml rename to examples/custom-resources/oidc/client-secret.yaml diff --git a/examples-of-custom-resources/oidc/keycloak.png b/examples/custom-resources/oidc/keycloak.png similarity index 100% rename from examples-of-custom-resources/oidc/keycloak.png rename to examples/custom-resources/oidc/keycloak.png diff --git a/examples-of-custom-resources/oidc/keycloak.yaml b/examples/custom-resources/oidc/keycloak.yaml similarity index 100% rename from examples-of-custom-resources/oidc/keycloak.yaml rename to examples/custom-resources/oidc/keycloak.yaml diff --git a/examples-of-custom-resources/oidc/keycloak_setup.md b/examples/custom-resources/oidc/keycloak_setup.md similarity index 100% rename from examples-of-custom-resources/oidc/keycloak_setup.md rename to examples/custom-resources/oidc/keycloak_setup.md diff --git a/examples-of-custom-resources/oidc/nginx-config.yaml b/examples/custom-resources/oidc/nginx-config.yaml similarity index 100% rename from examples-of-custom-resources/oidc/nginx-config.yaml rename to examples/custom-resources/oidc/nginx-config.yaml diff --git a/examples-of-custom-resources/oidc/nginx-ingress-headless.yaml b/examples/custom-resources/oidc/nginx-ingress-headless.yaml similarity index 100% rename from examples-of-custom-resources/oidc/nginx-ingress-headless.yaml rename to examples/custom-resources/oidc/nginx-ingress-headless.yaml diff --git a/examples-of-custom-resources/oidc/oidc.yaml b/examples/custom-resources/oidc/oidc.yaml similarity index 100% rename from examples-of-custom-resources/oidc/oidc.yaml rename to examples/custom-resources/oidc/oidc.yaml diff --git a/examples-of-custom-resources/oidc/tls-secret.yaml b/examples/custom-resources/oidc/tls-secret.yaml similarity index 100% rename from examples-of-custom-resources/oidc/tls-secret.yaml rename to examples/custom-resources/oidc/tls-secret.yaml diff --git a/examples-of-custom-resources/oidc/virtual-server-idp.yaml b/examples/custom-resources/oidc/virtual-server-idp.yaml similarity index 100% rename from examples-of-custom-resources/oidc/virtual-server-idp.yaml rename to examples/custom-resources/oidc/virtual-server-idp.yaml diff --git a/examples-of-custom-resources/oidc/virtual-server.yaml b/examples/custom-resources/oidc/virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/oidc/virtual-server.yaml rename to examples/custom-resources/oidc/virtual-server.yaml diff --git a/examples-of-custom-resources/oidc/webapp.png b/examples/custom-resources/oidc/webapp.png similarity index 100% rename from examples-of-custom-resources/oidc/webapp.png rename to examples/custom-resources/oidc/webapp.png diff --git a/examples-of-custom-resources/oidc/webapp.yaml b/examples/custom-resources/oidc/webapp.yaml similarity index 100% rename from examples-of-custom-resources/oidc/webapp.yaml rename to examples/custom-resources/oidc/webapp.yaml diff --git a/examples-of-custom-resources/rate-limit/README.md b/examples/custom-resources/rate-limit/README.md similarity index 100% rename from examples-of-custom-resources/rate-limit/README.md rename to examples/custom-resources/rate-limit/README.md diff --git a/examples-of-custom-resources/rate-limit/rate-limit.yaml b/examples/custom-resources/rate-limit/rate-limit.yaml similarity index 100% rename from examples-of-custom-resources/rate-limit/rate-limit.yaml rename to examples/custom-resources/rate-limit/rate-limit.yaml diff --git a/examples-of-custom-resources/rate-limit/virtual-server.yaml b/examples/custom-resources/rate-limit/virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/rate-limit/virtual-server.yaml rename to examples/custom-resources/rate-limit/virtual-server.yaml diff --git a/examples-of-custom-resources/rate-limit/webapp.yaml b/examples/custom-resources/rate-limit/webapp.yaml similarity index 100% rename from examples-of-custom-resources/rate-limit/webapp.yaml rename to examples/custom-resources/rate-limit/webapp.yaml diff --git a/examples-of-custom-resources/rewrites/README.md b/examples/custom-resources/rewrites/README.md similarity index 100% rename from examples-of-custom-resources/rewrites/README.md rename to examples/custom-resources/rewrites/README.md diff --git a/examples-of-custom-resources/tls-passthrough/README.md b/examples/custom-resources/tls-passthrough/README.md similarity index 100% rename from examples-of-custom-resources/tls-passthrough/README.md rename to examples/custom-resources/tls-passthrough/README.md diff --git a/examples-of-custom-resources/tls-passthrough/secure-app.yaml b/examples/custom-resources/tls-passthrough/secure-app.yaml similarity index 100% rename from examples-of-custom-resources/tls-passthrough/secure-app.yaml rename to examples/custom-resources/tls-passthrough/secure-app.yaml diff --git a/examples-of-custom-resources/tls-passthrough/transport-server-passthrough.yaml b/examples/custom-resources/tls-passthrough/transport-server-passthrough.yaml similarity index 100% rename from examples-of-custom-resources/tls-passthrough/transport-server-passthrough.yaml rename to examples/custom-resources/tls-passthrough/transport-server-passthrough.yaml diff --git a/examples-of-custom-resources/traffic-splitting/README.md b/examples/custom-resources/traffic-splitting/README.md similarity index 100% rename from examples-of-custom-resources/traffic-splitting/README.md rename to examples/custom-resources/traffic-splitting/README.md diff --git a/examples-of-custom-resources/traffic-splitting/cafe-virtual-server.yaml b/examples/custom-resources/traffic-splitting/cafe-virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/traffic-splitting/cafe-virtual-server.yaml rename to examples/custom-resources/traffic-splitting/cafe-virtual-server.yaml diff --git a/examples-of-custom-resources/traffic-splitting/cafe.yaml b/examples/custom-resources/traffic-splitting/cafe.yaml similarity index 100% rename from examples-of-custom-resources/traffic-splitting/cafe.yaml rename to examples/custom-resources/traffic-splitting/cafe.yaml diff --git a/examples-of-custom-resources/waf/README.md b/examples/custom-resources/waf/README.md similarity index 100% rename from examples-of-custom-resources/waf/README.md rename to examples/custom-resources/waf/README.md diff --git a/examples-of-custom-resources/waf/ap-apple-uds.yaml b/examples/custom-resources/waf/ap-apple-uds.yaml similarity index 100% rename from examples-of-custom-resources/waf/ap-apple-uds.yaml rename to examples/custom-resources/waf/ap-apple-uds.yaml diff --git a/examples-of-custom-resources/waf/ap-dataguard-alarm-policy.yaml b/examples/custom-resources/waf/ap-dataguard-alarm-policy.yaml similarity index 100% rename from examples-of-custom-resources/waf/ap-dataguard-alarm-policy.yaml rename to examples/custom-resources/waf/ap-dataguard-alarm-policy.yaml diff --git a/examples-of-custom-resources/waf/ap-logconf.yaml b/examples/custom-resources/waf/ap-logconf.yaml similarity index 100% rename from examples-of-custom-resources/waf/ap-logconf.yaml rename to examples/custom-resources/waf/ap-logconf.yaml diff --git a/examples-of-custom-resources/waf/syslog.yaml b/examples/custom-resources/waf/syslog.yaml similarity index 100% rename from examples-of-custom-resources/waf/syslog.yaml rename to examples/custom-resources/waf/syslog.yaml diff --git a/examples-of-custom-resources/waf/virtual-server.yaml b/examples/custom-resources/waf/virtual-server.yaml similarity index 100% rename from examples-of-custom-resources/waf/virtual-server.yaml rename to examples/custom-resources/waf/virtual-server.yaml diff --git a/examples-of-custom-resources/waf/waf.yaml b/examples/custom-resources/waf/waf.yaml similarity index 100% rename from examples-of-custom-resources/waf/waf.yaml rename to examples/custom-resources/waf/waf.yaml diff --git a/examples-of-custom-resources/waf/webapp.yaml b/examples/custom-resources/waf/webapp.yaml similarity index 100% rename from examples-of-custom-resources/waf/webapp.yaml rename to examples/custom-resources/waf/webapp.yaml