Amazon EKS
User Guide

Getting Started with Amazon EKS

This getting started guide helps you to create all of the required resources to get started with Amazon EKS.

Amazon EKS Prerequisites

Before you can create an Amazon EKS cluster, you must create an IAM role that Kubernetes can assume to create AWS resources. For example, when a load balancer is created, Kubernetes assumes the role to create an Elastic Load Balancing load balancer in your account. This only needs to be done one time and can be used for multiple EKS clusters.

You must also create a VPC and a security group for your cluster to use. Although the VPC and security groups can be used for multiple EKS clusters, we recommend that you use a separate VPC for each EKS cluster to provide better network isolation.

This section also helps you to install the kubectl binary and configure it to work with Amazon EKS.

Create your Amazon EKS Service Role

To create your Amazon EKS service role in the IAM console

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. Choose Roles, then Create role.

  3. Choose EKS from the list of services, then Allows Amazon EKS to manage your clusters on your behalf for your use case, then Next: Permissions.

  4. Choose Next: Tags.

  5. (Optional) Add metadata to the role by attaching tags as key–value pairs. For more information about using tags in IAM, see Tagging IAM Entities in the IAM User Guide.

  6. Choose Next: Review.

  7. For Role name, enter a unique name for your role, such as eksServiceRole, then choose Create role.

Create your Amazon EKS Cluster VPC

To create your cluster VPC

  1. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  2. From the navigation bar, select a Region that supports Amazon EKS.

  3. Choose Create stack.

  4. For Choose a template, select Specify an Amazon S3 template URL.

  5. Paste the following URL into the text area and choose Next:

    https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2019-02-11/amazon-eks-vpc-sample.yaml
  6. On the Specify Details page, fill out the parameters accordingly, and then choose Next.

    • Stack name: Choose a stack name for your AWS CloudFormation stack. For example, you can call it eks-vpc.

    • VpcBlock: Choose a CIDR range for your VPC. You can keep the default value.

    • Subnet01Block: Choose a CIDR range for subnet 1. You can keep the default value.

    • Subnet02Block: Choose a CIDR range for subnet 2. You can keep the default value.

    • Subnet03Block: Choose a CIDR range for subnet 3. You can keep the default value.

  7. (Optional) On the Options page, tag your stack resources. Choose Next.

  8. On the Review page, choose Create.

  9. When your stack is created, select it in the console and choose Outputs.

  10. Record the SecurityGroups value for the security group that was created. You need this when you create your EKS cluster; this security group is applied to the cross-account elastic network interfaces that are created in your subnets that allow the Amazon EKS control plane to communicate with your worker nodes.

  11. Record the VpcId for the VPC that was created. You need this when you launch your worker node group template.

  12. Record the SubnetIds for the subnets that were created. You need this when you create your EKS cluster; these are the subnets that your worker nodes are launched into.

Install and Configure kubectl for Amazon EKS

Kubernetes uses a command-line utility called kubectl for communicating with the cluster API server. Amazon EKS clusters also require the AWS IAM Authenticator for Kubernetes to allow IAM authentication for your Kubernetes cluster. Beginning with Kubernetes version 1.10, you can configure the kubectl client to work with Amazon EKS by installing the AWS IAM Authenticator for Kubernetes and modifying your kubectl configuration file to use it for authentication.

To install kubectl for Amazon EKS

  • You have multiple options to download and install kubectl for your operating system.

    • The kubectl binary is available in many operating system package managers, and this option is often much easier than a manual download and install process. You can follow the instructions for your specific operating system or package manager in the Kubernetes documentation to install.

    • Amazon EKS also vends kubectl binaries that you can use that are identical to the upstream kubectl binaries with the same version. To install the Amazon EKS-vended binary for your operating system, see Installing kubectl.

