From 7230699ff48f1b941383d4c32714c315e09c61af Mon Sep 17 00:00:00 2001 From: Paul Abel Date: Tue, 16 Dec 2025 15:53:08 +0000 Subject: [PATCH 1/2] fix: Update NIC OIDC template configmap customisation --- content/nic/changelog/_index.md | 9 +++-- .../tutorials/oidc-custom-configuration.md | 38 ++++++++++--------- 2 files changed, 26 insertions(+), 21 deletions(-) diff --git a/content/nic/changelog/_index.md b/content/nic/changelog/_index.md index 73c1592e1..85ee777db 100644 --- a/content/nic/changelog/_index.md +++ b/content/nic/changelog/_index.md @@ -24,12 +24,12 @@ For older releases, check the changelogs for previous years: [2024]({{< ref "/ni {{< /details >}} - ## 5.3.0 09 Dec 2025 ### {{% icon rocket %}} Features + - [8292](https://github.com/nginx/kubernetes-ingress/pull/8292) Add sslverify for jwksuri - [8447](https://github.com/nginx/kubernetes-ingress/pull/8447) Add support for ssl ciphers related annotations - [8340](https://github.com/nginx/kubernetes-ingress/pull/8340) Implement oidc front channel logout nginx directives @@ -42,10 +42,12 @@ For older releases, check the changelogs for previous years: [2024]({{< ref "/ni - [8533](https://github.com/nginx/kubernetes-ingress/pull/8533) Extend cache policy for more configurable parameters ### {{% icon bug %}} Fixes + - [8299](https://github.com/nginx/kubernetes-ingress/pull/8299) Remove type field for objects with schema ref - [8455](https://github.com/nginx/kubernetes-ingress/pull/8455) Cleanup stale socket files on startup ### {{% icon arrow-up %}} Dependencies + - [8553](https://github.com/nginx/kubernetes-ingress/pull/8553) Bump Go dependencies - [8244](https://github.com/nginx/kubernetes-ingress/pull/8244), [8279](https://github.com/nginx/kubernetes-ingress/pull/8279), [8284](https://github.com/nginx/kubernetes-ingress/pull/8284), [8595](https://github.com/nginx/kubernetes-ingress/pull/8595), [8584](https://github.com/nginx/kubernetes-ingress/pull/8584), [8315](https://github.com/nginx/kubernetes-ingress/pull/8315), [8324](https://github.com/nginx/kubernetes-ingress/pull/8324), [8334](https://github.com/nginx/kubernetes-ingress/pull/8334), [8466](https://github.com/nginx/kubernetes-ingress/pull/8466), [8384](https://github.com/nginx/kubernetes-ingress/pull/8384), [8502](https://github.com/nginx/kubernetes-ingress/pull/8502), [8406](https://github.com/nginx/kubernetes-ingress/pull/8406), [8588](https://github.com/nginx/kubernetes-ingress/pull/8588), [8589](https://github.com/nginx/kubernetes-ingress/pull/8589), [8598](https://github.com/nginx/kubernetes-ingress/pull/8598), [8575](https://github.com/nginx/kubernetes-ingress/pull/8575), [8542](https://github.com/nginx/kubernetes-ingress/pull/8542), [8543](https://github.com/nginx/kubernetes-ingress/pull/8543), [8599](https://github.com/nginx/kubernetes-ingress/pull/8599), [8551](https://github.com/nginx/kubernetes-ingress/pull/8551), [8484](https://github.com/nginx/kubernetes-ingress/pull/8484), [8475](https://github.com/nginx/kubernetes-ingress/pull/8475), [8497](https://github.com/nginx/kubernetes-ingress/pull/8497), [8498](https://github.com/nginx/kubernetes-ingress/pull/8498), [8499](https://github.com/nginx/kubernetes-ingress/pull/8499), [8596](https://github.com/nginx/kubernetes-ingress/pull/8596), [8511](https://github.com/nginx/kubernetes-ingress/pull/8511) & [8581](https://github.com/nginx/kubernetes-ingress/pull/8581) Bump Docker dependencies - [8616](https://github.com/nginx/kubernetes-ingress/pull/8616) Update dependency go to v1.25.5 (main) @@ -53,14 +55,15 @@ For older releases, check the changelogs for previous years: [2024]({{< ref "/ni - [8494](https://github.com/nginx/kubernetes-ingress/pull/8494) Update nginx to 1.29.3, nginx agent to 3.5 - [8600](https://github.com/nginx/kubernetes-ingress/pull/8600) Update nginx plus waf pkg and alpine base version - - ### {{% icon download %}} Upgrade + - For NGINX, use the 5.3.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=5.3.0), [GitHub Container](https://github.com/nginx/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress). - For NGINX Plus, use the 5.3.0 images from the F5 Container registry or build your own image using the 5.3.0 source code. - For Helm, use version 2.4.0 of the chart. +- For users making use of a custom `oidc.conf` by following this [guide]({{< ref "/nic/tutorials/oidc-custom-configuration.md" >}}), in this release this behaviour has changed from a static file to a template. The [guide]({{< ref "/nic/tutorials/oidc-custom-configuration.md" >}}) has been updated to reflect the recent changes. ### {{% icon life-buoy %}} Supported Platforms + We will provide technical support for NGINX Ingress Controller on any Kubernetes platform that is currently supported by its provider and that passes the Kubernetes conformance tests. This release was fully tested on the following Kubernetes versions: 1.27-1.34. ## 5.2.1 diff --git a/content/nic/tutorials/oidc-custom-configuration.md b/content/nic/tutorials/oidc-custom-configuration.md index d665fdb4e..240ab6ff6 100644 --- a/content/nic/tutorials/oidc-custom-configuration.md +++ b/content/nic/tutorials/oidc-custom-configuration.md @@ -13,24 +13,24 @@ This guide will walk through how to customize and configure this default impleme ## Prerequisites -{{< call-out "note" >}}This guide only works with F5 NGINX Ingress Controller version 5.2.1 or below. Please make sure you are using a compatible version before proceeding.{{< /call-out >}} +{{< call-out "note" >}}This guide only works with F5 NGINX Ingress Controller version 5.3.0 or above. Please make sure you are using a compatible version before proceeding.{{< /call-out >}} This guide assumes that you have an F5 NGINX Ingress Controller deployed. If not, please follow the installation steps using either the [Manifest]({{< ref "/nic/install/manifests.md" >}}) or [Helm]({{< ref "/nic/install/helm.md" >}}) approach. To customize the NGINX OpenID Connect Reference implementation, you will need to: -1. Create a ConfigMap containing the contents of the default `oidc.conf` file +1. Create a ConfigMap containing the contents of the default `oidc.tmpl` file 2. Attach a `Volume` and `VolumeMount` to your deployment of the F5 NGINX Ingress Controller -This setup will allow the custom configuration in your ConfigMap to override the contents of the default `oidc.conf` file. +This setup will allow the custom configuration in your ConfigMap to override the contents of the default `oidc.tmpl` file. ## Step 1 - Creating the ConfigMap -Run the below command to generate a ConfigMap with the contents of the `oidc.conf` file. +Run the below command to generate a ConfigMap with the contents of the `oidc.tmpl` file. **NOTE** The ConfigMap must be deployed in the same `namespace` as the F5 NGINX Ingress Controller. ```console -kubectl create configmap oidc-config-map --from-literal=oidc.conf="$(curl -k https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/internal/configs/oidc/oidc.conf)" +kubectl create configmap oidc-config-map --from-literal=oidc.tmpl="$(curl -k https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/internal/configs/version2/oidc.tmpl)" ``` Use the `kubectl describe` command to confirm the contents of the ConfigMap are correct. @@ -47,11 +47,12 @@ Annotations: Data ==== -oidc.conf: +oidc.tmpl: ---- # Advanced configuration START set $internal_error_message "NGINX / OpenID Connect login failure\n"; set $pkce_id ""; + set $idp_sid ""; # resolver 8.8.8.8; # For DNS lookup of IdP endpoints; subrequest_output_buffer_size 32k; # To fit a complete tokenset response gunzip on; # Decompress IdP responses if necessary @@ -63,8 +64,8 @@ oidc.conf: ## Step 2 - Customizing the default configuration -Once the contents of the `oidc.conf` file has been added to the ConfigMap, you are free to customize the contents of this ConfigMap. -This example demonstrates adding a comment to the top of the file. The comment will be shown at the top of the `oidc.conf` file. +Once the contents of the `oidc.tmpl` file has been added to the ConfigMap, you are free to customize the contents of this ConfigMap. +This example demonstrates adding a comment to the top of the file. The comment will be shown at the top of the `oidc.tmpl` file. This comment will be `# >> Custom Comment for my OIDC file <<` ```shell @@ -80,11 +81,12 @@ Add the custom content: # apiVersion: v1 data: - oidc.conf: |2- + oidc.tmpl: |2- # >> Custom Comment for my OIDC file << # Advanced configuration START set $internal_error_message "NGINX / OpenID Connect login failure\n"; set $pkce_id ""; + set $idp_sid ""; # resolver 8.8.8.8; # For DNS lookup of IdP endpoints; subrequest_output_buffer_size 32k; # To fit a complete tokenset response gunzip on; # Decompress IdP responses if necessary @@ -107,7 +109,7 @@ Applying any updates to the data in this ConfigMap will require NGINX Ingress Co ## Step 3 - Add Volume and VolumeMount to the Ingress Controller deployment In this step we will add a `Volume` and `VolumeMount` to the NGINX Ingress Controller deployment. -This will allow you to mount the ConfigMap created in Step 1 and overwrite the contents of the `oidc.conf` file. +This will allow you to mount the ConfigMap created in Step 1 and overwrite the contents of the `oidc.tmpl` file. This document will demonstrate how to add the `Volume` and `VolumeMount` using both Manifest and HELM @@ -143,17 +145,17 @@ spec: ... volumeMounts: - name: oidc-volume - mountPath: /etc/nginx/oidc/oidc.conf - subPath: oidc.conf # Must match the name in the data filed + mountPath: /oidc.tmpl + subPath: oidc.tmpl # Must match the name in the data filed readOnly: true ``` Once the `Volume` and `VolumeMount` has been added the manifest file, apply the changes to the Ingress Controller deployment. -Confirm the `oidc.conf` file has been updated: +Confirm the `oidc.tmpl` file has been updated: ```shell -kubectl exec -it -n -- cat /etc/nginx/oidc/oidc.conf +kubectl exec -it -n -- cat /oidc.tmpl ``` ### Helm @@ -207,15 +209,15 @@ spec: ... volumeMounts: - name: oidc-volume - mountPath: /etc/nginx/oidc/oidc.conf - subPath: oidc.conf # Must match the name in the data filed + mountPath: /oidc.tmpl + subPath: oidc.tmpl # Must match the name in the data filed readOnly: true ``` Once the Deployment/DaemonSet/StatefulSet has been edited, save the file and exit. -Confirm the `oidc.conf` file has been updated: +Confirm the `oidc.tmpl` file has been updated: ```shell -kubectl exec -it -n -- cat /etc/nginx/oidc/oidc.conf +kubectl exec -it -n -- cat /oidc.tmpl ``` From 119c6f7bacc408aceb654b4fd5093d7dcf2d65bc Mon Sep 17 00:00:00 2001 From: Paul Abel Date: Tue, 16 Dec 2025 16:28:44 +0000 Subject: [PATCH 2/2] chore: advise users to copy existing modifications --- content/nic/changelog/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/changelog/_index.md b/content/nic/changelog/_index.md index 85ee777db..09612d4b0 100644 --- a/content/nic/changelog/_index.md +++ b/content/nic/changelog/_index.md @@ -60,7 +60,7 @@ For older releases, check the changelogs for previous years: [2024]({{< ref "/ni - For NGINX, use the 5.3.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=5.3.0), [GitHub Container](https://github.com/nginx/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress). - For NGINX Plus, use the 5.3.0 images from the F5 Container registry or build your own image using the 5.3.0 source code. - For Helm, use version 2.4.0 of the chart. -- For users making use of a custom `oidc.conf` by following this [guide]({{< ref "/nic/tutorials/oidc-custom-configuration.md" >}}), in this release this behaviour has changed from a static file to a template. The [guide]({{< ref "/nic/tutorials/oidc-custom-configuration.md" >}}) has been updated to reflect the recent changes. +- For users making use of a custom `oidc.conf` by following this [guide]({{< ref "/nic/tutorials/oidc-custom-configuration.md" >}}), in this release this behaviour has changed from a static file (`oidc.conf`) to a dynamic template (`oidc.tmpl`). The [guide]({{< ref "/nic/tutorials/oidc-custom-configuration.md" >}}) has been updated to reflect the recent changes. If you still require a custom OIDC configuration, you should copy all the modifications you have made prior to 5.3.0 to the `oidc.tmpl` in the `ConfigMap`. ### {{% icon life-buoy %}} Supported Platforms