Kubernetes (AKA "k8s")

From kubernetes.io: Kubernetes is an open source orchestration

system for Docker containers. It handles scheduling onto nodes in a

compute cluster and actively manages workloads to ensure that their

state matches the users declared intentions. Using the concepts of

"labels" and "pods", it groups the containers which make up an

application into logical units for easy management and

discovery.

We use it to host some of our web applications at FP Complete.

In this article we will show you how to deploy a Kubernetes cluster

to Amazon's AWS cloud, create a Haskell web application, build the

application with Stack and finally deploy the application with

Docker & Kubernetes. The whole process should take about 10

minutes.

Download the command line interface kubectl here (the binary CLI for your OS will be found in the tarball).

You'll need this executable in order to interact with your deployed

Kubernetes cluster. Download it now & make sure it's in your

PATH.

If you are curious about all the things you can do with Kubernetes, you can find the documentation online. There's also an active mail-list and IRC channel.

kube-aws Deployment Tool

The CoreOS team has created a nice AWS CloudFormation tool for

deploying working clusters of Kubernetes on AWS with ease. This is

much simpler than my blog post from last winter (shows the guts of a

CloudFormation deployment with CoreOS & Kubernetes.) These days all

we need is one command line tool & a tiny yaml manifest file.

Download the command line tool here and put it in your PATH.

Deploy Kubernetes

Setup your AWS environment variables

Make sure you have at least the following environment variables set:

• AWS_ACCESS_KEY_ID

• AWS_SECRET_ACCESS_KEY

• AWS_DEFAULT_REGION

Create a folder for the new cluster

This will house the TLS certificates & configuration for communicating with Kubernetes after launch.

mkdir -p ~/.kube/clusters/kube/
cd ~/.kube/

Create a ~/.kube/clusters/kube/cluster.yaml manifest file

This file will be used by kube-aws when launching a cluster (or destroying a cluster. See kube-aws --help for more options.)

# cluster name is whatever you want it to be
clusterName: kube
# the key name is, of course, the aws key-pair name
keyName: kubernetes
# pick a region and availability zone
region: us-west-2
availabilityZone: us-west-2a
# pick a domain name for your cluster
externalDNSName: kube.mydomain.com
# pick the size of your cluster
workerCount: 3

Launch with kube-aws

Once our manifest is ready we can launch our cluster.

kube-aws up --config=~/.kube/clusters/kube/cluster.yaml

This will output the IP address of the master node. Take note of the IP address for the next step.

Set a DNS A record for the Kubernetes IP address

Set an external DNS 'A' record with master node's IP address.

kube.mydomain.com. IN A <<IPADDRESS

If you don't have control of DNS for a domain, you can put an entry into your /etc/hosts file.

kube.mydomain.com <<IPADDRESS

Configure kubectl

Then we'll want to link the kubectl configuration file that

kube-aws produced into the right spot (~/.kube/config) so we can

talk to our cluster.

ln -sf ~/.kube/clusters/kube/kubeconfig ~/.kube/config

Interact with the Kubernetes cluster

Everything should be ready to interact with our new cluster.

Let's list the (worker) nodes. You should see 3 based on our

manifest file above.

kubectl get nodes

Haskell Web Service

Start a new haskell package

Let's create a new directory for our example haskell web service. (We could have used stack new hello to create

an application stub but our needs are as simple as they get. We'll

just create a couple of files & our project will be complete.)

mkdir hello
cd hello

Create a hello.cabal

As with any Haskell application we need a cabal file describing the project.

name:                hello
version:             0.1.0
license:             BSD3
build-type:          Simple
cabal-version:       >=1.10
executable hello
  default-language:    Haskell2010
  ghc-options:         -threaded -rtsopts -with-rtsopts=-N
  main-is:             Main.hs
  build-depends:       base
                     , http-types
                     , wai
                     , warp

Create a stack.yaml

We also need a stack.yaml file. This sets the resolver (and the

GHC version. In this case it's 7.10.2). The stack.yaml file also

describes what packages we are building and it has container image

settings.

resolver: lts-3.14
packages: [.]
image:
  container:
    base: hello:base

Create a Dockerfile

In order for Stack to build our application & package a docker

container, we need to setup a base image with all our application

dependencies. Put anything in your base image that your application

will need. In our case today, we only need libgmp which is used by

most haskell applications.

FROM ubuntu:14.04
RUN apt-get update && apt-get install -y libgmp10

Now we need to build & tag the base image. You most likely only

need to do this once. You can optionally tag this base image &

share it on DockerHub with your co-workers.

docker build -t hello:base

Create a Main.hs

Every haskell application needs it's Main module. This one

simply fires up a Warp web-server on port 8080 and always serves

"hello world" as plain text.

{-# LANGUAGE OverloadedStrings #-}

import Network.HTTP.Types (status200)
import Network.Wai (responseLBS)
import Network.Wai.Handler.Warp (run)

main :: IO ()
main =
  run 8080
      (rq rs ->
         rs (responseLBS status200
                         [("Content-Type","text/plain")]
                         "hello world"))

Build with Stack

This will compile your haskell executable and layer it on top of your 'base' image.

stack image container

You should now see a hello docker image if you list your images.

Test the image locally

We should now be able to run the docker image locally & see it work. Try it.

docker run -i -t --rm -p 8080:8080 hello hello

In another window use curl or your web-browser to access port 8080.

curl -v http://localhost:8080

Press ctrl-c when you are done with the local docker web-server.

Push the image to dockerhub

Next we'll tag the hello image with our dockerhub user prefix and a version. Then we'll push the image up to dockerhub.com.

docker tag hello dysinger/hello:0.1.0
docker push dysinger/hello:0.1.0

Deploy to Kubernetes

Now that we have our application written & published we can

deploy it to our new Kubernetes cluster. In order to deploy any

cluster of web-servers to Kubernetes you need two basic yaml files.

One is the Replication Controller file & the other is the Service

file.

Create a hello-rc.yaml

The Replication Controller file describes our docker container's

needs (ports, volumes, number of replicas, etc). Kubernetes will

use this information to maintain a number of docker containers on

the cluster running your application.

apiVersion: v1
kind: ReplicationController
metadata:
  name: hello
spec:
  replicas: 2
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
      - name: hello
        image: dysinger/hello:0.1.0
        command:
        - hello
        ports:
        - name: http
          containerPort: 8080

Create a hello-svc.yaml

The Service file describes the external interface for your

replicated application. It can optionally create a load-balancer

and map ports into your replicated application. If you need your

application to be exposed to the internet, then you need a Service

file.

apiVersion: v1
kind: Service
metadata:
  name: hello
  labels:
    app: hello
spec:
  ports:
  - name: http
    port: 80
    targetPort: http
  selector:
    app: hello
  type: LoadBalancer

Deploy the Controller & Service to Kubernetes

Next we use the kubectl command line tool to tell

Kubernetes to deploy this application. We can do it with one

command.

kubectl create -f hello-rc.yaml -f hello-svc.yaml

Describe the running Service

We can ask Kubernetes how the deployment went with the get subcommand.

kubectl get pods

You should see your new hello application being deployed (possibly not ready yet.)

You should see 2 of our hello applications deployed on 2 of our 3 worker nodes.

After a few minutes you should be able to get information about the applications external interface.

kubectl describe svc hello

This will show you the Amazon ELB DNS name. You can stick this

hostname in your browser & your should see 'hello world'. You can

update DNS with a CNAME from your domain to the Amazon ELB DNS name

if you would like a shorter URL.

hello.mydomain.com. CNAME <<ELB-HOSTNAME