Skip to content

Update EKS on Outpost docs for AL2023 #1177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
nkvetsinski wants to merge 2 commits into from
Closed

Update EKS on Outpost docs for AL2023 #1177

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a4f5bbb
Update Outpost docs for AL2023
Nov 24, 2025
3a6b701
Merge branch 'awsdocs:mainline' into mainline
nkvetsinski Nov 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 15 additions & 26 deletions latest/ug/outposts/eks-outposts-self-managed-nodes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,13 @@ Learn how to launch Auto Scaling groups of Amazon Linux nodes on an Outpost that

[IMPORTANT]
====
Amazon EKS Local Clusters on Outposts only supports nodes created from the following Amazon EKS-optimized Amazon Linux 2 AMIs:
Amazon EKS Local Clusters on Outposts only supports nodes created from the following Amazon EKS-optimized Amazon Linux 2023 AMIs:

* Standard Amazon Linux 2 (`amazon-linux-2`)
* GPU-enabled Amazon Linux 2 (`amazon-linux-2-gpu`)
* Arm64-based Amazon Linux 2 (`amazon-linux-2-arm64`)
* Standard Amazon Linux 2023 (`amazon-linux-2023/x86_64/standard`)
* Accelerated Nvidia Amazon Linux 2023 (`amazon-linux-2023/x86_64/nvidia`)
* Accelerated Neuron Amazon Linux 2023 (`amazon-linux-2023/x86_64/neuron`)

Nodes on Local Clusters that run Amazon Linux 2023 (AL2023) AMIs aren't supported and fail to join the cluster.
AWS will end support for EKS AL2-optimized and AL2-accelerated AMIs, effective November 26, 2025. While you can continue using EKS AL2 AMIs after the end-of-support (EOS) date (November 26, 2025), EKS will no longer release any new Kubernetes versions or updates to AL2 AMIs, including minor releases, patches, and bug fixes after this date. See link:https://docs.aws.amazon.com/eks/latest/userguide/eks-ami-deprecation-faqs.html[this] for more information on AL2 deprecation.
====

This topic describes how you can launch Auto Scaling groups of Amazon Linux nodes on an Outpost that register with your Amazon EKS cluster. The cluster can be on the {aws} Cloud or on an Outpost.
Expand Down Expand Up @@ -50,7 +50,7 @@ You can create a self-managed node group for local cluster with the following to
. Install version `{eksctl-min-version}` or later of the `eksctl` command line tool installed on your device or {aws} CloudShell. To install or update `eksctl`, see https://eksctl.io/installation[Installation] in the `eksctl` documentation.
+
. If your cluster is on the {aws} Cloud and the *AmazonEKS_CNI_Policy* managed IAM policy is attached to your <<create-node-role,Amazon EKS node IAM role>>, we recommend assigning it to an IAM role that you associate to the Kubernetes `aws-node` service account instead. For more information, see <<cni-iam-role>>. If your cluster in on your Outpost, the policy must be attached to your node role.
. The following command creates a node group in an existing cluster. The cluster must have been created using `eksctl`. Replace [.replaceable]`al-nodes` with a name for your node group. The node group name can't be longer than 63 characters. It must start with letter or digit, but can also include hyphens and underscores for the remaining characters. Replace [.replaceable]`my-cluster` with the name of your cluster. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphanumeric character and can't be longer than 100 characters. The name must be unique within the {aws} Region and {aws} account that you're creating the cluster in. If your cluster exists on an Outpost, replace [.replaceable]`id` with the ID of an Outpost subnet. If your cluster exists on the {aws} Cloud, replace [.replaceable]`id` with the ID of a subnet that you didn't specify when you created your cluster. Replace [.replaceable]`instance-type` with an instance type supported by your Outpost. Replace the remaining example values with your own values. The nodes are created with the same Kubernetes version as the control plane, by default.
. The following command creates a node group in an existing cluster. The cluster must have been created using `eksctl`. Replace [.replaceable]`al-nodes` with a name for your node group. The node group name can't be longer than 63 characters. It must start with letter or digit, but can also include hyphens and underscores for the remaining characters. Replace [.replaceable]`my-cluster` with the name of your cluster. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphanumeric character and can't be longer than 100 characters. The name must be unique within the {aws} Region and {aws} account that you're creating the cluster in. If your cluster exists on an Outpost, replace [.replaceable]`id` with the ID of an Outpost subnet. If your cluster exists on the {aws} Cloud, replace [.replaceable]`id` with the ID of a subnet that you didn't specify when you created your cluster. Replace the remaining example values with your own values. The nodes are created with the same Kubernetes version as the control plane, by default.
+
Replace [.replaceable]`instance-type` with an instance type available on your Outpost.
+
Expand All @@ -61,7 +61,9 @@ Create your node group with the following command.
[source,bash,subs="verbatim,attributes"]
----
eksctl create nodegroup --cluster my-cluster --name al-nodes --node-type instance-type \
--nodes 3 --nodes-min 1 --nodes-max 4 --managed=false --node-volume-type gp2 --subnet-ids subnet-id
--nodes 3 --nodes-min 1 --nodes-max 4 --managed=false \
--node-volume-type gp2 --subnet-ids subnet-id \
--node-ami-family AmazonLinux2023
----
+
If your cluster is deployed on the {aws} Cloud:
Expand Down Expand Up @@ -89,15 +91,19 @@ For a complete list of all available options and defaults, see https://eksctl.io
+
[source,bash,subs="verbatim,attributes"]
----
curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2022-12-23/amazon-eks-nodegroup.yaml
curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2025-11-24/amazon-eks-outpost-nodegroup.yaml
----
. Open the link:cloudformation/[{aws} CloudFormation console,type="console"].
. Choose *Create stack* and then select *With new resources (standard)*.
. For *Specify template*, select *Upload a template file* and then select *Choose file*. Select the `amazon-eks-nodegroup.yaml` file that you downloaded in a previous step and then select *Next*.
. On the *Specify stack details* page, enter the following parameters accordingly, and then choose *Next*:
+
** *Stack name*: Choose a stack name for your {aws} CloudFormation stack. For example, you can call it [.replaceable]`al-nodes`. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphanumeric character and can't be longer than 100 characters. The name must be unique within the {aws} Region and {aws} account that you're creating the cluster in.
** *ApiServerEndpoint*: Enter the Kubernetes API Server endpoint, visible in EKS console or via DescribeCluster API.
** *ClusterName*: Enter the name of your cluster. If this name doesn't match your cluster name, your nodes can't join the cluster.
** *ClusterId*: Enter the id assigned to the cluster by EKS service. Visible via DescribeCluster API. If this id doesn't match your cluster id, your nodes can't join the cluster.
** *CertificateAuthority*: Enter base64 encoded string of the Kubernetes Certificate Authority. Visible in EKS console or via DescribeCluster API.
** *ServiceCidr*: Enter the Kubernetes Services CIDR. Visible in EKS console or via DescribeCluster API.
** *ClusterControlPlaneSecurityGroup*: Choose the *SecurityGroups* value from the {aws} CloudFormation output that you generated when you created your <<creating-a-vpc,VPC>>.
+
The following steps show one operation to retrieve the applicable group.
Expand All @@ -113,7 +119,7 @@ The following steps show one operation to retrieve the applicable group.
** *NodeInstanceType*: Choose an instance type for your nodes. If your cluster is running on the {aws} Cloud, then for more information, see <<choosing-instance-type>>. If your cluster is running on an Outpost, then you can only select an instance type that is available on your Outpost.
** *NodeImageIdSSMParam*: Pre-populated with the Amazon EC2 Systems Manager parameter of a recent Amazon EKS optimized AMI for a variable Kubernetes version. To use a different Kubernetes minor version supported with Amazon EKS, replace [.replaceable]`1.XX` with a different link:eks/latest/userguide/kubernetes-versions.html[supported version,type="documentation"]. We recommend specifying the same Kubernetes version as your cluster.
+
To use an Amazon EKS optimized accelerated AMI, replace [.replaceable]`amazon-linux-2` with `amazon-linux-2-gpu`. To use an Amazon EKS optimized Arm AMI, replace [.replaceable]`amazon-linux-2` with `amazon-linux-2-arm64`.
To use an Amazon EKS optimized accelerated AMI, update [.replaceable]`NodeImageIdSSMParam` value to the desired SSM parameter. See how to retrieve EKS AMI IDs from SSM link:eks/latest/userguide/retrieve-ami-id.html[here,type="documentation"].
+
NOTE: The Amazon EKS node AMIs are based on Amazon Linux. You can track security or privacy events for Amazon Linux at the https://alas.aws.amazon.com/[Amazon Linux security center] by choosing the tab for your desired version. You can also subscribe to the applicable RSS feed. Security and privacy events include an overview of the issue, what packages are affected, and how to update your instances to correct the issue.
** *NodeImageId*: (Optional) If you're using your own custom AMI (instead of an Amazon EKS optimized AMI), enter a node AMI ID for your {aws} Region. If you specify a value here, it overrides any values in the *NodeImageIdSSMParam* field.
Expand All @@ -122,23 +128,6 @@ NOTE: The Amazon EKS node AMIs are based on Amazon Linux. You can track security
** *KeyName*: Enter the name of an Amazon EC2 SSH key pair that you can use to connect using SSH into your nodes with after they launch. If you don't already have an Amazon EC2 key pair, you can create one in the {aws-management-console}. For more information, see link:AWSEC2/latest/UserGuide/ec2-key-pairs.html[Amazon EC2 key pairs,type="documentation"] in the _Amazon EC2 User Guide_.
+
NOTE: If you don't provide a key pair here, the {aws} CloudFormation stack creation fails.
** *BootstrapArguments*: There are several optional arguments that you can pass to your nodes. For more information, view the https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh[bootstrap script usage information] on GitHub. If you're adding nodes to an Amazon EKS Local Cluster on {aws} Outposts (where the Kubernetes control plane instances run on {aws} Outposts) and the cluster doesn't have ingress and egress internet connection (also known as private clusters), then you must provide the following bootstrap arguments (as a single line).
+
[source,bash,subs="verbatim,attributes"]
----
--b64-cluster-ca ${CLUSTER_CA} --apiserver-endpoint https://${APISERVER_ENDPOINT} --enable-local-outpost true --cluster-id ${CLUSTER_ID}
----
To retrieve the values for `CLUSTER_CA`, `APISERVER_ENDPOINT`, and `CLUSTER_ID` of your Amazon EKS local cluster, run the following {aws} CLI commands. Replace cluster-name with the name of your cluster and region (for example, us-east-1) with your cluster's {aws} Region.
+
[source,bash,subs="verbatim,attributes"]
----
echo "CLUSTER_CA=$(aws eks describe-cluster --name cluster-name --region region --query cluster.certificateAuthority.data --output text)"

echo "APISERVER_ENDPOINT=$(aws eks describe-cluster --name cluster-name --region region --query cluster.endpoint --output text)"

echo "CLUSTER_ID=$(aws eks describe-cluster --name cluster-name --region region --query cluster.id --output text)"
----


** *DisableIMDSv1*: By default, each node supports the Instance Metadata Service Version 1 (IMDSv1) and IMDSv2. You can disable IMDSv1. To prevent future nodes and Pods in the node group from using IMDSv1, set *DisableIMDSv1* to *true*. For more information about IMDS, see link:AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html[Configuring the instance metadata service,type="documentation"]. For more information about restricting access to it on your nodes, see https://aws.github.io/aws-eks-best-practices/security/docs/iam/#restrict-access-to-the-instance-profile-assigned-to-the-worker-node[Restrict access to the instance profile assigned to the worker node].
** *VpcId*: Enter the ID for the <<creating-a-vpc,VPC>> that you created. Before choosing a VPC, review <<outposts-vpc-requirements,VPC requirements and considerations>>.
Expand Down