From cd6a405d23fd0ecc9ed7c31204128a9184d40bd6 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 6 May 2026 00:38:29 +0100 Subject: [PATCH 1/5] feat: Add empty-host Ingress documentation Update documentation for Ingress resources without a host field: - Update command-line-arguments.md with listener port notes - Update configmap-resource.md with default-server-return interaction - Update upgrade.md with custom templates section --- .../command-line-arguments.md | 18 +++++++++++ .../configmap-resource.md | 2 +- ...advanced-configuration-with-annotations.md | 4 +-- .../ingress-resources/basic-configuration.md | 2 +- content/nic/install/helm/parameters.md | 7 ++-- content/nic/install/upgrade.md | 32 +++++++++++++++++++ 6 files changed, 58 insertions(+), 7 deletions(-) diff --git a/content/nic/configuration/global-configuration/command-line-arguments.md b/content/nic/configuration/global-configuration/command-line-arguments.md index 5196f28ff4..78a4b3e3c7 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,18 @@ 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 + +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 +523,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 +533,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 ddef16e08a..a7e608b3cd 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/ingress-resources/advanced-configuration-with-annotations.md b/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md index bc0972e4ac..01e93eecab 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 d1f84bd78e..c5811eaeb9 100644 --- a/content/nic/configuration/ingress-resources/basic-configuration.md +++ b/content/nic/configuration/ingress-resources/basic-configuration.md @@ -80,7 +80,7 @@ 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. - 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/install/helm/parameters.md b/content/nic/install/helm/parameters.md index 0611e22942..4eef7fbec9 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 ab6abb83d9..58064da437 100644 --- a/content/nic/install/upgrade.md +++ b/content/nic/install/upgrade.md @@ -312,3 +312,35 @@ 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" >}}). + +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: + + ```shell + git diff v..v -- internal/configs/ > 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 any hunks fail, review `my-template.tmpl.rej` and apply those changes 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`. From cd5da4f6e3fa2a779554e22234982a667a360c4e Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Tue, 12 May 2026 11:38:48 +0100 Subject: [PATCH 2/5] update docs Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- content/nic/configuration/host-and-listener-collisions.md | 2 +- .../configuration/ingress-resources/basic-configuration.md | 1 + .../ingress-resources/cross-namespace-configuration.md | 2 +- content/nic/install/upgrade.md | 6 +++++- 4 files changed, 8 insertions(+), 3 deletions(-) diff --git a/content/nic/configuration/host-and-listener-collisions.md b/content/nic/configuration/host-and-listener-collisions.md index 633dd740b4..3099574f44 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/basic-configuration.md b/content/nic/configuration/ingress-resources/basic-configuration.md index c5811eaeb9..968eb2fc36 100644 --- a/content/nic/configuration/ingress-resources/basic-configuration.md +++ b/content/nic/configuration/ingress-resources/basic-configuration.md @@ -81,6 +81,7 @@ Starting from Kubernetes 1.18, you can use the following new features: NGINX Ingress Controller imposes the following restrictions on Ingress resources: - 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 5982b481f9..9e065266eb 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/upgrade.md b/content/nic/install/upgrade.md index 58064da437..664661b7f0 100644 --- a/content/nic/install/upgrade.md +++ b/content/nic/install/upgrade.md @@ -317,6 +317,10 @@ Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set 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:** Starting in version 5.5, the default server is generated as a separate include file (`conf.d/_default-server.conf`). If your custom `main-template` was created before version 5.5 and contains a `default_server` server block, remove that block when patching your template. Keeping it produces a duplicate `default_server` nginx configuration error at startup. This applies regardless of whether you enable `-allow-empty-ingress-host`. +{{< /call-out >}} + 1. Clone the repository: ```shell @@ -326,7 +330,7 @@ If you use custom NGINX configuration templates, review and apply any upstream t 2. Generate a diff between the version you are upgrading from and the version you are upgrading to: ```shell - git diff v..v -- internal/configs/ > upstream.patch + git diff v..v -- internal/configs/version1/ > 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`: From b7a6a29cdb63550f9b617691c051a5fabcec454e Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Tue, 12 May 2026 13:15:08 +0100 Subject: [PATCH 3/5] update docs Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- content/nic/install/upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/install/upgrade.md b/content/nic/install/upgrade.md index 664661b7f0..b7a446a1b6 100644 --- a/content/nic/install/upgrade.md +++ b/content/nic/install/upgrade.md @@ -318,7 +318,7 @@ Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set 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:** Starting in version 5.5, the default server is generated as a separate include file (`conf.d/_default-server.conf`). If your custom `main-template` was created before version 5.5 and contains a `default_server` server block, remove that block when patching your template. Keeping it produces a duplicate `default_server` nginx configuration error at startup. This applies regardless of whether you enable `-allow-empty-ingress-host`. +**Upgrading to version 5.5 or later:** Starting in version 5.5, the default server is generated as a separate include file (`conf.d/_default-server.conf`). If you have custom `main-template` or `ingress-template`, you must update both to match the upstream versions before upgrading. Follow the procedure below to review and apply the upstream changes. {{< /call-out >}} 1. Clone the repository: From bd7a33a5a090d8b170c7786941eef3a1e2f02ef4 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Tue, 12 May 2026 15:42:49 +0100 Subject: [PATCH 4/5] simplify wording Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- content/nic/install/upgrade.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/content/nic/install/upgrade.md b/content/nic/install/upgrade.md index b7a446a1b6..9635727d89 100644 --- a/content/nic/install/upgrade.md +++ b/content/nic/install/upgrade.md @@ -318,7 +318,7 @@ Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set 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:** Starting in version 5.5, the default server is generated as a separate include file (`conf.d/_default-server.conf`). If you have custom `main-template` or `ingress-template`, you must update both to match the upstream versions before upgrading. Follow the procedure below to review and apply the upstream changes. +**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: @@ -327,10 +327,11 @@ If you use custom NGINX configuration templates, review and apply any upstream t 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: +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`: @@ -345,6 +346,6 @@ If you use custom NGINX configuration templates, review and apply any upstream t patch my-template.tmpl < upstream.patch ``` - If any hunks fail, review `my-template.tmpl.rej` and apply those changes manually. + 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`. From d9b4bd937b883a1c8a7bdffdd6f76e22216556d7 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 13 May 2026 16:04:54 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- .../global-configuration/command-line-arguments.md | 4 +--- content/nic/install/upgrade.md | 4 ++-- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/content/nic/configuration/global-configuration/command-line-arguments.md b/content/nic/configuration/global-configuration/command-line-arguments.md index 78a4b3e3c7..5345ae561b 100644 --- a/content/nic/configuration/global-configuration/command-line-arguments.md +++ b/content/nic/configuration/global-configuration/command-line-arguments.md @@ -167,9 +167,7 @@ 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 +### -allow-empty-ingress-host {#cmdoption-allow-empty-ingress-host} Allows Ingress resources to omit the `host` field. diff --git a/content/nic/install/upgrade.md b/content/nic/install/upgrade.md index 9635727d89..d58b9a4c58 100644 --- a/content/nic/install/upgrade.md +++ b/content/nic/install/upgrade.md @@ -317,8 +317,8 @@ Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set 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 "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: