We love Kubernetes. It’s becoming a critical platform for us to manage our containers, but deploying Kubernetes clusters is pretty tedious. Luckily for us, cloud providers such as AWS are helping to take care of these tedious tasks so we can focus on what is more important to us, like building apps. This post shows how you can go from a basic AWS account to a Kubernetes cluster for you to deploy your applications.

EKS Environment Setup

To get started, we’ll need to deploy an IAM Role in our AWS account that has permissions to manage Kubernetes clusters on our behalf. Once that’s done, we’ll deploy a new VPC in our account to house our EKS cluster. To speed things up, I’ve created a CloudFormation template to deploy the IAM role for us, and to call the sample Amazon VPC template to deploy a VPC. You’ll need to fill in the parameters for your environment.

NOTE: Be sure that you’re in a region that supports EKS. As of the time of this writing the US regions that can use EKS are us-west-2 (Oregon) and us-east-1 (N. Virginia).

AWSTemplateFormatVersion: 2010-09-09
Description: 'EKS Setup - IAM Roles and Control Plane Cluster'

Metadata:

  "AWS::CloudFormation::Interface":
    ParameterGroups:
      - Label:
          default: VPC
        Parameters:
          - VPCCIDR
      - Label:
          default: Subnets
        Parameters:
          - Subnet01Block
          - Subnet02Block
          - Subnet03Block

Parameters:

  VPCCIDR:
    Type: String
    Description: VPC CIDR Address
    AllowedPattern: "(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})/(\\d{1,2})"
    ConstraintDescription: "Must be a valid IP CIDR range of the form x.x.x.x/x."

  Subnet01Block:
    Type: String
    Description: Subnet01
    AllowedPattern: "(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})/(\\d{1,2})"
    ConstraintDescription: "Must be a valid IP CIDR range of the form x.x.x.x/x."

  Subnet02Block:
    Type: String
    Description: Subnet02
    AllowedPattern: "(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})/(\\d{1,2})"
    ConstraintDescription: "Must be a valid IP CIDR range of the form x.x.x.x/x."

  Subnet03Block:
    Type: String
    Description: Subnet03
    AllowedPattern: "(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})/(\\d{1,2})"
    ConstraintDescription: "Must be a valid IP CIDR range of the form x.x.x.x/x."


Resources:

  EKSRole:
    Type: "AWS::IAM::Role"
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          -
            Effect: "Allow"
            Principal:
              Service:
                - "eks.amazonaws.com"
            Action:
              - "sts:AssumeRole"
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AmazonEKSClusterPolicy
        - arn:aws:iam::aws:policy/AmazonEKSServicePolicy
      Path: "/"
      RoleName: "EKSRole"

  EKSVPC:
    Type: "AWS::CloudFormation::Stack"
    Properties:
      Parameters:
        VpcBlock: !Ref VPCCIDR
        Subnet01Block: !Ref Subnet01Block
        Subnet02Block: !Ref Subnet02Block
        Subnet03Block: !Ref Subnet03Block
      TemplateURL: https://amazon-eks.s3-us-west-2.amazonaws.com/1.10.3/2018-06-05/amazon-eks-vpc-sample.yaml
      TimeoutInMinutes: 10


Outputs:

  EKSRole:
    Value: !Ref EKSRole

  StackRef:
    Value: !Ref EKSVPC

  EKSSecurityGroup:
    Value: !GetAtt EKSVPC.Outputs.SecurityGroups

  EKSVPC:
    Value: !GetAtt EKSVPC.Outputs.VpcId

  EKSSubnets:
    Value: !GetAtt EKSVPC.Outputs.SubnetIdsCode language: JavaScript (javascript)

Use the template above and go to the AWS CloudFormation console within your account. Deploy the template and fill in your VPC addressing for a new VPC and subnets.

After you’ve deployed the template, you’ll see two stacks that have been created. An IAM role and the EKS VPC/subnets.

Once the stack has been completed take note of the outputs which will be used for creating the cluster.

Create the Amazon EKS Control Cluster

Now that we’ve got an environment to work with, its time to deploy the Amazon EKS control cluster. To do this go to the AWS Console and open the EKS Service.

When you open the EKS console, you’ll notice that you don’t have any clusters created yet. We’re about to change that. Enter a cluster name and then click the “next step” button. Similarly you could go into the clusters menu and click Create Cluster if the splash screen doesn’t show the screenshot below.

Fill out the information about your new cluster. Give it a name and select the version. Next select the IAM Role, VPC, Subnets and Security Groups for your Kubernetes Control Plane cluster. This info can be found in the outputs from your CloudFormation Template used to create the environment.

