docs: update CRD note in upgrade guide

aws · Dec 2, 2024 · f3237bc · f3237bc
1 parent b2fcf44
commit f3237bc
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 9 deletions.
diff --git a/website/content/en/docs/upgrading/upgrade-guide.md b/website/content/en/docs/upgrading/upgrade-guide.md
@@ -17,18 +17,22 @@ With the release of Karpenter v1.0.0, the Karpenter team will be dropping suppor
 ### CRD Upgrades
 
 Karpenter ships with a few Custom Resource Definitions (CRDs). These CRDs are published:
-* As an independent Helm chart [karpenter-crd](https://gallery.ecr.aws/karpenter/karpenter-crd) - [source](https://github.com/aws/karpenter/blob/main/charts/karpenter-crd) that can be used by Helm to manage the lifecycle of these CRDs. To upgrade or install `karpenter-crd` run:
+* As an independent Helm chart [karpenter-crd](https://gallery.ecr.aws/karpenter/karpenter-crd) ([source](https://github.com/aws/karpenter/blob/main/charts/karpenter-crd)) that can be used by Helm to manage the lifecycle of these CRDs. To upgrade or install `karpenter-crd` run:
   ```bash
   KARPENTER_NAMESPACE=kube-system
   helm upgrade --install karpenter-crd oci://public.ecr.aws/karpenter/karpenter-crd --version x.y.z --namespace "${KARPENTER_NAMESPACE}" --create-namespace
   ```
+* As part of the helm chart [karpenter](https://gallery.ecr.aws/karpenter/karpenter) ([source](https://github.com/aws/karpenter/blob/main/charts/karpenter/crds)).
+  Helm [does not manage the lifecycle of CRDs using this method](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/) - the tool will only install the CRD during the first installation of the Helm chart.
+  Subsequent chart upgrades will not add or remove CRDs, even if the CRDs have changed.
+
+CRDs are coupled to the version of Karpenter, and should be updated along with Karpenter.
+For this reason, we recommend using the independent `karpenter-crd` chart to manage CRDs.
 
 {{% alert title="Note" color="warning" %}}
 If you get the error `invalid ownership metadata; label validation error:` while installing the `karpenter-crd` chart from an older version of Karpenter, follow the [Troubleshooting Guide]({{<ref "../troubleshooting/#helm-error-when-installing-the-karpenter-crd-chart" >}}) for details on how to resolve these errors.
 {{% /alert %}}
 
-* As part of the helm chart [karpenter](https://gallery.ecr.aws/karpenter/karpenter) - [source](https://github.com/aws/karpenter/blob/main/charts/karpenter/crds). Helm [does not manage the lifecycle of CRDs using this method](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/), the tool will only install the CRD during the first installation of the Helm chart. Subsequent chart upgrades will not add or remove CRDs, even if the CRDs have changed. When CRDs are changed, we will make a note in the version's upgrade guide.
-
 <!--
 WHEN CREATING A NEW SECTION OF THE UPGRADE GUIDANCE FOR NEWER VERSIONS, ENSURE THAT YOU COPY THE BETA API ALERT SECTION FROM THE LAST RELEASE TO PROPERLY WARN USERS OF THE RISK OF UPGRADING WITHOUT GOING TO 0.32.x FIRST
 -->

diff --git a/website/content/en/preview/upgrading/upgrade-guide.md b/website/content/en/preview/upgrading/upgrade-guide.md
@@ -17,18 +17,22 @@ With the release of Karpenter v1.0.0, the Karpenter team will be dropping suppor
 ### CRD Upgrades
 
 Karpenter ships with a few Custom Resource Definitions (CRDs). These CRDs are published:
-* As an independent Helm chart [karpenter-crd](https://gallery.ecr.aws/karpenter/karpenter-crd) - [source](https://github.com/aws/karpenter/blob/main/charts/karpenter-crd) that can be used by Helm to manage the lifecycle of these CRDs. To upgrade or install `karpenter-crd` run:
+* As an independent Helm chart [karpenter-crd](https://gallery.ecr.aws/karpenter/karpenter-crd) ([source](https://github.com/aws/karpenter/blob/main/charts/karpenter-crd)) that can be used by Helm to manage the lifecycle of these CRDs. To upgrade or install `karpenter-crd` run:
   ```bash
   KARPENTER_NAMESPACE=kube-system
   helm upgrade --install karpenter-crd oci://public.ecr.aws/karpenter/karpenter-crd --version x.y.z --namespace "${KARPENTER_NAMESPACE}" --create-namespace
   ```
+* As part of the helm chart [karpenter](https://gallery.ecr.aws/karpenter/karpenter) ([source](https://github.com/aws/karpenter/blob/main/charts/karpenter/crds)).
+  Helm [does not manage the lifecycle of CRDs using this method](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/) - the tool will only install the CRD during the first installation of the Helm chart.
+  Subsequent chart upgrades will not add or remove CRDs, even if the CRDs have changed.
+
+CRDs are coupled to the version of Karpenter, and should be updated along with Karpenter.
+For this reason, we recommend using the independent `karpenter-crd` chart to manage CRDs.
 
 {{% alert title="Note" color="warning" %}}
 If you get the error `invalid ownership metadata; label validation error:` while installing the `karpenter-crd` chart from an older version of Karpenter, follow the [Troubleshooting Guide]({{<ref "../troubleshooting/#helm-error-when-installing-the-karpenter-crd-chart" >}}) for details on how to resolve these errors.
 {{% /alert %}}
 
-* As part of the helm chart [karpenter](https://gallery.ecr.aws/karpenter/karpenter) - [source](https://github.com/aws/karpenter/blob/main/charts/karpenter/crds). Helm [does not manage the lifecycle of CRDs using this method](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/), the tool will only install the CRD during the first installation of the Helm chart. Subsequent chart upgrades will not add or remove CRDs, even if the CRDs have changed. When CRDs are changed, we will make a note in the version's upgrade guide.
-
 <!--
 WHEN CREATING A NEW SECTION OF THE UPGRADE GUIDANCE FOR NEWER VERSIONS, ENSURE THAT YOU COPY THE BETA API ALERT SECTION FROM THE LAST RELEASE TO PROPERLY WARN USERS OF THE RISK OF UPGRADING WITHOUT GOING TO 0.32.x FIRST
 -->

diff --git a/website/content/en/v1.0/upgrading/upgrade-guide.md b/website/content/en/v1.0/upgrading/upgrade-guide.md
@@ -17,18 +17,22 @@ With the release of Karpenter v1.0.0, the Karpenter team will be dropping suppor
 ### CRD Upgrades
 
 Karpenter ships with a few Custom Resource Definitions (CRDs). These CRDs are published:
-* As an independent Helm chart [karpenter-crd](https://gallery.ecr.aws/karpenter/karpenter-crd) - [source](https://github.com/aws/karpenter/blob/main/charts/karpenter-crd) that can be used by Helm to manage the lifecycle of these CRDs. To upgrade or install `karpenter-crd` run:
+* As an independent Helm chart [karpenter-crd](https://gallery.ecr.aws/karpenter/karpenter-crd) ([source](https://github.com/aws/karpenter/blob/main/charts/karpenter-crd)) that can be used by Helm to manage the lifecycle of these CRDs. To upgrade or install `karpenter-crd` run:
   ```bash
   KARPENTER_NAMESPACE=kube-system
   helm upgrade --install karpenter-crd oci://public.ecr.aws/karpenter/karpenter-crd --version x.y.z --namespace "${KARPENTER_NAMESPACE}" --create-namespace
   ```
+* As part of the helm chart [karpenter](https://gallery.ecr.aws/karpenter/karpenter) ([source](https://github.com/aws/karpenter/blob/main/charts/karpenter/crds)).
+  Helm [does not manage the lifecycle of CRDs using this method](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/) - the tool will only install the CRD during the first installation of the Helm chart.
+  Subsequent chart upgrades will not add or remove CRDs, even if the CRDs have changed.
+
+CRDs are coupled to the version of Karpenter, and should be updated along with Karpenter.
+For this reason, we recommend using the independent `karpenter-crd` chart to manage CRDs.
 
 {{% alert title="Note" color="warning" %}}
 If you get the error `invalid ownership metadata; label validation error:` while installing the `karpenter-crd` chart from an older version of Karpenter, follow the [Troubleshooting Guide]({{<ref "../troubleshooting/#helm-error-when-installing-the-karpenter-crd-chart" >}}) for details on how to resolve these errors.
 {{% /alert %}}
 
-* As part of the helm chart [karpenter](https://gallery.ecr.aws/karpenter/karpenter) - [source](https://github.com/aws/karpenter/blob/main/charts/karpenter/crds). Helm [does not manage the lifecycle of CRDs using this method](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/), the tool will only install the CRD during the first installation of the Helm chart. Subsequent chart upgrades will not add or remove CRDs, even if the CRDs have changed. When CRDs are changed, we will make a note in the version's upgrade guide.
-
 <!--
 WHEN CREATING A NEW SECTION OF THE UPGRADE GUIDANCE FOR NEWER VERSIONS, ENSURE THAT YOU COPY THE BETA API ALERT SECTION FROM THE LAST RELEASE TO PROPERLY WARN USERS OF THE RISK OF UPGRADING WITHOUT GOING TO 0.32.x FIRST
 -->