From edad17f44f89753450826b3960fba23ec8140b7e Mon Sep 17 00:00:00 2001 From: Jason Deal Date: Tue, 20 Aug 2024 11:36:01 -0700 Subject: [PATCH 1/4] docs: detail how to discover alias versions --- .../content/en/docs/concepts/nodeclasses.md | 26 ++++++++++++++++++- .../en/preview/concepts/nodeclasses.md | 25 +++++++++++++++++- .../content/en/v1.0/concepts/nodeclasses.md | 25 +++++++++++++++++- 3 files changed, 73 insertions(+), 3 deletions(-) diff --git a/website/content/en/docs/concepts/nodeclasses.md b/website/content/en/docs/concepts/nodeclasses.md index bd7a70d50629..a81787022d80 100644 --- a/website/content/en/docs/concepts/nodeclasses.md +++ b/website/content/en/docs/concepts/nodeclasses.md @@ -731,6 +731,30 @@ alias: bottlerocket@v1.20.4 ``` The Windows family does not support pinning, so only `latest` is supported. +The following commands can be used to determine the versions availble for an alias in your region: + +{{< tabpane text=true right=false >}} + {{% tab "AL2023" %}} + ```bash + export K8S_VERSION="{{< param "latest_k8s_version" >}}" + aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2023/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $10}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq + ``` + {{% /tab %}} + {{% tab "AL2" %}} + ```bash + export K8S_VERSION="{{< param "latest_k8s_version" >}}" + aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $8}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq + ``` + {{% /tab %}} + {{% tab "Bottlerocket" %}} + ```bash + export K8S_VERSION="{{< param "latest_k8s_version" >}}" + aws ssm get-parameters-by-path --path "/aws/service/bottlerocket/aws-k8s-$K8S_VERSION" --recursive | jq -cr '.Parameters[].Name' | grep -v "latest" | awk -F '/' '{print $7}' | sort | uniq + ``` + {{% /tab %}} +{{< /tabpane >}} + + To select an AMI by name, use the `name` field in the selector term. To select an AMI by id, use the `id` field in the selector term. To select AMIs that are not owned by `amazon` or the account that Karpenter is running in, use the `owner` field - you can use a combination of account aliases (e.g. `self` `amazon`, `your-aws-account-name`) and account IDs. If owner is not set for `name`, it defaults to `self,amazon`, preventing Karpenter from inadvertently selecting an AMI that is owned by a different account. Tags don't require an owner as tags can only be discovered by the user who created them. @@ -1534,4 +1558,4 @@ NodeClasses have the following status conditions: | AMIsReady | AMIs are discovered | | Ready | Top level condition that indicates if the nodeClass is ready. If any of the underlying conditions is `False` then this condition is set to `False` and `Message` on the condition indicates the dependency that was not resolved. | -If a NodeClass is not ready, NodePools that reference it through their `nodeClassRef` will not be considered for scheduling. \ No newline at end of file +If a NodeClass is not ready, NodePools that reference it through their `nodeClassRef` will not be considered for scheduling. diff --git a/website/content/en/preview/concepts/nodeclasses.md b/website/content/en/preview/concepts/nodeclasses.md index 0c3e1a1d76e5..c5563faf1ebe 100644 --- a/website/content/en/preview/concepts/nodeclasses.md +++ b/website/content/en/preview/concepts/nodeclasses.md @@ -731,6 +731,29 @@ alias: bottlerocket@v1.20.4 ``` The Windows family does not support pinning, so only `latest` is supported. +The following commands can be used to determine the versions availble for an alias in your region: + +{{< tabpane text=true right=false >}} + {{% tab "AL2023" %}} + ```bash + export K8S_VERSION=1.30 + aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2023/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $10}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq + ``` + {{% /tab %}} + {{% tab "AL2" %}} + ```bash + export K8S_VERSION=1.30 + aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $8}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq + ``` + {{% /tab %}} + {{% tab "Bottlerocket" %}} + ```bash + export K8S_VERSION=1.30 + aws ssm get-parameters-by-path --path "/aws/service/bottlerocket/aws-k8s-$K8S_VERSION" --recursive | jq -cr '.Parameters[].Name' | grep -v "latest" | awk -F '/' '{print $7}' | sort | uniq + ``` + {{% /tab %}} +{{< /tabpane >}} + To select an AMI by name, use the `name` field in the selector term. To select an AMI by id, use the `id` field in the selector term. To select AMIs that are not owned by `amazon` or the account that Karpenter is running in, use the `owner` field - you can use a combination of account aliases (e.g. `self` `amazon`, `your-aws-account-name`) and account IDs. If owner is not set for `name`, it defaults to `self,amazon`, preventing Karpenter from inadvertently selecting an AMI that is owned by a different account. Tags don't require an owner as tags can only be discovered by the user who created them. @@ -1534,4 +1557,4 @@ NodeClasses have the following status conditions: | AMIsReady | AMIs are discovered | | Ready | Top level condition that indicates if the nodeClass is ready. If any of the underlying conditions is `False` then this condition is set to `False` and `Message` on the condition indicates the dependency that was not resolved. | -If a NodeClass is not ready, NodePools that reference it through their `nodeClassRef` will not be considered for scheduling. \ No newline at end of file +If a NodeClass is not ready, NodePools that reference it through their `nodeClassRef` will not be considered for scheduling. diff --git a/website/content/en/v1.0/concepts/nodeclasses.md b/website/content/en/v1.0/concepts/nodeclasses.md index bd7a70d50629..3ee6527dc981 100644 --- a/website/content/en/v1.0/concepts/nodeclasses.md +++ b/website/content/en/v1.0/concepts/nodeclasses.md @@ -731,6 +731,29 @@ alias: bottlerocket@v1.20.4 ``` The Windows family does not support pinning, so only `latest` is supported. +The following commands can be used to determine the versions availble for an alias in your region: + +{{< tabpane text=true right=false >}} + {{% tab "AL2023" %}} + ```bash + export K8S_VERSION=1.30 + aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2023/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $10}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq + ``` + {{% /tab %}} + {{% tab "AL2" %}} + ```bash + export K8S_VERSION=1.30 + aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $8}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq + ``` + {{% /tab %}} + {{% tab "Bottlerocket" %}} + ```bash + export K8S_VERSION=1.30 + aws ssm get-parameters-by-path --path "/aws/service/bottlerocket/aws-k8s-$K8S_VERSION" --recursive | jq -cr '.Parameters[].Name' | grep -v "latest" | awk -F '/' '{print $7}' | sort | uniq + ``` + {{% /tab %}} +{{< /tabpane >}} + To select an AMI by name, use the `name` field in the selector term. To select an AMI by id, use the `id` field in the selector term. To select AMIs that are not owned by `amazon` or the account that Karpenter is running in, use the `owner` field - you can use a combination of account aliases (e.g. `self` `amazon`, `your-aws-account-name`) and account IDs. If owner is not set for `name`, it defaults to `self,amazon`, preventing Karpenter from inadvertently selecting an AMI that is owned by a different account. Tags don't require an owner as tags can only be discovered by the user who created them. @@ -1534,4 +1557,4 @@ NodeClasses have the following status conditions: | AMIsReady | AMIs are discovered | | Ready | Top level condition that indicates if the nodeClass is ready. If any of the underlying conditions is `False` then this condition is set to `False` and `Message` on the condition indicates the dependency that was not resolved. | -If a NodeClass is not ready, NodePools that reference it through their `nodeClassRef` will not be considered for scheduling. \ No newline at end of file +If a NodeClass is not ready, NodePools that reference it through their `nodeClassRef` will not be considered for scheduling. From 34be1b115480bc15f46099d80a4111a9b1ef363b Mon Sep 17 00:00:00 2001 From: Jason Deal Date: Wed, 28 Aug 2024 15:39:17 -0700 Subject: [PATCH 2/4] add latest warning --- website/content/en/docs/concepts/nodeclasses.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/content/en/docs/concepts/nodeclasses.md b/website/content/en/docs/concepts/nodeclasses.md index a81787022d80..5dc421f89834 100644 --- a/website/content/en/docs/concepts/nodeclasses.md +++ b/website/content/en/docs/concepts/nodeclasses.md @@ -754,6 +754,12 @@ The following commands can be used to determine the versions availble for an ali {{% /tab %}} {{< /tabpane >}} +{{% alert title="Warning" color="warning" %}} +Karpenter supports automatic AMI selection and upgrades using the `latest` version pin, but this is **not** recommended for production environments. +When using `latest`, a new AMI release will cause Karpenter to drift all out-of-date nodes in the cluster, replacing them with nodes running the new AMI. +We strongly recommend evaluating new AMIs in a lower environment before rolling them out into a production environment. +More details on Karpenter's recommendations for managing AMIs can be found [here]({{< ref "../tasks/managing-amis" >}}). +{{% /alert %}} To select an AMI by name, use the `name` field in the selector term. To select an AMI by id, use the `id` field in the selector term. To select AMIs that are not owned by `amazon` or the account that Karpenter is running in, use the `owner` field - you can use a combination of account aliases (e.g. `self` `amazon`, `your-aws-account-name`) and account IDs. From d61a94285ffdc1cca430e7f48a66c673109a3fbf Mon Sep 17 00:00:00 2001 From: Jason Deal Date: Wed, 28 Aug 2024 15:43:20 -0700 Subject: [PATCH 3/4] copy updates --- website/content/en/preview/concepts/nodeclasses.md | 13 ++++++++++--- website/content/en/v1.0/concepts/nodeclasses.md | 13 ++++++++++--- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/website/content/en/preview/concepts/nodeclasses.md b/website/content/en/preview/concepts/nodeclasses.md index c5563faf1ebe..216b3ad6e5b1 100644 --- a/website/content/en/preview/concepts/nodeclasses.md +++ b/website/content/en/preview/concepts/nodeclasses.md @@ -736,24 +736,31 @@ The following commands can be used to determine the versions availble for an ali {{< tabpane text=true right=false >}} {{% tab "AL2023" %}} ```bash - export K8S_VERSION=1.30 + export K8S_VERSION="{{< param "latest_k8s_version" >}}" aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2023/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $10}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq ``` {{% /tab %}} {{% tab "AL2" %}} ```bash - export K8S_VERSION=1.30 + export K8S_VERSION="{{< param "latest_k8s_version" >}}" aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $8}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq ``` {{% /tab %}} {{% tab "Bottlerocket" %}} ```bash - export K8S_VERSION=1.30 + export K8S_VERSION="{{< param "latest_k8s_version" >}}" aws ssm get-parameters-by-path --path "/aws/service/bottlerocket/aws-k8s-$K8S_VERSION" --recursive | jq -cr '.Parameters[].Name' | grep -v "latest" | awk -F '/' '{print $7}' | sort | uniq ``` {{% /tab %}} {{< /tabpane >}} +{{% alert title="Warning" color="warning" %}} +Karpenter supports automatic AMI selection and upgrades using the `latest` version pin, but this is **not** recommended for production environments. +When using `latest`, a new AMI release will cause Karpenter to drift all out-of-date nodes in the cluster, replacing them with nodes running the new AMI. +We strongly recommend evaluating new AMIs in a lower environment before rolling them out into a production environment. +More details on Karpenter's recommendations for managing AMIs can be found [here]({{< ref "../tasks/managing-amis" >}}). +{{% /alert %}} + To select an AMI by name, use the `name` field in the selector term. To select an AMI by id, use the `id` field in the selector term. To select AMIs that are not owned by `amazon` or the account that Karpenter is running in, use the `owner` field - you can use a combination of account aliases (e.g. `self` `amazon`, `your-aws-account-name`) and account IDs. If owner is not set for `name`, it defaults to `self,amazon`, preventing Karpenter from inadvertently selecting an AMI that is owned by a different account. Tags don't require an owner as tags can only be discovered by the user who created them. diff --git a/website/content/en/v1.0/concepts/nodeclasses.md b/website/content/en/v1.0/concepts/nodeclasses.md index 3ee6527dc981..5dc421f89834 100644 --- a/website/content/en/v1.0/concepts/nodeclasses.md +++ b/website/content/en/v1.0/concepts/nodeclasses.md @@ -736,24 +736,31 @@ The following commands can be used to determine the versions availble for an ali {{< tabpane text=true right=false >}} {{% tab "AL2023" %}} ```bash - export K8S_VERSION=1.30 + export K8S_VERSION="{{< param "latest_k8s_version" >}}" aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2023/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $10}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq ``` {{% /tab %}} {{% tab "AL2" %}} ```bash - export K8S_VERSION=1.30 + export K8S_VERSION="{{< param "latest_k8s_version" >}}" aws ssm get-parameters-by-path --path "/aws/service/eks/optimized-ami/$K8S_VERSION/amazon-linux-2/" --recursive | jq -cr '.Parameters[].Name' | grep -v "recommended" | awk -F '/' '{print $8}' | sed -r 's/.*(v[[:digit:]]+)$/\1/' | sort | uniq ``` {{% /tab %}} {{% tab "Bottlerocket" %}} ```bash - export K8S_VERSION=1.30 + export K8S_VERSION="{{< param "latest_k8s_version" >}}" aws ssm get-parameters-by-path --path "/aws/service/bottlerocket/aws-k8s-$K8S_VERSION" --recursive | jq -cr '.Parameters[].Name' | grep -v "latest" | awk -F '/' '{print $7}' | sort | uniq ``` {{% /tab %}} {{< /tabpane >}} +{{% alert title="Warning" color="warning" %}} +Karpenter supports automatic AMI selection and upgrades using the `latest` version pin, but this is **not** recommended for production environments. +When using `latest`, a new AMI release will cause Karpenter to drift all out-of-date nodes in the cluster, replacing them with nodes running the new AMI. +We strongly recommend evaluating new AMIs in a lower environment before rolling them out into a production environment. +More details on Karpenter's recommendations for managing AMIs can be found [here]({{< ref "../tasks/managing-amis" >}}). +{{% /alert %}} + To select an AMI by name, use the `name` field in the selector term. To select an AMI by id, use the `id` field in the selector term. To select AMIs that are not owned by `amazon` or the account that Karpenter is running in, use the `owner` field - you can use a combination of account aliases (e.g. `self` `amazon`, `your-aws-account-name`) and account IDs. If owner is not set for `name`, it defaults to `self,amazon`, preventing Karpenter from inadvertently selecting an AMI that is owned by a different account. Tags don't require an owner as tags can only be discovered by the user who created them. From 0372a63d2d5e8e89d25cc7344bacf476a02ecc9b Mon Sep 17 00:00:00 2001 From: Jason Deal Date: Wed, 28 Aug 2024 16:10:13 -0700 Subject: [PATCH 4/4] update amiFamily note --- website/content/en/docs/concepts/nodeclasses.md | 3 ++- website/content/en/preview/concepts/nodeclasses.md | 3 ++- website/content/en/v1.0/concepts/nodeclasses.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/website/content/en/docs/concepts/nodeclasses.md b/website/content/en/docs/concepts/nodeclasses.md index 5dc421f89834..6bc0fba7013a 100644 --- a/website/content/en/docs/concepts/nodeclasses.md +++ b/website/content/en/docs/concepts/nodeclasses.md @@ -56,7 +56,8 @@ spec: imageGCLowThresholdPercent: 80 cpuCFSQuota: true clusterDNS: ["10.0.1.100"] - # Required, resolves a default ami and userdata + # Optional, dictates UserData generation and default block device mappings. + # May be ommited when using an `alias` amiSelectorTerm, otherwise required. amiFamily: AL2 # Required, discovers subnets to attach to instances diff --git a/website/content/en/preview/concepts/nodeclasses.md b/website/content/en/preview/concepts/nodeclasses.md index 216b3ad6e5b1..2ee6597cc846 100644 --- a/website/content/en/preview/concepts/nodeclasses.md +++ b/website/content/en/preview/concepts/nodeclasses.md @@ -56,7 +56,8 @@ spec: imageGCLowThresholdPercent: 80 cpuCFSQuota: true clusterDNS: ["10.0.1.100"] - # Required, resolves a default ami and userdata + # Optional, dictates UserData generation and default block device mappings. + # May be ommited when using an `alias` amiSelectorTerm, otherwise required. amiFamily: AL2 # Required, discovers subnets to attach to instances diff --git a/website/content/en/v1.0/concepts/nodeclasses.md b/website/content/en/v1.0/concepts/nodeclasses.md index 5dc421f89834..6bc0fba7013a 100644 --- a/website/content/en/v1.0/concepts/nodeclasses.md +++ b/website/content/en/v1.0/concepts/nodeclasses.md @@ -56,7 +56,8 @@ spec: imageGCLowThresholdPercent: 80 cpuCFSQuota: true clusterDNS: ["10.0.1.100"] - # Required, resolves a default ami and userdata + # Optional, dictates UserData generation and default block device mappings. + # May be ommited when using an `alias` amiSelectorTerm, otherwise required. amiFamily: AL2 # Required, discovers subnets to attach to instances