You will see that your cluster is being created. This may take some time, so you can continue with this post to make sure you’ve installed some of the other tools that you’ll need to manage the cluster.

Eventually your cluster will be created and you’ll see a screen like this:

Setup the Tools

You’ll need a few client tools installed in order to manage the Kubernetes cluster on EKS. You’ll need to have the following tools installed:

• AWS CLI v1.15.32 or higher
• Kubectl
• aws-iam-authenticator

The instructions below are to install the tools on a Windows client.

• AWS CLI – To install the AWS CLI, download and run the installer for your version of windows. 64-bit version , 32-bit version. Once you’ve completed running the installer, you’ll need to configure your client with the appropriate settings such as region, access_keys, secret_keys and an output format. This can be accomplished by opening up a cmd prompt and running aws configure. Enter access keys and secret keys with permissions to your AWS resources.

• kubectl – Installing the Amazon EKS-vended kubectl binary, download the kubectl executable for Windows from here: https://amazon-eks.s3-us-west-2.amazonaws.com/1.10.3/2018-06-05/bin/windows/amd64/kubectl.exe and place it in your file path. To test that its working, run:

kubectl version -o yaml

The result should look something like this:

• aws-iam-authenticator – The IAM authenticator is used to integrate your AWS IAM settings with your Kubernetes RBAC permissions. To install this, download the executable for Windows from here: https://amazon-eks.s3-us-west-2.amazonaws.com/1.11.5/2018-12-06/bin/windows/amd64/aws-iam-authenticator.exe and place it in your file path. To test that its working, run:

aws-iam-authenticator --help

The result of that command should return info about your options.

Configure kubectl for EKS

Now that the tools are setup and the control cluster is deployed, we need to configure our kubeconfig file to use with EKS. To do this, the first thing to do is determine the cluster endpoint. You can do this by clicking on your cluster in the GUI and noting the server endpoint and the certificate information.

Note: you could also find this through the aws cli by:

aws eks describe-cluster --name [clustername] --query cluster.endpoint

aws eks describe-cluster --name [clustername] --query cluster.certificateAuthority.data

Next, create a new directory called .kube, if it doesn’t already exist. Once that’s done you’ll need to create a new file in that directory named “config-“[clustername]. After this, we can use the AWS cli to create a new kubeconfig file by running:

aws eks update-kubeconfig --name [cluster_name]Code language: CSS (css)

If things are working correctly, we can run kubectl config get-contexts so we can see the AWS authentication is working. I’ve also run kubectl get svc to show that we can read from the EKS cluster.

Deploy EKS Worker Nodes

Our control cluster is up and running, and we’ve got our clients connected through the aws-iam-authenticator. Now its time to deploy some worker nodes for our containers to run on. To do this, go back to your CloudFormation console and deploy the following CFn template that is provided by AWS.

https://amazon-eks.s3-us-west-2.amazonaws.com/1.10.3/2018-06-05/amazon-eks-nodegroup.yaml

Fill out the deployment information. You’ll need to enter a stack name, number of min/max nodes to scale within, an SSH Key to use, the VPC we deployed earlier, and the subnets. You will also need to enter a ClusterName which must be exactly the same as our control plane cluster we deployed earlier. Lastly, the NodeImageID must be one of the following, depending on your region:

• US-East-1 (N. Virginia) – ami-0c24db5df6badc35a
• US-West-2 (Oregon) – ami-0a2abab4107669c1b
• US-East-2 (Ohio) – ami-0c2e8d28b1f854c68

Deploy your CloudFormation template and wait for it to complete. Once the stack completes, you’ll need to look at the outputs to get the NodeInstanceRole.

The last step is to ensure that our nodes have permissions and can join the cluster. Use the file format below and save it as aws-auth-cm.yaml.

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:nodesCode language: HTML, XML (xml)

Replace ONLY the <ARN of instance role (not instance profile)> section with the NodeInstanceRole we got from the outputs of our CloudFormation stack. Save the file and then apply the configmap to your EKS cluster by running:

kubectl apply -f aws-auth-cm.yaml

After we run the command our cluster should be fully working. We can run “get nodes” to see the worker nodes listed in the cluster.

NOTE: the status of the cluster will initially show “NotReady”. Re-running the command or using the –watch switch will let you see when the nodes are fully provisioned.

Deploy Your Apps

Congratulations, you’ve build your Kubernetes cluster on Amazon EKS. Its time to deploy your apps which is outside of this blog post. If you want to try out an app to prove that its working, try one of the deployments from the kubernetes.io tutorials such as their guestbook app.

 kubectl apply -f https://k8s.io/examples/application/guestbook/redis-master-deployment.yaml

From here on out, it’s up to you. Start deploying your replication controllers, pods, services, etc as you’d like.