**Help improve this page** To contribute to this user guide, choose the **Edit this page on GitHub** link that is located in the right pane of every page. # Run sample workloads in EKS Auto Mode clusters This chapter provides examples of how to deploy different types of workloads to Amazon EKS clusters running in Auto Mode. The examples demonstrate key workload patterns including sample applications, load-balanced web applications, stateful workloads using persistent storage, and workloads with specific node placement requirements. Each example includes complete manifests and step-by-step deployment instructions that you can use as templates for your own applications. Before proceeding with the examples, ensure that you have an EKS cluster running in Auto Mode and that you have installed the AWS CLI and kubectl. For more information, see [Set up to use Amazon EKS](setting-up.md). The examples assume basic familiarity with Kubernetes concepts and kubectl commands. You can use these use case-based samples to run workloads in EKS Auto Mode clusters. [Deploy a sample inflate workload to an Amazon EKS Auto Mode cluster](automode-workload.md) Shows how to deploy a sample workload to an EKS Auto Mode cluster using `kubectl` commands. [Deploy a Sample Load Balancer Workload to EKS Auto Mode](auto-elb-example.md) Shows how to deploy a containerized version of the 2048 game on Amazon EKS. [Deploy a sample stateful workload to EKS Auto Mode](sample-storage-workload.md) Shows how to deploy a sample stateful application to an EKS Auto Mode cluster. [Deploy an accelerated workload](auto-accelerated.md) Shows how to deploy hardware-accelerated workloads to nodes managed by EKS Auto Mode. [Control if a workload is deployed on EKS Auto Mode nodes](associate-workload.md) Shows how to use an annotation to control if a workload is deployed to nodes managed by EKS Auto Mode. # Deploy a sample inflate workload to an Amazon EKS Auto Mode cluster In this tutorial, you’ll learn how to deploy a sample workload to an EKS Auto Mode cluster and observe how it automatically provisions the required compute resources. You’ll use `kubectl` commands to watch the cluster’s behavior and see firsthand how Auto Mode simplifies Kubernetes operations on AWS. By the end of this tutorial, you’ll understand how EKS Auto Mode responds to workload deployments by automatically managing the underlying compute resources, without requiring manual node group configuration. ## Prerequisites + An Amazon EKS Auto Mode cluster. Note the name and AWS region of the cluster. + An IAM principal, such as a user or role, with sufficient permissions to manage networking, compute, and EKS resources. + For more information, see [Creating roles and attaching policies in the IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions_create-policies.html) in the IAM User Guide. + `aws` CLI installed and configured with an IAM identity. + `kubectl` CLI installed and connected to cluster. + For more information, see [Set up to use Amazon EKS](setting-up.md). ## Step 1: Review existing compute resources (optional) First, use `kubectl` to list the node pools on your cluster. ``` kubectl get nodepools ``` Sample Output: ``` general-purpose ``` In this tutorial, we will deploy a workload configured to use the `general-purpose` node pool. This node pool is built into EKS Auto Mode, and includes reasonable defaults for general workloads, such as microservices and web apps. You can create your own node pool. For more information, see [Create a Node Pool for EKS Auto Mode](create-node-pool.md). Second, use `kubectl` to list the nodes connected to your cluster. ``` kubectl get nodes ``` If you just created an EKS Auto Mode cluster, you will have no nodes. In this tutorial you will deploy a sample workload. If you have no nodes, or the workload cannot fit on existing nodes, EKS Auto Mode will provision a new node. ## Step 2: Deploy a sample application to the cluster Review the following Kubernetes Deployment and save it as `inflate.yaml` ``` apiVersion: apps/v1 kind: Deployment metadata: name: inflate spec: replicas: 1 selector: matchLabels: app: inflate template: metadata: labels: app: inflate spec: terminationGracePeriodSeconds: 0 nodeSelector: eks.amazonaws.com/compute-type: auto securityContext: runAsUser: 1000 runAsGroup: 3000 fsGroup: 2000 containers: - name: inflate image: public.ecr.aws/eks-distro/kubernetes/pause:3.7 resources: requests: cpu: 1 securityContext: allowPrivilegeEscalation: false ``` Note the `eks.amazonaws.com/compute-type: auto` selector requires the workload be deployed on an Amazon EKS Auto Mode node. Apply the Deployment to your cluster. ``` kubectl apply -f inflate.yaml ``` ## Step 3: Watch Kubernetes Events Use the following command to watch Kubernetes events, including creating a new node. Use `ctrl+c` to stop watching events. ``` kubectl get events -w --sort-by '.lastTimestamp' ``` Use `kubectl` to list the nodes connected to your cluster again. Note the newly created node. ``` kubectl get nodes ``` ## Step 4: View nodes and instances in the AWS console You can view EKS Auto Mode Nodes in the EKS console, and the associated EC2 instances in the EC2 console. EC2 Instances deployed by EKS Auto Mode are restricted. You cannot run arbitrary commands on EKS Auto Mode nodes. ## Step 5: Delete the deployment Use `kubectl` to delete the sample deployment ``` kubectl delete -f inflate.yaml ``` If you have no other workloads deployed to your cluster, the node created by EKS Auto Mode will be empty. In the default configration, EKS Auto Mode detects nodes that have been empty for thirty seconds, and terminates them. Use `kubectl` or the EC2 console to confirm the associated instance has been deleted. # Deploy a Sample Load Balancer Workload to EKS Auto Mode This guide walks you through deploying a containerized version of the 2048 game on Amazon EKS, complete with load balancing and internet accessibility. ## Prerequisites + An EKS Auto Mode cluster + `kubectl` configured to interact with your cluster + Appropriate IAM permissions for creating ALB resources ## Step 1: Create the Namespace First, create a dedicated namespace for the 2048 game application. Create a file named `01-namespace.yaml`: ``` apiVersion: v1 kind: Namespace metadata: name: game-2048 ``` Apply the namespace configuration: ``` kubectl apply -f 01-namespace.yaml ``` ## Step 2: Deploy the Application The application runs multiple replicas of the 2048 game container. Create a file named `02-deployment.yaml`: ``` apiVersion: apps/v1 kind: Deployment metadata: namespace: game-2048 name: deployment-2048 spec: selector: matchLabels: app.kubernetes.io/name: app-2048 replicas: 5 template: metadata: labels: app.kubernetes.io/name: app-2048 spec: containers: - image: public.ecr.aws/l6m2t8p7/docker-2048:latest imagePullPolicy: Always name: app-2048 ports: - containerPort: 80 resources: requests: cpu: "0.5" ``` **Note** If you receive an error loading the image `public.ecr.aws/l6m2t8p7/docker-2048:latest`, confirm your Node IAM role has sufficient permissions to pull images from ECR. For more information, see [Node IAM role](auto-learn-iam.md#auto-learn-node-iam-role). Also, the `docker-2048` image in the example is an `x86_64` image and will not run on other architectures. **Key components:** + Deploys 5 replicas of the application + Uses a public ECR image + Requests 0.5 CPU cores per pod + Exposes port 80 for HTTP traffic Apply the deployment: ``` kubectl apply -f 02-deployment.yaml ``` ## Step 3: Create the Service The service exposes the deployment to the cluster network. Create a file named `03-service.yaml`: ``` apiVersion: v1 kind: Service metadata: namespace: game-2048 name: service-2048 spec: ports: - port: 80 targetPort: 80 protocol: TCP selector: app.kubernetes.io/name: app-2048 ``` **Key components:** + Creates a NodePort service + Maps port 80 to the container’s port 80 + Uses label selector to find pods Apply the service: ``` kubectl apply -f 03-service.yaml ``` ## Step 4: Configure Load Balancing You will set up an ingress to expose the application to the internet. First, create the `IngressClass`. Create a file named `04-ingressclass.yaml`: ``` apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: labels: app.kubernetes.io/name: LoadBalancerController name: alb spec: controller: eks.amazonaws.com/alb ``` **Note** EKS Auto Mode requires subnet tags to identify public and private subnets. If you created your cluster with `eksctl`, you already have these tags. Learn how to [Tag subnets for EKS Auto Mode](tag-subnets-auto.md). Then create the Ingress resource. Create a file named `05-ingress.yaml`: ``` apiVersion: networking.k8s.io/v1 kind: Ingress metadata: namespace: game-2048 name: ingress-2048 annotations: alb.ingress.kubernetes.io/scheme: internet-facing alb.ingress.kubernetes.io/target-type: ip spec: ingressClassName: alb rules: - http: paths: - path: / pathType: Prefix backend: service: name: service-2048 port: number: 80 ``` **Key components:** + Creates an internet-facing ALB + Uses IP target type for direct pod routing + Routes all traffic (/) to the game service Apply the ingress configurations: ``` kubectl apply -f 04-ingressclass.yaml kubectl apply -f 05-ingress.yaml ``` ## Step 5: Verify the Deployment 1. Check that all pods are running: ``` kubectl get pods -n game-2048 ``` 1. Verify the service is created: ``` kubectl get svc -n game-2048 ``` 1. Get the ALB endpoint: ``` kubectl get ingress -n game-2048 ``` The ADDRESS field in the ingress output will show your ALB endpoint. Wait 2-3 minutes for the ALB to provision and register all targets. ## Step 6: Access the Game Open your web browser and browse to the ALB endpoint URL from the earlier step. You should see the 2048 game interface. ## Step 7: Cleanup To remove all resources created in this tutorial: ``` kubectl delete namespace game-2048 ``` This will delete all resources in the namespace, including the deployment, service, and ingress resources. ## What’s Happening Behind the Scenes 1. The deployment creates 5 pods running the 2048 game 1. The service provides stable network access to these pods 1. EKS Auto Mode: + Creates an Application Load Balancer in AWS + Configures target groups for the pods + Sets up routing rules to direct traffic to the service ## Troubleshooting If the game doesn’t load: + Ensure all pods are running: `kubectl get pods -n game-2048` + Check ingress status: `kubectl describe ingress -n game-2048` + Verify ALB health checks: Check the target group health in AWS Console # Deploy a sample stateful workload to EKS Auto Mode This tutorial will guide you through deploying a sample stateful application to your EKS Auto Mode cluster. The application writes timestamps to a persistent volume, demonstrating EKS Auto Mode’s automatic EBS volume provisioning and persistence capabilities. ## Prerequisites + An EKS Auto Mode cluster + The AWS CLI configured with appropriate permissions + `kubectl` installed and configured + For more information, see [Set up to use Amazon EKS](setting-up.md). ## Step 1: Configure your environment 1. Set your environment variables: ``` export CLUSTER_NAME=my-auto-cluster export AWS_REGION="us-west-2" ``` 1. Update your kubeconfig: ``` aws eks update-kubeconfig --name "${CLUSTER_NAME}" ``` ## Step 2: Create the storage class The `StorageClass` defines how EKS Auto Mode will provision EBS volumes. EKS Auto Mode does not create a `StorageClass` for you. You must create a `StorageClass` referencing `ebs.csi.eks.amazonaws.com` to use the storage capability of EKS Auto Mode. 1. Create a file named `storage-class.yaml`: ``` apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: auto-ebs-sc annotations: storageclass.kubernetes.io/is-default-class: "true" provisioner: ebs.csi.eks.amazonaws.com volumeBindingMode: WaitForFirstConsumer parameters: type: gp3 encrypted: "true" ``` 1. Apply the `StorageClass`: ``` kubectl apply -f storage-class.yaml ``` **Key components:** + `provisioner: ebs.csi.eks.amazonaws.com` - Uses EKS Auto Mode + `volumeBindingMode: WaitForFirstConsumer` - Delays volume creation until a pod needs it + `type: gp3` - Specifies the EBS volume type + `encrypted: "true"` - EBS will use the default `aws/ebs` key to encrypt volumes created with this class. This is optional, but recommended. + `storageclass.kubernetes.io/is-default-class: "true"` - Kubernetes will use this storage class by default, unless you specify a different volume class on a persistent volume claim. Use caution when setting this value if you are migrating from another storage controller. (optional) ## Step 3: Create the persistent volume claim The PVC requests storage from the `StorageClass`. 1. Create a file named `pvc.yaml`: ``` apiVersion: v1 kind: PersistentVolumeClaim metadata: name: auto-ebs-claim spec: accessModes: - ReadWriteOnce storageClassName: auto-ebs-sc resources: requests: storage: 8Gi ``` 1. Apply the PVC: ``` kubectl apply -f pvc.yaml ``` **Key components:** + `accessModes: ReadWriteOnce` - Volume can be mounted by one node at a time + `storage: 8Gi` - Requests an 8 GiB volume + `storageClassName: auto-ebs-sc` - References the `StorageClass` we created ## Step 4: Deploy the Application The Deployment runs a container that writes timestamps to the persistent volume. 1. Create a file named `deployment.yaml`: ``` apiVersion: apps/v1 kind: Deployment metadata: name: inflate-stateful spec: replicas: 1 selector: matchLabels: app: inflate-stateful template: metadata: labels: app: inflate-stateful spec: terminationGracePeriodSeconds: 0 nodeSelector: eks.amazonaws.com/compute-type: auto containers: - name: bash image: public.ecr.aws/docker/library/bash:4.4 command: ["/usr/local/bin/bash"] args: ["-c", "while true; do echo $(date -u) >> /data/out.txt; sleep 60; done"] resources: requests: cpu: "1" volumeMounts: - name: persistent-storage mountPath: /data volumes: - name: persistent-storage persistentVolumeClaim: claimName: auto-ebs-claim ``` 1. Apply the Deployment: ``` kubectl apply -f deployment.yaml ``` **Key components:** + Simple bash container that writes timestamps to a file + Mounts the PVC at `/data` + Requests 1 CPU core + Uses node selector for EKS managed nodes ## Step 5: Verify the Setup 1. Check that the pod is running: ``` kubectl get pods -l app=inflate-stateful ``` 1. Verify the PVC is bound: ``` kubectl get pvc auto-ebs-claim ``` 1. Check the EBS volume: ``` # Get the PV name PV_NAME=$(kubectl get pvc auto-ebs-claim -o jsonpath='{.spec.volumeName}') # Describe the EBS volume aws ec2 describe-volumes \ --filters Name=tag:CSIVolumeName,Values=${PV_NAME} ``` 1. Verify data is being written: ``` kubectl exec "$(kubectl get pods -l app=inflate-stateful \ -o=jsonpath='{.items[0].metadata.name}')" -- \ cat /data/out.txt ``` ## Step 6: Cleanup Run the following command to remove all resources created in this tutorial: ``` # Delete all resources in one command kubectl delete deployment/inflate-stateful pvc/auto-ebs-claim storageclass/auto-ebs-sc ``` ## What’s Happening Behind the Scenes 1. The PVC requests storage from the `StorageClass` 1. When the Pod is scheduled: 1. EKS Auto Mode provisions an EBS volume 1. Creates a PersistentVolume 1. Attaches the volume to the node 1. The Pod mounts the volume and begins writing timestamps ## Snapshot Controller EKS Auto Mode is compatible with the Kubernetes CSI Snapshotter, also known as the snapshot controller. However, EKS Auto Mode does not include the snapshot controller. You are responsible for installing and configuring the snapshot controller. For more information, see [Enable snapshot functionality for CSI volumes](csi-snapshot-controller.md). Review the following `VolumeSnapshotClass` that references the storage capability of EKS Auto Mode. ``` apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: auto-ebs-vsclass driver: ebs.csi.eks.amazonaws.com deletionPolicy: Delete ``` [Learn more about the Kubernetes CSI Snapshotter.](https://github.com/kubernetes-csi/external-snapshotter/blob/master/README.md#usage) # Deploy an accelerated workload This tutorial demonstrates how Amazon EKS Auto Mode simplifies launching hardware-accelerated workloads. Amazon EKS Auto Mode streamlines operations beyond the cluster itself by automating key infrastructure components providing compute, networking, load balancing, storage, and Identity Access and Management capabilities out of the box. Amazon EKS Auto Mode includes the drivers and device plugins required for certain instance types, such as NVIDIA and AWS Neuron drivers. You do not have to install or update these components. EKS Auto Mode automatically manages drivers for these accelerators: + [AWS Trainium](https://aws.amazon.com/ai/machine-learning/trainium/) + [AWS Inferentia](https://aws.amazon.com/ai/machine-learning/inferentia/) + [NVIDIA GPUs on Amazon EC2 accelerated instances](https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html) **Note** EKS Auto Mode includes the NVIDIA device plugin for Kubernetes. This plugin runs automatically and isn’t visible as a daemon set in your cluster. Additional networking support: + [Elastic Fabric Adapter (EFA)](https://aws.amazon.com/hpc/efa/) Amazon EKS Auto Mode eliminates the toil of accelerator driver and device plugin management. You can also benefit from cost savings by scaling the cluster to zero. You can configure EKS Auto Mode to terminate instances when no workloads are running. This is useful for batch based inference workloads. The following provides an example of how to launch accelerated workloads with Amazon EKS Auto Mode. ## Prerequisites + A Kubernetes cluster with Amazon EKS Auto Mode configured. + A `default` EKS Node class as created when the `general-purpose` or `system` Managed Node Pools are enabled. ## Step 1: Deploy a GPU workload In this example, you will create a NodePool for NVIDIA based workloads that requires 45GB GPU memory. With EKS Auto Mode, you use Kubernetes scheduling constraints to define your instance requirements. To deploy the Amazon EKS Auto Mode `NodePool` and the sample `workload`, review the following NodePool and Pod definition and save as `nodepool-gpu.yaml` and `pod.yaml`: **nodepool-gpu.yaml** ``` apiVersion: karpenter.sh/v1 kind: NodePool metadata: name: gpu spec: disruption: budgets: - nodes: 10% consolidateAfter: 1h consolidationPolicy: WhenEmpty template: metadata: {} spec: nodeClassRef: group: eks.amazonaws.com kind: NodeClass name: default requirements: - key: "karpenter.sh/capacity-type" operator: In values: ["on-demand"] - key: "kubernetes.io/arch" operator: In values: ["amd64"] - key: "eks.amazonaws.com/instance-family" operator: In values: - g6e - g6 taints: - key: nvidia.com/gpu effect: NoSchedule terminationGracePeriod: 24h0m0s ``` **pod.yaml** ``` apiVersion: v1 kind: Pod metadata: name: nvidia-smi spec: nodeSelector: eks.amazonaws.com/compute-type: auto restartPolicy: OnFailure containers: - name: nvidia-smi image: public.ecr.aws/amazonlinux/amazonlinux:2023-minimal args: - "nvidia-smi" resources: requests: memory: "30Gi" cpu: "3500m" nvidia.com/gpu: 1 limits: memory: "30Gi" nvidia.com/gpu: 1 tolerations: - key: nvidia.com/gpu effect: NoSchedule operator: Exists ``` Note the `eks.amazonaws.com/compute-type: auto` selector requires the workload be deployed on an Amazon EKS Auto Mode node. The NodePool also sets a taint that only allows pods with tolerations for Nvidia GPUs to be scheduled. Apply the NodePool and workload to your cluster. ``` kubectl apply -f nodepool-gpu.yaml kubectl apply -f pod.yaml ``` You should see the following output: ``` nodepool.karpenter.sh/gpu configured created pod/nvidia-smi created ``` Wait a few seconds, and check the nodes in your cluster. You should now see a new node provisioned in your Amazon EKS Auto Mode cluster: ``` > kubectl get nodes NAME TYPE CAPACITY ZONE NODE READY AGE gpu-dnknr g6e.2xlarge on-demand us-west-2b i-02315c7d7643cdee6 True 76s ``` ## Step 2: Validate You can see Amazon EKS Auto Mode launched a `g6e.2xlarge` rather than an `g6.2xlarge` as the workload required an instance with l40s `GPU`, according to the following Kubernetes scheduling constraints: ``` ... nodeSelector: eks.amazonaws.com/instance-gpu-name: l40s ... requests: memory: "30Gi" cpu: "3500m" nvidia.com/gpu: 1 limits: memory: "30Gi" nvidia.com/gpu: 1 ``` Now, look at the containers logs, by running the following command: ``` kubectl logs nvidia-smi ``` Sample output: ``` +---------------------------------------------------------------------------------------+ | NVIDIA-SMI 535.230.02 Driver Version: 535.230.02 CUDA Version: 12.2 | |-----------------------------------------+----------------------+----------------------+ | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | | | | MIG M. | |=========================================+======================+======================| | 0 NVIDIA L40S On | 00000000:30:00.0 Off | 0 | | N/A 27C P8 23W / 350W | 0MiB / 46068MiB | 0% Default | | | | N/A | +-----------------------------------------+----------------------+----------------------+ +---------------------------------------------------------------------------------------+ | Processes: | | GPU GI CI PID Type Process name GPU Memory | | ID ID Usage | |=======================================================================================| | No running processes found | +---------------------------------------------------------------------------------------+ ``` You can see that the container has detected it’s running on an instance with an `NVIDIA` GPU and that you’ve not had to install any device drivers, as this is managed by Amazon EKS Auto Mode. ## Step 3: Clean-up To remove all objects created, use `kubectl` to delete the sample deployment and NodePool so the node is terminated: ``` kubectl delete -f nodepool-gpu.yaml kubectl delete -f pod.yaml ``` ## Example NodePools Reference ### Create an NVIDIA NodePool The following NodePool defines: + Only launch instances of `g6e` and `g6` family + Consolidate nodes when empty for 1 hour + The 1 hour value for `consolidateAfter` supports spiky workloads and reduce node churn. You can tune `consolidateAfter` based on your workload requirements. **Example NodePool with GPU instance family and consolidation** ``` apiVersion: karpenter.sh/v1 kind: NodePool metadata: name: gpu spec: disruption: budgets: - nodes: 10% consolidateAfter: 1h consolidationPolicy: WhenEmpty template: metadata: {} spec: nodeClassRef: group: eks.amazonaws.com kind: NodeClass name: default requirements: - key: "karpenter.sh/capacity-type" operator: In values: ["on-demand"] - key: "kubernetes.io/arch" operator: In values: ["amd64"] - key: "eks.amazonaws.com/instance-family" operator: In values: - g6e - g6 terminationGracePeriod: 24h0m0s ``` Instead of to setting the `eks.amazonaws.com/instance-gpu-name` you might use `eks.amazonaws.com/instance-family` to specify the instance family. For other well-known labels which influence scheduling review, see [EKS Auto Mode Supported Labels](create-node-pool.md#auto-supported-labels). If you have specific storage requirements you can tune the nodes ephemeral storage `iops`, `size` and `throughput` by creating your own [NodeClass](create-node-class.md) to reference in the NodePool. Learn more about the [configurable NodeClass options](create-node-class.md). **Example storage configuration for NodeClass** ``` apiVersion: eks.amazonaws.com/v1 kind: NodeClass metadata: name: gpu spec: ephemeralStorage: iops: 3000 size: 80Gi throughput: 125 ``` ### Define an AWS Trainium and AWS Inferentia NodePool The following NodePool has an `eks.amazonaws.com/instance-category` set that says, only launch instances of Inferentia and Trainium family: ``` - key: "eks.amazonaws.com/instance-category" operator: In values: - inf - trn ```