Getting started with Kubernetes on AWS

This a step-by-step guide on how to create a Kubernetes cluster on top of AWS infrastructure and how to run a simple application in it. I've tried to make it simple and clear, specially for beginners.

This is what we need before we start:

  • AWS admin account
  • A domain

We need a domain because the cluster's name must be a valid DNS name. I'm going to use domain and as the cluster's name. We'll be running the commands on a Ubuntu 16.10 machine. Links for others environments will be provided.

Installing KOPS

Kubernetes offers a simple tool, called kops, that makes the creation of our cluster very easy. Let's install it.

curl -LO  
chmod +x kops-linux-amd64  
sudo mv kops-linux-amd64 /usr/local/bin/kops  

We can see it from the url the we installed kops 1.5.1 (currently the latest version). You can download any version by changing that. Here we can check all the releases available. We can also check what is changing from version to version.

Setting the AWS environment

We need, basically, two resources created on AWS before we can create our cluster. We're going to use the aws command line for creating them, so make sure you have it by following Installing the AWS Command Line Interface.

The first resource is a S3 bucket responsible for storing the cluster configuration file. From docs:

kops lets you manage your clusters even after installation. To do this, it must keep track of the clusters that you have created, along with their configuration, the keys they are using etc. This information is stored in an S3 bucket

I'll create a S3 bucket named brunocalza-k8s-state. Since bucket's name are global, you should pick a different name.

aws s3api create-bucket --bucket brunocalza-k8s-state --region us-east-1  

The second resource is a hosted zone for the domain we want our cluster running on. The reason we need a domain can be found on docs, as follows:

kops uses DNS for discovery, both inside the cluster and so that you can reach the kubernetes API server from clients.

kops has a strong opinion on the cluster name: it should be a valid DNS name. By doing so you will no longer get your clusters confused, you can share clusters with your colleagues unambiguously, and you can reach them without relying on remembering an IP address.

Since my cluster's name is, the command to create a hosted zone is

ID=$(uuidgen) && aws route53 create-hosted-zone --name --caller-reference $ID  

