How do I use the Bottlerocket AMI to create a managed node group in Amazon EKS?

Resolution

You can use eksctl with a configuration file to create a Bottlerocket managed node group.

Prerequisites

• eksctl version 0.124.0 or later
• An existing Amazon EKS cluster
• If you want SSH access to nodes, then you need an Amazon Elastic Compute Cloud (Amazon EC2) SSH key pair

To use the Bottlerocket AMI to create a managed node group, complete the following steps:

Verify the eksctl version

To verify your eksctl version, run the following command:

eksctl version

If you need to install or upgrade eksctl, then see Installation options for Eksctl.

Create the configuration file

Important: Bottlerocket supports general purpose, compute-optimized, memory-optimized, and storage-optimized instance types. Bottlerocket doesn't support accelerated computing instances.

Create a file named bottlerocket.yaml with the following configuration:

---
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: mybottlerocket-cluster
  region: your-region
  version: '1.31'

iam:
  withOIDC: true

nodeGroups:
  - name: ng-bottlerocket
    instanceType: m5.large
    desiredCapacity: 3
    amiFamily: Bottlerocket
    ami: auto-ssm
    iam:
       attachPolicyARNs:
          - arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy
          - arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly
          - arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
          - arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy
    ssh:
        allow: true
        publicKeyName: your-ec2-keypair-name

Note: Replace mybottlerocket-cluster with your cluster name. Replace your-region with your AWS Region. Replace your-ec2-keypair-name with your Amazon EC2 SSH key pair name. If you don't have an Amazon EC2 key pair, then see Create a key pair for your Amazon EC2 instance.

Create the managed node group

To create the managed node group, run the following command:

eksctl create nodegroup --config-file=bottlerocket.yaml

The command creates the node group and registers the nodes with your cluster. This process takes several minutes to complete.

Verify the nodes

To verify the nodes are running, run the following command:

kubectl get nodes -o wide

The output shows your Bottlerocket nodes with their status, Kubernetes version, and operating system information.

Example output:

NAME                                           STATUS   ROLES    AGE   VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE                                       KERNEL-VERSION   CONTAINER-RUNTIME
ip-[IP_ADDRESS].us-west-2.compute.internal   Ready    <none>   5m    v1.31.0   [IP_ADDRESS] <none>        Bottlerocket OS 1.20.0 (aws-k8s-1.31)        5.15.0           containerd://1.7.11

Connect to Bottlerocket nodes

Bottlerocket nodes don't include an SSH server or shell by default. To connect to Bottlerocket nodes for troubleshooting, use AWS Systems Manager Session Manager.

To connect to a Bottlerocket node, complete the following steps:

1. Retrieve the instance ID of your Bottlerocket node from the Amazon EC2 console or by running the following command:

   kubectl get nodes -o wide

2. Use the instance ID to start a Session Manager session. For more information about starting a session, see Starting a session (Systems Manager console).

Note: The AmazonSSMManagedInstanceCore IAM policy in the node group configuration allows Session Manager access to your Bottlerocket nodes.

Related information

Create self-managed Bottlerocket nodes

Simplify node lifecycle with managed node groups

Using a Bottlerocket AMI with Amazon EKS on the github website