From 244f0b84965c4157b7de36bc486610cc2e28e6f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20BUISSON?= Date: Mon, 27 Jan 2025 11:21:58 +0100 Subject: [PATCH 1/3] chore: :memo: document CRDs technical choices --- README.md | 139 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 116 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index d06b10556..75f429bde 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,15 @@ Starting with v28.x, this chart now bootstraps Traefik Proxy version 3 as a Kube using Custom Resources `IngressRoute`: . It's possible to use this chart with Traefik Proxy v2 using v27.x -This chart support policy is aligned with [upstream support policy](https://doc.traefik.io/traefik/deprecation/releases/) of Traefik Proxy. +This chart support policy is aligned +with [upstream support policy](https://doc.traefik.io/traefik/deprecation/releases/) of Traefik Proxy. -See [Migration guide from v2 to v3](https://doc.traefik.io/traefik/v3.0/migration/v2-to-v3/) and upgrading section of this chart on CRDs. +See [Migration guide from v2 to v3](https://doc.traefik.io/traefik/v3.0/migration/v2-to-v3/) and upgrading section of +this chart on CRDs. -Starting with v34.x, to work around [Helm caveats](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations), it's possible to use an additional Chart dedicated to CRDs: **traefik-crds**. +Starting with v34.x, to work +around [Helm caveats](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations), +it's possible to use an additional Chart dedicated to CRDs: **traefik-crds**. ### Philosophy @@ -24,12 +28,14 @@ to avoid integrating any third party solutions nor any specific use cases. Accordingly, the encouraged approach to fulfill your needs: -1. Override the default Traefik configuration values ([yaml file or cli](https://helm.sh/docs/chart_template_guide/values_files/)) +1. Override the default Traefik configuration + values ([yaml file or cli](https://helm.sh/docs/chart_template_guide/values_files/)) 2. Append your own configurations (`kubectl apply -f myconf.yaml`) [Examples](https://github.com/traefik/traefik-helm-chart/blob/master/EXAMPLES.md) of common usage are provided. -If needed, one may use [extraObjects](./traefik/tests/values/extra.yaml) or extend this HelmChart [as a Subchart](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/). +If needed, one may use [extraObjects](./traefik/tests/values/extra.yaml) or extend this +HelmChart [as a Subchart](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/). ## Installing @@ -40,23 +46,25 @@ If needed, one may use [extraObjects](./traefik/tests/values/extra.yaml) or exte ### Kubernetes Version Support -Due to changes in CRD version support, the following versions of the chart are usable and supported on the following Kubernetes versions: +Due to changes in CRD version support, the following versions of the chart are usable and supported on the following +Kubernetes versions: -| | Kubernetes v1.15 and below | Kubernetes v1.16-v1.21 | Kubernetes v1.22 and above | -|-------------------------|-----------------------------|------------------------|----------------------------| -| Chart v9.20.2 and below | [x] | [x] | | -| Chart v10.0.0 and above | | [x] | [x] | -| Chart v22.0.0 and above | | | [x] | +| | Kubernetes v1.15 and below | Kubernetes v1.16-v1.21 | Kubernetes v1.22 and above | +|-------------------------|----------------------------|------------------------|----------------------------| +| Chart v9.20.2 and below | [x] | [x] | | +| Chart v10.0.0 and above | | [x] | [x] | +| Chart v22.0.0 and above | | | [x] | ### CRDs Support of Traefik Proxy -Due to changes in API Group of Traefik CRDs from `containo.us` to `traefik.io`, this Chart install CRDs needed by default Traefik Proxy version, following this table: +Due to changes in API Group of Traefik CRDs from `containo.us` to `traefik.io`, this Chart install CRDs needed by +default Traefik Proxy version, following this table: -| | `containo.us` | `traefik.io` | -|-------------------------|-----------------------------|------------------------| -| Chart v22.0.0 and below | [x] | | -| Chart v23.0.0 and above | [x] | [x] | -| Chart v28.0.0 and above | | [x] | +| | `containo.us` | `traefik.io` | +|-------------------------|---------------|--------------| +| Chart v22.0.0 and below | [x] | | +| Chart v23.0.0 and above | [x] | [x] | +| Chart v28.0.0 and above | | [x] | ### Deploying @@ -81,6 +89,88 @@ helm install -f myvalues.yaml traefik traefik/traefik #### With additional CRDs chart +
+ Few words on technical choices about CRDs implementation +Some Traefik Helm chart users asked us for help in managing CRDs installed by this chart (cf. #1141, #1209). +Helm doesn't support CRDs upgrades (cf. [HIP-0011](https://github.com/helm/community/blob/main/hips/hip-0011.md) for details). + +The objectives are the following: + +1. continue to support the nominal installation case +2. stay conservative about CRDs to protect resource removal (that's actually one of the reasons why helm doesn't support + CRDs upgrades) +3. allow users to install multiple instances of Traefik chart along with managed CRDs + +Several implementations have been experimented. Here are pros and cons of each: + + + + + + + + + + + + + + + + + + + + + + + + + + +
solutionproscons
templatized CRDs within Traefik helm chart +
    +
  • simple
    • +
  • users can specify only install a subset of CRDs
    • +
  • users don't have to bother with CRDs upgrades
    • +
+ 		+
    +
  • --skip-crds will be inefficient and can lost users
    • +
  • the first installation fails are CRDs are not rendered first by helm
    • +
  • when installing multiple instances, CRDs are attached to one instance
    • +
+
seperated CRDs chart as main chart dependency +
    +
  • users can specify only install a subset of CRDs
    • +
  • users don't have to bother with CRDs upgrades
    • +
  • CRDs are versioned aside from main chart
    • +
  • users can install CRDs along with multiple instances of main chart
    • +
+ 		+
    +
  • --skip-crds will be inefficient and can lost users
    • +
  • the first installation fails are CRDs are not rendered first by helm (helm doesn't respect dependency order)
    • +
  • when installing multiple instances, CRDs are attached to one instance
    • +
+
seperated CRDs chart +
    +
  • users can specify only install a subset of CRDs
    • +
  • users don't have to bother with CRDs upgrades
    • +
  • CRDs are versioned aside from main chart
    • +
  • users can install CRDs along with multiple instances of main chart
    • +
+ 		+
    +
  • --skip-crds will be inefficient and can lost users
    • +
  • the first installation fails are CRDs are not rendered first by helm
    • +
+
+ +Consequently, we decided the last option was the less disruptive. + +
+ ```bash helm install traefik-crds traefik/traefik-crds helm install traefik traefik/traefik --skip-crds @@ -98,7 +188,8 @@ New major version indicates that there is an incompatible breaking change. ### A standard installation When using Helm native management for CRDs, user **MUST** upgrade CRDs before calling _helm upgrade_ command. -CRDs are **not** updated by Helm. See [HIP-0011](https://github.com/helm/community/blob/main/hips/hip-0011.md) for details. +CRDs are **not** updated by Helm. See [HIP-0011](https://github.com/helm/community/blob/main/hips/hip-0011.md) for +details. ```bash # Update repository @@ -122,7 +213,6 @@ kubectl get customresourcedefinitions.apiextensions.k8s.io -o name | grep gatewa helm install traefik-crds traefik/traefik-crds ``` - ### An installation with additional CRDs chart ```bash @@ -138,7 +228,8 @@ helm upgrade traefik traefik/traefik ### Upgrade up to 27.X -When upgrading on Traefik Proxy v2 version, one need to stay at Traefik Helm Chart v27.x. The command to upgrade to the latest Traefik Proxy v2 CRD is: +When upgrading on Traefik Proxy v2 version, one need to stay at Traefik Helm Chart v27.x. The command to upgrade to the +latest Traefik Proxy v2 CRD is: ```bash kubectl apply --server-side --force-conflicts -k https://github.com/traefik/traefik-helm-chart/traefik/crds/?ref=v27 @@ -165,8 +256,9 @@ On HTTP/3, if you want to avoid this issue, you can set `ports.websecure.http3.advertisedPort` to an other value than `443` If you were previously using HTTP/3, you should update your values as follows: - - Replace the old value (`true`) of `ports.websecure.http3` with a key `enabled: true` - - Remove `experimental.http3.enabled=true` entry + +- Replace the old value (`true`) of `ports.websecure.http3` with a key `enabled: true` +- Remove `experimental.http3.enabled=true` entry ### Upgrading from 16.x to 17.x @@ -182,7 +274,8 @@ order to be able to upgrade. You may also upgrade by deploying another Traefik to a different namespace and removing after your first Traefik. -Alternatively, since version 20.3.0 of this chart, you may set `instanceLabelOverride` to the previous value of that label. +Alternatively, since version 20.3.0 of this chart, you may set `instanceLabelOverride` to the previous value of that +label. This will override the new `Release.Name-Release.Namespace` pattern to avoid any (longer) downtime. ## Contributing From b2c1c179c068c00d422ee28d119461c2df94ca98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20BUISSON?= Date: Wed, 29 Jan 2025 11:55:42 +0100 Subject: [PATCH 2/3] fix: apply suggestions from @mloiseleur's code review Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com> --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 75f429bde..f7d3c094e 100644 --- a/README.md +++ b/README.md @@ -91,15 +91,15 @@ helm install -f myvalues.yaml traefik traefik/traefik
Few words on technical choices about CRDs implementation -Some Traefik Helm chart users asked us for help in managing CRDs installed by this chart (cf. #1141, #1209). +Some Traefik Helm chart users asked for help in managing CRDs installed by this chart (cf. [#1141](https://github.com/traefik/traefik-helm-chart/issues/1141), [#1209](https://github.com/traefik/traefik-helm-chart/issues/1209)). Helm doesn't support CRDs upgrades (cf. [HIP-0011](https://github.com/helm/community/blob/main/hips/hip-0011.md) for details). The objectives are the following: -1. continue to support the nominal installation case -2. stay conservative about CRDs to protect resource removal (that's actually one of the reasons why helm doesn't support +1. Support the nominal installation case following official Helm GuideLines +2. Stay conservative about CRDs to protect resource removal (that's actually one of the reasons why helm doesn't support) CRDs upgrades) -3. allow users to install multiple instances of Traefik chart along with managed CRDs +3. Allow users to install multiple instances of Traefik chart along with helm managed CRDs Several implementations have been experimented. Here are pros and cons of each: From a80e636d4dfc6c7933518d68069c0b1e81f4832c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20BUISSON?= Date: Mon, 3 Feb 2025 08:35:12 +0100 Subject: [PATCH 3/3] fix: apply suggestions from @mloiseleur's code review Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com> --- README.md | 165 +++++++++++++++++++++++++++--------------------------- 1 file changed, 83 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index f7d3c094e..2960d58d0 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ Accordingly, the encouraged approach to fulfill your needs: [Examples](https://github.com/traefik/traefik-helm-chart/blob/master/EXAMPLES.md) of common usage are provided. If needed, one may use [extraObjects](./traefik/tests/values/extra.yaml) or extend this -HelmChart [as a Subchart](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/). +Helm Chart [as a Subchart](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/). ## Installing @@ -89,87 +89,88 @@ helm install -f myvalues.yaml traefik traefik/traefik #### With additional CRDs chart -
- Few words on technical choices about CRDs implementation -Some Traefik Helm chart users asked for help in managing CRDs installed by this chart (cf. [#1141](https://github.com/traefik/traefik-helm-chart/issues/1141), [#1209](https://github.com/traefik/traefik-helm-chart/issues/1209)). -Helm doesn't support CRDs upgrades (cf. [HIP-0011](https://github.com/helm/community/blob/main/hips/hip-0011.md) for details). - -The objectives are the following: - -1. Support the nominal installation case following official Helm GuideLines -2. Stay conservative about CRDs to protect resource removal (that's actually one of the reasons why helm doesn't support) - CRDs upgrades) -3. Allow users to install multiple instances of Traefik chart along with helm managed CRDs - -Several implementations have been experimented. Here are pros and cons of each: - - - - - - - - - - - - - - - - - - - - - - - - - - -
solutionproscons
templatized CRDs within Traefik helm chart -
    -
  • simple
    • -
  • users can specify only install a subset of CRDs
    • -
  • users don't have to bother with CRDs upgrades
    • -
- 		-
    -
  • --skip-crds will be inefficient and can lost users
    • -
  • the first installation fails are CRDs are not rendered first by helm
    • -
  • when installing multiple instances, CRDs are attached to one instance
    • -
-
seperated CRDs chart as main chart dependency -
    -
  • users can specify only install a subset of CRDs
    • -
  • users don't have to bother with CRDs upgrades
    • -
  • CRDs are versioned aside from main chart
    • -
  • users can install CRDs along with multiple instances of main chart
    • -
- 		-
    -
  • --skip-crds will be inefficient and can lost users
    • -
  • the first installation fails are CRDs are not rendered first by helm (helm doesn't respect dependency order)
    • -
  • when installing multiple instances, CRDs are attached to one instance
    • -
-
seperated CRDs chart -
    -
  • users can specify only install a subset of CRDs
    • -
  • users don't have to bother with CRDs upgrades
    • -
  • CRDs are versioned aside from main chart
    • -
  • users can install CRDs along with multiple instances of main chart
    • -
- 		-
    -
  • --skip-crds will be inefficient and can lost users
    • -
  • the first installation fails are CRDs are not rendered first by helm
    • -
-
- -Consequently, we decided the last option was the less disruptive. - -
+> [!NOTE] +>
+> Few words on technical choices about CRDs implementation +> Some Traefik Helm chart users asked for help in managing CRDs installed by this chart (cf. [#1141](https://github.com/traefik/traefik-helm-chart/issues/1141), [#1209](https://github.com/traefik/traefik-helm-chart/issues/1209)). +> Helm doesn't support CRDs upgrades (cf. [HIP-0011](https://github.com/helm/community/blob/main/hips/hip-0011.md) for details). +> +> The objectives are the following: +> +> 1. Support the nominal installation case following official Helm GuideLines +> 2. Stay conservative about CRDs to protect resource removal (that's actually one of the reasons why helm doesn't support) +> CRDs upgrades) +> 3. Allow users to install multiple instances of Traefik chart along with helm managed CRDs +> +> Several implementations have been experimented. Here are pros and cons of each: +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +> +>
solutionproscons
templatized CRDs within Traefik helm chart +>
    +>
  • simple
    • +>
  • users can specify only install a subset of CRDs
    • +>
  • users don't have to bother with CRDs upgrades
    • +>
+> 		+>
    +>
  • --skip-crds will be inefficient and can lost users
    • +>
  • the first installation fails are CRDs are not rendered first by helm
    • +>
  • when installing multiple instances, CRDs are attached to one instance
    • +>
+>
seperated CRDs chart as main chart dependency +>
    +>
  • users can specify only install a subset of CRDs
    • +>
  • users don't have to bother with CRDs upgrades
    • +>
  • CRDs are versioned aside from main chart
    • +>
  • users can install CRDs along with multiple instances of main chart
    • +>
+> 		+>
    +>
  • --skip-crds will be inefficient and can lost users
    • +>
  • the first installation fails are CRDs are not rendered first by helm (helm doesn't respect dependency order)
    • +>
  • when installing multiple instances, CRDs are attached to one instance
    • +>
+>
seperated CRDs chart +>
    +>
  • users can specify only install a subset of CRDs
    • +>
  • users don't have to bother with CRDs upgrades
    • +>
  • CRDs are versioned aside from main chart
    • +>
  • users can install CRDs along with multiple instances of main chart
    • +>
+> 		+>
    +>
  • --skip-crds will be inefficient and can lost users
    • +>
  • the first installation fails are CRDs are not rendered first by helm
    • +>
+>
+> +> Consequently, we decided the last option was the less disruptive. +> +>
```bash helm install traefik-crds traefik/traefik-crds