To install aws-iam-authenticator for Amazon EKS

  1. Download the Amazon EKS-vended aws-iam-authenticator binary from Amazon S3:

    Use the command below to download the binary, substituting the correct URL for your platform. The example below is for macOS clients.

    curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/darwin/amd64/aws-iam-authenticator

    Alternately, you can download the binaries from the AWS IAM Authenticator for Kubernetes project on GitHub. The binaries are identical to the binaries that you can download from Amazon S3 above.

  2. (Optional) Verify the downloaded binary with the SHA-256 sum provided in the same bucket prefix, substituting the correct URL for your platform.

    1. Download the SHA-256 sum for your system. The example below is to download the SHA-256 sum for macOS clients.

      curl -o aws-iam-authenticator.sha256 https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/darwin/amd64/aws-iam-authenticator.sha256
    2. Check the SHA-256 sum for your downloaded binary. The example openssl command below was tested for macOS and Ubuntu clients. Your operating system may use a different command or syntax to check SHA-256 sums. Consult your operating system documentation if necessary.

      openssl sha1 -sha256 aws-iam-authenticator
    3. Compare the generated SHA-256 sum in the command output against your downloaded aws-iam-authenticator.sha256 file. The two should match.

  3. Apply execute permissions to the binary.

    chmod +x ./aws-iam-authenticator
  4. Copy the binary to a folder in your $PATH. We recommend creating a $HOME/bin/aws-iam-authenticator and ensuring that $HOME/bin comes first in your $PATH.

    mkdir $HOME/bin && cp ./aws-iam-authenticator $HOME/bin/aws-iam-authenticator && export PATH=$HOME/bin:$PATH
  5. Add $HOME/bin to your PATH environment variable.

    • For Bash shells on macOS:

      echo 'export PATH=$HOME/bin:$PATH' >> ~/.bash_profile
    • For Bash shells on Linux:

      echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc
  6. Test that the aws-iam-authenticator binary works.

    aws-iam-authenticator help

(Optional) Download and Install the Latest AWS CLI

While the AWS CLI is not explicitly required to use Amazon EKS, the update-kubeconfig command greatly simplifies the kubeconfig creation process. To use the AWS CLI with Amazon EKS, you must have at least version 1.16.73 of the AWS CLI installed. To install or upgrade the AWS CLI, see Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.

Important

Package managers such yum, apt-get, or Homebrew for macOS are often behind several versions of the AWS CLI. To ensure that you have the latest version, see Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.

You can check your AWS CLI version with the following command:

aws --version

Note

Your system's Python version must be Python 3, or Python 2.7.9 or greater. Otherwise, you receive hostname doesn't match errors with AWS CLI calls to Amazon EKS. For more information, see What are "hostname doesn't match" errors? in the Python Requests FAQ.

Step 1: Create Your Amazon EKS Cluster

Now you can create your Amazon EKS cluster.

Important

When an Amazon EKS cluster is created, the IAM entity (user or role) that creates the cluster is added to the Kubernetes RBAC authorization table as the administrator (with system:master permissions. Initially, only that IAM user can make calls to the Kubernetes API server using kubectl. For more information, see Managing Users or IAM Roles for your Cluster. Also, the AWS IAM Authenticator for Kubernetes uses the AWS SDK for Go to authenticate against your Amazon EKS cluster. If you use the console to create the cluster, you must ensure that the same IAM user credentials are in the AWS SDK credential chain when you are running kubectl commands on your cluster.

If you install and configure the AWS CLI, you can configure the IAM credentials for your user. These also work for the AWS IAM Authenticator for Kubernetes. If the AWS CLI is configured properly for your user, the AWS IAM Authenticator for Kubernetes can find those credentials as well. For more information, see Configuring the AWS CLI in the AWS Command Line Interface User Guide.

To create your cluster with the console

  1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.

  2. Choose Create cluster.

    Note

    If your IAM user does not have administrative privileges, you must explicitly add permissions for that user to call the Amazon EKS API operations. For more information, see Creating Amazon EKS IAM Policies.

  3. On the Create cluster page, fill in the following fields and then choose Create:

    • Cluster name: A unique name for your cluster.

    • Kubernetes version: The version of Kubernetes to use for your cluster. By default, the latest available version is selected.

    • Role ARN: Select the IAM role that you created with Create your Amazon EKS Service Role.

    • VPC: The VPC you created with Create your Amazon EKS Cluster VPC. You can find the name of your VPC in the drop-down list.

    • Subnets: The SubnetIds values (comma-separated) from the AWS CloudFormation output that you generated with Create your Amazon EKS Cluster VPC. By default, the available subnets in the above VPC are preselected.

    • Security Groups: The SecurityGroups value from the AWS CloudFormation output that you generated with Create your Amazon EKS Cluster VPC. This security group has ControlPlaneSecurityGroup in the drop-down name.

      Important

      The worker node AWS CloudFormation template modifies the security group that you specify here, so Amazon EKS strongly recommends that you use a dedicated security group for each cluster control plane (one per cluster). If this security group is shared with other resources, you might block or disrupt connections to those resources.

    • Endpoint private access: Choose whether to enable or disable private access for your cluster's Kubernetes API server endpoint. If you enable private access, Kubernetes API requests that originate from within your cluster's VPC will use the private VPC endpoint. For more information, see Amazon EKS Cluster Endpoint Access Control.

    • Endpoint public access: Choose whether to enable or disable public access for your cluster's Kubernetes API server endpoint. If you disable public access, your cluster's Kubernetes API server can only receive requests from within the cluster VPC. For more information, see Amazon EKS Cluster Endpoint Access Control.

    • Logging – For each individual log type, choose whether the log type should be Enabled or Disabled. By default, each log type is Disabled. For more information, see Amazon EKS Control Plane Logging

    Note

    You might receive an error that one of the Availability Zones in your request doesn't have sufficient capacity to create an Amazon EKS cluster. If this happens, the error output contains the Availability Zones that can support a new cluster. Retry creating your cluster with at least two subnets that are located in the supported Availability Zones for your account. For more information, see Insufficient Capacity.

  4. On the Clusters page, choose the name of your newly created cluster to view the cluster information.

  5. The Status field shows CREATING until the cluster provisioning process completes. Cluster provisioning usually takes between 10 and 15 minutes.

To create your cluster with the AWS CLI

  1. Create your cluster with the following command. Substitute your cluster name, the Amazon Resource Name (ARN) of your Amazon EKS service role that you created in Create your Amazon EKS Service Role, and the subnet and security group IDs for the VPC that you created in Create your Amazon EKS Cluster VPC.

    aws eks --region region create-cluster --name devel --role-arn arn:aws:iam::111122223333:role/eks-service-role-AWSServiceRoleForAmazonEKS-EXAMPLEBKZRQR --resources-vpc-config subnetIds=subnet-a9189fe2,subnet-50432629,securityGroupIds=sg-f5c54184

    Important

    If you receive a syntax error similar to the following, you might be using a preview version of the AWS CLI for Amazon EKS. The syntax for many Amazon EKS commands has changed since the public service launch. Update your AWS CLI version to the latest available and delete the custom service model directory at ~/.aws/models/eks.

    aws: error: argument --cluster-name is required

    Note

    If your IAM user does not have administrative privileges, you must explicitly add permissions for that user to call the Amazon EKS API operations. For more information, see Creating Amazon EKS IAM Policies.

    Output:

    { "cluster": { "name": "devel", "arn": "arn:aws:eks:us-west-2:111122223333:cluster/devel", "createdAt": 1527785885.159, "version": "1.10", "roleArn": "arn:aws:iam::111122223333:role/eks-service-role-AWSServiceRoleForAmazonEKS-AFNL4H8HB71F", "resourcesVpcConfig": { "subnetIds": [ "subnet-a9189fe2", "subnet-50432629" ], "securityGroupIds": [ "sg-f5c54184" ], "vpcId": "vpc-a54041dc" }, "status": "CREATING", "certificateAuthority": {} } }
  2. Cluster provisioning usually takes between 10 and 15 minutes. You can query the status of your cluster with the following command. When your cluster status is ACTIVE, you can proceed.

    aws eks --region region describe-cluster --name devel --query cluster.status

Step 2: Create a kubeconfig File

In this section, you create a kubeconfig file for your cluster with the AWS CLI update-kubeconfig command. If you do not want to install the AWS CLI, or if you would prefer to create or update your kubeconfig manually, see Create a kubeconfig for Amazon EKS.

To create your kubeconfig file with the AWS CLI

  1. Ensure that you have at least version 1.16.73 of the AWS CLI installed. To install or upgrade the AWS CLI, see Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.

    Note

    Your system's Python version must be Python 3, or Python 2.7.9 or greater. Otherwise, you receive hostname doesn't match errors with AWS CLI calls to Amazon EKS. For more information, see What are "hostname doesn't match" errors? in the Python Requests FAQ.

    You can check your AWS CLI version with the following command:

    aws --version

    Important

    Package managers such yum, apt-get, or Homebrew for macOS are often behind several versions of the AWS CLI. To ensure that you have the latest version, see Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.

  2. Use the AWS CLI update-kubeconfig command to create or update your kubeconfig for your cluster.

    • By default, the resulting configuration file is created at the default kubeconfig path (.kube/config) in your home directory or merged with an existing kubeconfig at that location. You can specify another path with the --kubeconfig option.

    • You can specify an IAM role ARN with the --role-arn option to use for authentication when you issue kubectl commands. Otherwise, the IAM entity in your default AWS CLI or SDK credential chain is used. You can view your default AWS CLI or SDK identity by running the aws sts get-caller-identity command.

    • For more information, see the help page with the aws eks update-kubeconfig help command or see update-kubeconfig in the AWS CLI Command Reference.

    aws eks --region region update-kubeconfig --name cluster_name
  3. Test your configuration.

    kubectl get svc

    Note

    If you receive the error "aws-iam-authenticator": executable file not found in $PATH, your kubectl isn't configured for Amazon EKS. For more information, see Installing aws-iam-authenticator.

    If you receive any other authorization or resource type errors, see Unauthorized or Access Denied (kubectl) in the troubleshooting section.

    Output:

    NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE svc/kubernetes ClusterIP 10.100.0.1 <none> 443/TCP 1m

Step 3: Launch and Configure Amazon EKS Worker Nodes

Now that your VPC and Kubernetes control plane are created, you can launch and configure your worker nodes.

Important

Amazon EKS worker nodes are standard Amazon EC2 instances, and you are billed for them based on normal Amazon EC2 On-Demand Instance prices. For more information, see Amazon EC2 Pricing.

To launch your worker nodes

  1. Wait for your cluster status to show as ACTIVE. If you launch your worker nodes before the cluster is active, the worker nodes will fail to register with the cluster and you will have to relaunch them.

  2. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  3. From the navigation bar, select a Region that supports Amazon EKS.

  4. Choose Create stack.

  5. For Choose a template, select Specify an Amazon S3 template URL.

  6. Paste the following URL into the text area and choose Next:

    https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2019-02-11/amazon-eks-nodegroup.yaml
  7. On the Specify Details page, fill out the following parameters accordingly, and choose Next.

    • Stack name: Choose a stack name for your AWS CloudFormation stack. For example, you can call it <cluster-name>-worker-nodes.

    • ClusterName: Enter the name that you used when you created your Amazon EKS cluster.

      Important

      This name must exactly match the name you used in Step 1: Create Your Amazon EKS Cluster; otherwise, your worker nodes cannot join the cluster.

    • ClusterControlPlaneSecurityGroup: Choose the SecurityGroups value from the AWS CloudFormation output that you generated with Create your Amazon EKS Cluster VPC.

    • NodeGroupName: Enter a name for your node group. This name can be used later to identify the Auto Scaling node group that is created for your worker nodes.

    • NodeAutoScalingGroupMinSize: Enter the minimum number of nodes that your worker node Auto Scaling group can scale in to.

    • NodeAutoScalingGroupDesiredCapacity: Enter the desired number of nodes to scale to when your stack is created.

    • NodeAutoScalingGroupMaxSize: Enter the maximum number of nodes that your worker node Auto Scaling group can scale out to.

    • NodeInstanceType: Choose an instance type for your worker nodes.

      Important

      Some instance types might not be available in all regions.

    • NodeImageId: Enter the current Amazon EKS worker node AMI ID for your Region. The AMI IDs for the latest Amazon EKS-optimized AMI (with and without GPU support) are shown in the following table.

      Note

      The Amazon EKS-optimized AMI with GPU support only supports P2 and P3 instance types. Be sure to specify these instance types in your worker node AWS CloudFormation template. By using the Amazon EKS-optimized AMI with GPU support, you agree to NVIDIA's end user license agreement (EULA).

      Kubernetes version 1.12.7Kubernetes version 1.11.9Kubernetes version 1.10.13
      Kubernetes version 1.12.7
      Region Amazon EKS-optimized AMI with GPU support
      US West (Oregon) (us-west-2) ami-0923e4b35a30a5f53 ami-0bebf2322fd52a42e
      US East (N. Virginia) (us-east-1) ami-0abcb9f9190e867ab ami-0cb7959f92429410a
      US East (Ohio) (us-east-2) ami-04ea7cb66af82ae4a ami-0118b61dc2312dee2
      EU (Frankfurt) (eu-central-1) ami-0d741ed58ca5b342e ami-0c57db5b204001099
      EU (Stockholm) (eu-north-1) ami-0c65a309fc58f6907 ami-09354b076296f5946
      EU (Ireland) (eu-west-1) ami-08716b70cac884aaa ami-0fbc930681258db86
      EU (London) (eu-west-2) ami-0c7388116d474ee10 ami-0d832fced2cfe0f7b
      EU (Paris) (eu-west-3) ami-0560aea042fec8b12 ami-0f8fa088b406ebba2
      Asia Pacific (Tokyo) (ap-northeast-1) ami-0bfedee6a7845c26d ami-08e41cc84f4b3f27f
      Asia Pacific (Seoul) (ap-northeast-2) ami-0a904348b703e620c ami-0c43b885e33fdc29e
      Asia Pacific (Mumbai) (ap-south-1) ami-09c3eb35bb3be46a4 ami-0d3ecaf4f3318c714
      Asia Pacific (Singapore) (ap-southeast-1) ami-07b922b9b94d9a6d2 ami-0655b4dbbe2d46703
      Asia Pacific (Sydney) (ap-southeast-2) ami-0f0121e9e64ebd3dc ami-07079cd9ff1b312da
      Kubernetes version 1.11.9
      Region Amazon EKS-optimized AMI with GPU support
      US West (Oregon) (us-west-2) ami-05ecac759c81e0b0c ami-08377056d89909b2a
      US East (N. Virginia) (us-east-1) ami-02c1de421df89c58d ami-06ec2ea207616c078
      US East (Ohio) (us-east-2) ami-03b1b6cc34c010f9c ami-0e6993a35aae3407b
      EU (Frankfurt) (eu-central-1) ami-0c2709025eb548246 ami-0bf09c13f4204ce9d
      EU (Stockholm) (eu-north-1) ami-084bd3569d08c6e67 ami-0a1714bb5be631b59
      EU (Ireland) (eu-west-1) ami-0e82e73403dd69fa3 ami-0b4d0f56587640d5a
      EU (London) (eu-west-2) ami-0da9aa88dd2ec8297 ami-00e98f9e6fd2319e5
      EU (Paris) (eu-west-3) ami-099369bc73d1cc66f ami-0039e2556e6290828
      Asia Pacific (Tokyo) (ap-northeast-1) ami-0d555d5f56c843803 ami-07fc636e8f6d3e18b
      Asia Pacific (Seoul) (ap-northeast-2) ami-0144ae839b1111571 ami-002057772097fcef9
      Asia Pacific (Mumbai) (ap-south-1) ami-02071c0110dc365ba ami-04fe7f4c75aac7196
      Asia Pacific (Singapore) (ap-southeast-1) ami-00c91afdb73cf7f93 ami-08d5da0b12751a31f
      Asia Pacific (Sydney) (ap-southeast-2) ami-05f4510fcfe56961c ami-04024dd8e0b9e36ff
      Kubernetes version 1.10.13
      Region Amazon EKS-optimized AMI with GPU support
      US West (Oregon) (us-west-2) ami-05a71d034119ffc12 ami-0901518d7557125c8
      US East (N. Virginia) (us-east-1) ami-03a1e71fb42fc37dd ami-00f74c3728d4ca27d
      US East (Ohio) (us-east-2) ami-093d55c2ba99ab2c8 ami-0a788defb66cdfffb
      EU (Frankfurt) (eu-central-1) ami-03bdf8079f6c013c5 ami-0a8536a894bd4ea06
      EU (Stockholm) (eu-north-1) ami-0be77fe86d741fc81 ami-05baf7a6c293fe2ed
      EU (Ireland) (eu-west-1) ami-06368da7f495b68e9 ami-0f6f3929a9d7a418e
      EU (London) (eu-west-2) ami-0f1f2189b4741bc60 ami-0a12396b818bc2383
      EU (Paris) (eu-west-3) ami-03a9acb0f6e0d424d ami-086d5edcaacd0ccfd
      Asia Pacific (Tokyo) (ap-northeast-1) ami-0c9fb6a3fda95d373 ami-073f06a1edd22ae2e
      Asia Pacific (Seoul) (ap-northeast-2) ami-00ea4ea959f28b4cf ami-0baff950f5217e54e
      Asia Pacific (Mumbai) (ap-south-1) ami-0f07478f5c5eb9e20 ami-033bd2c2a3431923e
      Asia Pacific (Singapore) (ap-southeast-1) ami-05dac5d0ada75e22f ami-09defa93988984fa1
      Asia Pacific (Sydney) (ap-southeast-2) ami-00513f18e1900ce1e ami-00d9364d705e902c9

      Note

      The Amazon EKS worker node AMI is based on Amazon Linux 2. You can track security or privacy events for Amazon Linux 2 at the Amazon Linux Security Center or subscribe to the associated 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.

    • KeyName: Enter the name of an Amazon EC2 SSH key pair that you can use to connect using SSH into your worker nodes with after they launch. If you don't already have an Amazon EC2 keypair, you can create one in the AWS Management Console. For more information, see Amazon EC2 Key Pairs in the Amazon EC2 User Guide for Linux Instances.

      Note

      If you do not provide a keypair here, the AWS CloudFormation stack creation fails.

    • BootstrapArguments: Specify any optional arguments to pass to the worker node bootstrap script, such as extra kubelet arguments. For more information, view the bootstrap script usage information at https://github.com/awslabs/amazon-eks-ami/blob/master/files/bootstrap.sh

    • VpcId: Enter the ID for the VPC that you created in Create your Amazon EKS Cluster VPC.

    • Subnets: Choose the subnets that you created in Create your Amazon EKS Cluster VPC.

  8. On the Options page, you can choose to tag your stack resources. Choose Next.

  9. On the Review page, review your information, acknowledge that the stack might create IAM resources, and then choose Create.

  10. When your stack has finished creating, select it in the console and choose the Outputs tab.

  11. Record the NodeInstanceRole for the node group that was created. You need this when you configure your Amazon EKS worker nodes.

To enable worker nodes to join your cluster

  1. Download, edit, and apply the AWS authenticator configuration map:

    1. Download the configuration map with the following command:

      curl -o aws-auth-cm.yaml https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2019-02-11/aws-auth-cm.yaml
    2. Open the file with your favorite text editor. Replace the <ARN of instance role (not instance profile)> snippet with the NodeInstanceRole value that you recorded in the previous procedure, and save the file.

      Important

      Do not modify any other lines in this file.

      apiVersion: v1 kind: ConfigMap metadata: name: aws-auth namespace: kube-system data: mapRoles: | - rolearn: <ARN of instance role (not instance profile)> username: system:node:{{EC2PrivateDNSName}} groups: - system:bootstrappers - system:nodes
    3. Apply the configuration. This command might take a few minutes to finish.

      kubectl apply -f aws-auth-cm.yaml

      Note

      If you receive the error "aws-iam-authenticator": executable file not found in $PATH, your kubectl isn't configured for Amazon EKS. For more information, see Installing aws-iam-authenticator.

      If you receive any other authorization or resource type errors, see Unauthorized or Access Denied (kubectl) in the troubleshooting section.

  2. Watch the status of your nodes and wait for them to reach the Ready status.

    kubectl get nodes --watch
  3. (GPU workers only) If you chose a P2 or P3 instance type and the Amazon EKS-optimized AMI with GPU support, you must apply the NVIDIA device plugin for Kubernetes as a daemon set on your cluster with the following command.

    Note

    If your cluster is running a different Kubernetes version than 1.12, be sure to substitute your cluster's version in the following URL.

    kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v1.12/nvidia-device-plugin.yml

Step 4: Launch a Guest Book Application

In this section, you create a sample guest book application to test your new cluster.

Note

For more information about setting up the guest book example, see https://github.com/kubernetes/examples/blob/master/guestbook-go/README.md in the Kubernetes documentation.

To create your guest book application

  1. Create the Redis master replication controller.

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/examples/master/guestbook-go/redis-master-controller.json

    Note

    If you receive the error "aws-iam-authenticator": executable file not found in $PATH, your kubectl isn't configured for Amazon EKS. For more information, see Installing aws-iam-authenticator.

    If you receive any other authorization or resource type errors, see Unauthorized or Access Denied (kubectl) in the troubleshooting section.

    Output:

    replicationcontroller "redis-master" created
  2. Create the Redis master service.

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/examples/master/guestbook-go/redis-master-service.json

    Output:

    service "redis-master" created
  3. Create the Redis slave replication controller.

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/examples/master/guestbook-go/redis-slave-controller.json

    Output:

    replicationcontroller "redis-slave" created
  4. Create the Redis slave service.

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/examples/master/guestbook-go/redis-slave-service.json

    Output:

    service "redis-slave" created
  5. Create the guestbook replication controller.

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/examples/master/guestbook-go/guestbook-controller.json

    Output:

    replicationcontroller "guestbook" created
  6. Create the guestbook service.

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/examples/master/guestbook-go/guestbook-service.json

    Output:

    service "guestbook" created
  7. Query the services in your cluster and wait until the External IP column for the guestbook service is populated.

    Note

    It might take several minutes before the IP address is available.

    kubectl get services -o wide
  8. After your external IP address is available, point a web browser to that address at port 3000 to view your guest book. For example, http://a7a95c2b9e69711e7b1a3022fdcfdf2e-1985673473.us-west-2.elb.amazonaws.com:3000

    Note

    It might take several minutes for DNS to propagate and for your guest book to show up.

    
                        Guest book

    Important

    If you are unable to connect to the external IP address with your browser, be sure that your corporate firewall is not blocking non-standards ports, like 3000. You can try switching to a guest network to verify.

Step 5: Cleaning Up Guest Book Objects

When you are finished experimenting with your guest book application, you should clean up the resources that you created for it. The following command deletes all of the services and replication controllers for the guest book application:

kubectl delete rc/redis-master rc/redis-slave rc/guestbook svc/redis-master svc/redis-slave svc/guestbook

Note

If you receive the error "aws-iam-authenticator": executable file not found in $PATH, your kubectl isn't configured for Amazon EKS. For more information, see Installing aws-iam-authenticator.

If you receive any other authorization or resource type errors, see Unauthorized or Access Denied (kubectl) in the troubleshooting section.

If you are done with your Amazon EKS cluster, you should delete it and its resources so that you do not incur additional charges. For more information, see Deleting a Cluster.