This is going to automatically create a name server (NS) record that identifies four name servers. We can check these four names servers in the response of the above command.

    "HostedZone": {
        "ResourceRecordSetCount": 2, 
        "CallerReference": "48d8c9ca-55ee-4e9e-9280-a3ac4cc21527", 
        "Config": {
            "PrivateZone": false
        "Id": "/hostedzone/Z2DHV8JMRBMA9X", 
        "Name": ""
    "DelegationSet": {
        "NameServers": [
    "Location": "", 
    "ChangeInfo": {
        "Status": "PENDING", 
        "SubmittedAt": "2017-03-08T00:23:41.512Z", 
        "Id": "/change/C3KFK9YH4ZCA3X"

They can be found inside DelegationSet.NameServers. Otherwise, we can check it by logging into AWS Console and going to Route S3.

These name servers are going to be responsible for resolving our cluster's domain name. You have give it to your registrar or your DNS service so that DNS queries can be routed to Amazon Route 53 name servers.

Setting up DNS

We already have our hosted zone created on AWS and with it our name servers that will be responsible for resolving our cluster domain name. Now we have to make sure our domain can be resolved. The is registered by GoDaddy but I'm using a Cloudflare as DNS service. Because of this, on GoDaddy I need to setup the name servers responsible for resolving, like these:

On Cloudflare I needed to create the A record responsible for resolving and the NS records that will responsible for resolving We can see that points to the machine's IP address that my blog is running on. AWS we'll be responsible for resolving This is my setup:

You probably have registered your domain with a different registrar or you're using a different DNS service provider, but you should be able to do something similar to what I've done.

We can check that everything work out correctly by digging our domain

dig ns  

The answer section must return the AWS name servers (it may take awhile)

;; ANSWER SECTION:    300 IN  NS    300 IN  NS    300 IN  NS    300 IN  NS  

This step is critical for a fully functional Kubernetes cluster. Do not move on until you're sure you have validated your NS records.

Creating the cluster

We're ready to create our cluster. Remember our tool kops? It's time to use it. We need just to set two environment variables before using kops.

export KOPS_STATE_STORE=s3://brunocalza-k8s-state  

We're good to go. We'll start by creating the configuration of our cluster. Most of our cluster's config will be the default ones. Let's run

kops create cluster --zones us-east-1a ${NAME}  

This command created the config file that is saved on S3. This file can be downloaded and edited by running

kops edit cluster ${NAME}  

Use the above command to make sure we're using Kubernetes 1.5.3 version. Edit the file if needed. To build our cluster, let's run

kops update cluster ${NAME} --yes  

It may take awhile but in a few minutes your cluster should be up and running. Let's check how many our EC2 instances on AWS console.

Here's a few things kops did for us behind the scenes:

  • kops created for us one master node and two slaves. This is the default config for kops. You can change it by setting --node-count parameter. It also selected, by default, the size of both master and slaves nodes. If you want a different size you must specify by setting --node-size and --master-size
  • kops created two autoscaling groups on AWS, so if any of the nodes fails, a new one will take its place

  • kops created four more DNS records to make all components of our cluster fully resolvable

  • kops copied the public key and put it as authorized key in all nodes. We can ssh into any machine doing ssh

Interacting with the cluster

Kubernetes provide a tool called kubectl to interact with the cluster. Let's install

curl -LO  
chmod +x ./kubectl  
sudo mv ./kubectl /usr/local/bin/kubectl  

We're installing here the version 1.5.3. You can change it for any available version. Just make sure the server and the client have the same version. You can check both versions by running

kubectl version

Client Version: version.Info{Major:"1", Minor:"5", GitVersion:"v1.5.3",GitCommit:"029c3a408176b55c30846f0faedf56aae5992e9b", GitTreeState:"clean", BuildDate:"2017-02-15T06:40:50Z", GoVersion:"go1.7.4", Compiler:"gc", Platform:"linux/amd64"}

Server Version: version.Info{Major:"1", Minor:"5", GitVersion:"v1.5.3", GitCommit:"029c3a408176b55c30846f0faedf56aae5992e9b", GitTreeState:"clean", BuildDate:"2017-02-15T06:34:56Z", GoVersion:"go1.7.4", Compiler:"gc", Platform:"linux/amd64"}  

Let's have some fun and try out some commands. First, we're going to find out some info about the cluster.

kubectl cluster-info

Kubernetes master is running at  
KubeDNS is running at  

The way we interact with our cluster is through kubectl that makes requests to Kubernetes api server. The first line of the response tells us where the api server is running. The second line tells about the KubeDNS which is a component that provides ways of resoving DNS names inside the cluster.

Let's see what kubectl has to tell us about the nodes by running

kubectl get nodes

NAME                            STATUS         AGE  
ip-172-20-36-71.ec2.internal    Ready          34m  
ip-172-20-56-81.ec2.internal    Ready,master   36m  
ip-172-20-60-254.ec2.internal   Ready          34m  

We can get more info about a node by running

kubectl describe node ip-172-20-36-71.ec2.internal  

Running our first app on Kubernetes

Running commands to find out more about our cluster is not so fun. We want to run our containerized applications. The quickest way to run an application on Kubernetes is to use the kubectl run command. Let's run a simple hello world app from a image I built and put it on Dockerhub by typing

kubectl run hello --image=brunocalza/helloworld --port=8080  
deployment "hello" created  

This is not the usual way to run applications on Kubernetes. We just did this for simplicity. You should be using yaml or json files together with kubectl create command.

A lot of things happened behind the scenes. Let's just focus on the essentials. Kubernetes works with a concept called pod. A pod is a group of one or more containers that will always run together, and it has its own ip and hostname. The containers inside it will have a feeling that they are in the same machine, while the containers of others pods will appear to be running on a different one.

What happened here is that a pod was created and scheduled to one of the slave nodes. Docker, that is installed on these machines, pulled the image from Dockerhub and started the container inside the pod. We can check our recently created pod by running

kubectl get pods  
NAME                     READY     STATUS    RESTARTS   AGE  
hello-2126299270-t19gx   1/1       Running   0          12s  

Our pod seems to be running fine. We need a way to access it. The way we make it available to the external world is by creating a service. There different kinds of services and ways to access a pod. For simplicity we're going to be using a Load Balancer. Let's create the service.

kubectl expose deployment hello --type=LoadBalancer --name hello-http  
service "hello-http" exposed  

Let's check it

kubectl get services

NAME         CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE  
hello-http   <pending>     8080:31720/TCP   7s  
kubernetes       <none>        443/TCP          1m

You can see that our recently created service is there, ready to be consumed by its external ip. The external ip is kind of hard to see. We can describe the service to get the full picture

kubectl describe service hello-http

Name:            hello-http  
Namespace:        default  
Labels:            run=hello  
Selector:        run=hello  
Type:            LoadBalancer  
LoadBalancer Ingress:  
Port:            <unset> 8080/TCP  
NodePort:        <unset> 31720/TCP  
Session Affinity:    None

Allright. Let's make our request to our app and see what it happens.


Hello World!  

Our app is running fine on port 8080.

One of the features of Kubernetes is that it can scale our applications very easily. We just need to

kubectl scale --replicas=3 deployment/hello  
deployment "hello" scaled  

It created 2 more pods, making sure that are 3 identical instances of our applications running.

kubectl get pods  
NAME                     READY     STATUS    RESTARTS   AGE  
hello-2126299270-js2xm   1/1       Running   0          8s  
hello-2126299270-pn2qh   1/1       Running   0          8s  
hello-2126299270-t19gx   1/1       Running   0          4m

All threes pods are running under the Load Balancer. So a call to our service may be handled by any of the pods. Make some more calls to the endpoint (we did 10 more requests). Since our app counts the number of requests and log it, we can check how many requests hit each one of our pods by looking at the logs.

kubectl logs hello-2126299270-js2xm  
Started server at localhost::8080  
Number of requests: 1  
Number of requests: 2  
Number of requests: 3

kubectl logs hello-2126299270-pn2qh  
Started server at localhost::8080  
Number of requests: 1  
Number of requests: 2  
Number of requests: 3

kubectl logs hello-2126299270-t19gx  
Started server at localhost::8080  
Number of requests: 1  
Number of requests: 2  
Number of requests: 3  
Number of requests: 4  
Number of requests: 5

We can see that the requests were distributed among the pods.

Installing the dashboard

Kubernetes offers the Dashboard as a easier way to interact with our cluster. We can get it running by executing

$ kubectl create -f

The Dashboard can be accessed at https://<master>/ui, in my case The username is admin and the password is can be obtained by kops get secrets kube --type secret -oplaintext.

Here's how it look likes:

Pretty much everything that can be done through kubectl can be done using the Dashboard. We're not going to cover how to use the Dashboard here, but you can move around the try some things out.

Wrapping up

This guide probably helped you understand a little bit of how Kubernetes applications are run on top of AWS. We've learned:

  • The tool needed to get a cluster up and running : kops
  • How to setup the DNS service to make every component of the cluster resolvable
  • How to interact with the cluster using kubectl
  • How to run our first application
  • How to expose our application
  • Some basic concepts of Kubernetes as: pod, service, deployment and logs
  • How to install a dashboard to make it easier to interact with the cluster

If you don't want your cluster up and running, you can destroy it by running

kops delete cluster ${NAME} --yes  

And here are some resources that helped me a lot to write this tutorial: