diff --git a/content/nic/configuration/global-configuration/command-line-arguments.md b/content/nic/configuration/global-configuration/command-line-arguments.md index 5196f28ff..5345ae561 100644 --- a/content/nic/configuration/global-configuration/command-line-arguments.md +++ b/content/nic/configuration/global-configuration/command-line-arguments.md @@ -32,6 +32,8 @@ Secret with a TLS certificate and key for TLS termination of the default server. Format: `/` +When `-allow-empty-ingress-host` is enabled, this secret also provides TLS for Ingress resources without a `host`. + ### -wildcard-tls-secret `` @@ -165,6 +167,16 @@ Default `nginx`. Path to the ingress NGINX configuration template for an ingress resource. Default for NGINX is `nginx.ingress.tmpl`; default for NGINX Plus is `nginx-plus.ingress.tmpl`. +### -allow-empty-ingress-host {#cmdoption-allow-empty-ingress-host} + +Allows Ingress resources to omit the `host` field. + +Default `false`. + +If multiple Ingress resources without a `host` conflict, NGINX Ingress Controller resolves the collision using the [winner selection algorithm]({{< ref "/nic/configuration/host-and-listener-collisions.md" >}}). To use multiple Ingress resources without a `host` across namespaces without conflict, use [mergeable Ingress]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}). + +To configure TLS, use the command-line argument [`-default-server-tls-secret`](#cmdoption-default-server-tls-secret). To configure listener ports, use the command-line arguments [`-default-http-listener-port`](#cmdoption-default-http-listener-port) or [`-default-https-listener-port`](#cmdoption-default-https-listener-port). + ### -leader-election-lock-name `` @@ -509,6 +521,8 @@ Sets the port for the HTTP `default_server` listener. Default `80`. +When [-allow-empty-ingress-host](#cmdoption-allow-empty-ingress-host) is enabled, also configures the HTTP listener port for Ingress resources without a `host`. + ### -default-https-listener-port @@ -517,6 +531,8 @@ Sets the port for the HTTPS `default_server` listener. Default `443`. +When [-allow-empty-ingress-host](#cmdoption-allow-empty-ingress-host) is enabled, also configures the HTTPS listener port for Ingress resources without a `host`. + ### -ssl-dynamic-reload diff --git a/content/nic/configuration/global-configuration/configmap-resource.md b/content/nic/configuration/global-configuration/configmap-resource.md index ddef16e08..a7e608b3c 100644 --- a/content/nic/configuration/global-configuration/configmap-resource.md +++ b/content/nic/configuration/global-configuration/configmap-resource.md @@ -77,7 +77,7 @@ For more information, view the [VirtualServer and VirtualServerRoute resources]( |*set-real-ip-from* | Sets the value of the [set_real_ip_from](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | |*real-ip-header* | Sets the value of the [real_ip_header](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | *X-Real-IP* | | |*real-ip-recursive* | Enables or disables the [real_ip_recursive](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive) directive. | *False* | | -|*default-server-return* | Configures the [return](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return) directive in the default server, which handles a client request if none of the hosts of Ingress or VirtualServer resources match. The default value configures NGINX to return a 404 error page. You can configure a fixed response or a redirect. For example, *default-server-return: 302 https://nginx.org* will redirect a client to *https://nginx.org*. | *404* | | +|*default-server-return* | Configures the [return](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return) directive in the default server, which handles a client request if none of the hosts of Ingress or VirtualServer resources match. The default value configures NGINX to return a 404 error page. You can configure a fixed response or a redirect. For example, *default-server-return: 302 https://nginx.org* will redirect a client to *https://nginx.org*. When [-allow-empty-ingress-host](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-allow-empty-ingress-host) is enabled and an empty-host Ingress is active, this directive applies to requests that do not match any Ingress path, unless the Ingress defines a `/` path or `spec.defaultBackend`. | *404* | | |*server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. | *True* | | |*worker-processes* | Sets the value of the [worker_processes](https://nginx.org/en/docs/ngx_core_module.html#worker_processes) directive. | *auto* | | |*worker-rlimit-nofile* | Sets the value of the [worker_rlimit_nofile](https://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile) directive. | N/A | | diff --git a/content/nic/configuration/host-and-listener-collisions.md b/content/nic/configuration/host-and-listener-collisions.md index 633dd740b..3099574f4 100644 --- a/content/nic/configuration/host-and-listener-collisions.md +++ b/content/nic/configuration/host-and-listener-collisions.md @@ -21,7 +21,7 @@ If multiple resources contend for the same host or listener, NGINX Ingress Contr ## Host collisions -A host collision occurs when multiple Ingress, VirtualServer, and TransportServer (configured for TLS Passthrough) resources configure the same `host`. NGINX Ingress Controller has two strategies for handling host collisions: +A host collision occurs when multiple Ingress, VirtualServer, and TransportServer (configured for TLS Passthrough) resources configure the same `host`. When [`-allow-empty-ingress-host`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-allow-empty-ingress-host" >}}) is enabled, multiple Ingress resources without a `host` also constitute a host collision for the default server slot. NGINX Ingress Controller has two strategies for handling host collisions: - Choosing a single "winner" resource to handle the host. - Merging the configuration of the conflicting resources. diff --git a/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md b/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md index bc0972e4a..01e93eeca 100644 --- a/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -169,8 +169,8 @@ The table below summarizes the available annotations. | Annotation | ConfigMap Key | Description | Default | | ---| ---| ---| ---| -| *nginx.org/listen-ports* | N/A | Configures HTTP ports that NGINX will listen on. | *[80]* | -| *nginx.org/listen-ports-ssl* | N/A | Configures HTTPS ports that NGINX will listen on. | *[443]* | +| *nginx.org/listen-ports* | N/A | Configures HTTP ports that NGINX will listen on. Not supported on Ingress resources without a `host`; use the `-default-http-listener-port` command-line argument instead. | *[80]* | +| *nginx.org/listen-ports-ssl* | N/A | Configures HTTPS ports that NGINX will listen on. Not supported on Ingress resources without a `host`; use the `-default-https-listener-port` command-line argument instead. | *[443]* | ### Backend services (Upstreams) diff --git a/content/nic/configuration/ingress-resources/basic-configuration.md b/content/nic/configuration/ingress-resources/basic-configuration.md index d1f84bd78..968eb2fc3 100644 --- a/content/nic/configuration/ingress-resources/basic-configuration.md +++ b/content/nic/configuration/ingress-resources/basic-configuration.md @@ -80,7 +80,8 @@ Starting from Kubernetes 1.18, you can use the following new features: NGINX Ingress Controller imposes the following restrictions on Ingress resources: -- When defining an Ingress resource, the `host` field is required. +- The `host` field is required by default. To allow Ingress resources to omit the `host` field, use the [`-allow-empty-ingress-host`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-allow-empty-ingress-host" >}}) command-line argument. +- When `-allow-empty-ingress-host` is enabled, `spec.tls` is not supported on Ingress resources without a `host`. To configure TLS, use the [`-default-server-tls-secret`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-default-server-tls-secret" >}}) command-line argument instead. - The `host` value needs to be unique among all Ingress and VirtualServer resources unless the Ingress resource is a [mergeable minion]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}). View the [Host and Listener collisions]({{< ref "/nic/configuration/host-and-listener-collisions.md" >}}) topic for more information. - The `path` field in `spec.rules[].http.paths[]` is required for `Exact` and `Prefix` `pathTypes`. - The ImplementationSpecific `pathType` is treated as equivalent to `Prefix` `pathType`, with the exception that when this `pathType` is configured, the `path` field in `spec.rules[].http.paths[]` is not mandatory. `path` defaults to `/` if not set but the `pathType` is set to ImplementationSpecific. diff --git a/content/nic/configuration/ingress-resources/cross-namespace-configuration.md b/content/nic/configuration/ingress-resources/cross-namespace-configuration.md index 5982b481f..9e065266e 100644 --- a/content/nic/configuration/ingress-resources/cross-namespace-configuration.md +++ b/content/nic/configuration/ingress-resources/cross-namespace-configuration.md @@ -9,6 +9,6 @@ nd-docs: DOCS-594 This topic explains how to spread Ingress configuration across different namespaces in F5 NGINX Ingress Controller. -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/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/mergeable-ingress-types) example in our GitHub repo. +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/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/mergeable-ingress-types) example in our GitHub repo. When [`-allow-empty-ingress-host`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-allow-empty-ingress-host" >}}) is enabled, this also applies to Ingress resources without a `host`. As an alternative to Mergeable Ingress resources, you can use [VirtualServer and VirtualServerRoute resources]({{< ref "/nic//configuration/virtualserver-and-virtualserverroute-resources.md" >}}) for cross-namespace configuration. See the [Cross-Namespace Configuration](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/cross-namespace-configuration) example in our GitHub repo. diff --git a/content/nic/install/helm/parameters.md b/content/nic/install/helm/parameters.md index 0611e2294..4eef7fbec 100644 --- a/content/nic/install/helm/parameters.md +++ b/content/nic/install/helm/parameters.md @@ -62,7 +62,7 @@ The [values.schema.json](https://github.com/nginx/kubernetes-ingress/blob/main/c | **controller.customPorts** | A list of custom ports to expose on the NGINX Ingress Controller pod. Follows the conventional Kubernetes yaml syntax for container ports. | [] | | **controller.defaultTLS.cert** | The base64-encoded TLS certificate for the default HTTPS server. **Note:** It is recommended that you specify your own certificate. Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. | | **controller.defaultTLS.key** | The base64-encoded TLS key for the default HTTPS server. **Note:** It is recommended that you specify your own key. Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. | -| **controller.defaultTLS.secret** | The secret with a TLS certificate and key for the default HTTPS server. The value must follow the following format: `/`. Used as an alternative to specifying a certificate and key using `controller.defaultTLS.cert` and `controller.defaultTLS.key` parameters. **Note:** Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. | None | +| **controller.defaultTLS.secret** | The secret with a TLS certificate and key for the default HTTPS server. The value must follow the following format: `/`. Used as an alternative to specifying a certificate and key using `controller.defaultTLS.cert` and `controller.defaultTLS.key` parameters. **Note:** Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. When `controller.allowEmptyIngressHost` is enabled, this secret also provides TLS for Ingress resources without a `host`. | None | | **controller.wildcardTLS.cert** | The base64-encoded TLS certificate for every Ingress/VirtualServer host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. | None | | **controller.wildcardTLS.key** | The base64-encoded TLS key for every Ingress/VirtualServer host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. | None | | **controller.wildcardTLS.secret** | The secret with a TLS certificate and key for every Ingress/VirtualServer host that has TLS enabled but no secret specified. The value must follow the following format: `/`. Used as an alternative to specifying a certificate and key using `controller.wildcardTLS.cert` and `controller.wildcardTLS.key` parameters. | None | @@ -190,8 +190,9 @@ The [values.schema.json](https://github.com/nginx/kubernetes-ingress/blob/main/c | **controller.statefulset.nginxCachePVC.storageClass** | The storage class for the persistent volume claim. Only applies when `controller.kind` is set to `statefulset`. | `""` | | **controller.statefulset.nginxCachePVC.accessModes** | The access modes for the persistent volume claim. Only applies when `controller.kind` is set to `statefulset`. | `["ReadWriteOnce"]` | | **controller.disableIPV6** | Disable IPV6 listeners explicitly for nodes that do not support the IPV6 stack. | false | -| **controller.defaultHTTPListenerPort** | Sets the port for the HTTP `default_server` listener. | 80 | -| **controller.defaultHTTPSListenerPort** | Sets the port for the HTTPS `default_server` listener. | 443 | +| **controller.defaultHTTPListenerPort** | Sets the port for the HTTP `default_server` listener. When `controller.allowEmptyIngressHost` is enabled, also configures the HTTP listener port for Ingress resources without a `host`. | 80 | +| **controller.defaultHTTPSListenerPort** | Sets the port for the HTTPS `default_server` listener. When `controller.allowEmptyIngressHost` is enabled, also configures the HTTPS listener port for Ingress resources without a `host`. | 443 | +| **controller.allowEmptyIngressHost** | Allows Ingress resources to omit the `host` field. `spec.tls` is not supported on Ingress resources without a `host`; use `controller.defaultTLS.secret` instead. `nginx.org/listen-ports` and `nginx.org/listen-ports-ssl` annotations are not supported; use `controller.defaultHTTPListenerPort` and `controller.defaultHTTPSListenerPort` instead. | false | | **controller.readOnlyRootFilesystem** | Configure root filesystem as read-only and add volumes for temporary data. Three major releases after 3.5.x this argument will be moved permanently to the `controller.securityContext` section. | false | | **controller.enableSSLDynamicReload** | Enable lazy loading for SSL Certificates. | true | | **controller.telemetryReporting.enable** | Enable telemetry reporting. | true | diff --git a/content/nic/install/upgrade.md b/content/nic/install/upgrade.md index ab6abb83d..d58b9a4c5 100644 --- a/content/nic/install/upgrade.md +++ b/content/nic/install/upgrade.md @@ -312,3 +312,40 @@ Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set {{% /tab %}} {{< /tabs >}} + +## Custom NGINX templates + +If you use custom NGINX configuration templates, review and apply any upstream template changes before upgrading. For more information, see [Custom templates]({{< ref "/nic/configuration/global-configuration/custom-templates.md" >}}). + +{{< call-out "warning" "Upgrading to version 5.5 or later">}} +In version 5.5, the default server block was removed from `main-template` and is now generated by `ingress-template`. You must update both templates before upgrading. If you had customizations inside the default server block in your `main-template`, the patch will remove them. Migrate those changes to your `ingress-template` manually. +{{< /call-out >}} + +1. Clone the repository: + + ```shell + git clone https://github.com/nginx/kubernetes-ingress.git + ``` + +2. Generate a diff between the version you are upgrading from and the version you are upgrading to. For `main-template` and `ingress-template`, use `version1`. For `virtualserver-template` and `transportserver-template`, use `version2`: + + ```shell + git diff v..v -- internal/configs/version1/ > upstream.patch + git diff v..v -- internal/configs/version2/ > upstream.patch + ``` + +3. Extract your custom template from the ConfigMap to a local file. The valid key names are `main-template`, `ingress-template`, `virtualserver-template`, and `transportserver-template`: + + ```shell + kubectl get configmap -n nginx-ingress -o jsonpath='{.data.}' > my-template.tmpl + ``` + +4. Apply the patch to your custom template: + + ```shell + patch my-template.tmpl < upstream.patch + ``` + + If the patch fails to apply some changes, review the rejected changes in `my-template.tmpl.rej` and apply them by manually. + +5. Update the template key with the patched content. If you manage your ConfigMap directly, update the relevant key in your manifest and run `kubectl apply -f `. If you use Helm, set the key under `controller.config.entries` in your values file and run `helm upgrade`.