Skip to content

Latest commit

 

History

History
238 lines (143 loc) · 8.64 KB

aws.md

File metadata and controls

238 lines (143 loc) · 8.64 KB

Getting Started

Install kops

From Homebrew:

brew update && brew install --HEAD kops

From Source:

go get -d k8s.io/kops
cd ${GOPATH}/src/k8s.io/kops/
git checkout release
make

See our installation guide for more information

Install kubectl

It is a good idea to grab a fresh copy of kubectl now if you don't already have it.

OS X

brew install kubernetes-cli

Other Platforms

Setup your environment

Setting up a kops IAM user

In this example we will be using a dedicated IAM user to use with kops. This user will need basic API security credentials in order to use kops. Create the user and credentials using the AWS console. More information.

Kubernetes kops uses the official AWS Go SDK, so all we need to do here is set up your system to use the official AWS supported methods of registering security credentials defined here. Here is an example using the aws command line tool to set up your security credentials.

OS X

brew update && brew install awscli
aws configure # Input your credentials here
aws iam list-users

Other Platforms

Official documentation here

We should now be able to pull a list of IAM users from the API, verifying that our credentials are working as expected.

Configure DNS

We will now need to set up DNS for cluster, find one of the scenarios below (A,B,C) that match your situation.

(A) Setting up DNS for your cluster, with AWS as your registrar

If you bought your domain with AWS, then you should already have a hosted zone in Route53.

If you plan on using your base domain, then no more work is needed. If you plan on using a subdomain to build your clusters on you will need to create a 2nd hosted zone in Route53.

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

(B) Setting up DNS for your cluster, with another registrar.

If you bought your domain elsewhere, and would like to dedicate the entire domain to AWS you should follow the guide here

(C) Setting up a subdomain for clusters, with another registrar while keeping your top level domain the same

If you bought your domain elsewhere, but only want to use a subdomain in AWS Route53 you must modify your registrar's NS (NameServer) records. See the example below.

Here we will be creating a hosted zone in AWS Route53, and migrating the subdomain's NS records to your other registrar.

You might need to grab jq for some of these.

  • Create the subdomain
ID=$(uuidgen) && aws route53 create-hosted-zone --name subdomain.kubernetes.com --caller-reference $ID
  • Note your hosted zone ID
aws route53 list-hosted-zones | jq '.HostedZones[] | select(.Name=="subdomain.kubernetes.com") | .Id'
  • Note your nameservers for the subdomain
aws route53 get-hosted-zone --id "/hostedzone/Z1K7H5F7891012" | jq .DelegationSet.NameServers

  • You will now go to your registrars page and log in. You will need to create a new subdomain, and use the 4 NS records listed above for the new subdomain. This MUST be done in order to use your cluster. Do NOT change your top level NS record, or you might take your site offline.

  • Information on adding NS records with Godaddy.com

  • Information on adding NS records with Google Cloud Platform

Testing your DNS setup

You should now able to dig your domain (or subdomain) and see the AWS Name Servers on the other end. This MUST be completed before moving on.

dig ns subdomain.kubernetes.com
;; ANSWER SECTION:
subdomain.kubernetes.com.        172800  IN  NS  ns-613.awsdns-13.net.
subdomain.kubernetes.com.        172800  IN  NS  ns-75.awsdns-04.org.
subdomain.kubernetes.com.        172800  IN  NS  ns-1022.awsdns-35.com.
subdomain.kubernetes.com.        172800  IN  NS  ns-1149.awsdns-27.co.uk.

Setting up a state store for your cluster

In this example we will be creating a dedicated S3 bucket for kops to use. This is where kops will store the state of your cluster and the representation of your cluster, and serves as the source of truth for our cluster configuration throughout the process. We will call this kubernetes-com-state-store. We recommend keeping the creation confined to us-east-1, otherwise more input will be needed here.

aws s3api create-bucket --bucket kubernetes-com-state-store --region us-east-1

Creating your first cluster

Setup your environment for kops

Okay! We are ready to start creating our first cluster. Lets first set up a few environmental variables to make this process as clean as possible.

export NAME=myfirstcluster.kubernetes.com
export KOPS_STATE_STORE=s3://kubernetes-com-state-store

Note: You don’t have to use environmental variables here. You can always define the values using the –name and –state flags later.

Form your create cluster command

We will need to note which availability zones are available to us. In this example we will be deploying our cluster to the us-west-1 region.

aws ec2 describe-availability-zones --region us-west-2

Lets form our create cluster command. This is the most basic example, a more verbose example on can be found here

kops create cluster \
    --zones us-west-2a \
    ${NAME}

kops will deploy these instances using AWS auto scaling groups, so each instance should be ephemeral and will rebuild itself if taken offline for any reason.

Cluster Configuration

We now have created the underlying cluster configuration, lets take a look at every aspect that will define our cluster.

kops edit cluster ${NAME}

This will open in your text editor of choice. You can always change your editor of choice

cat "export EDITOR=/usr/bin/emacs" ~/.bash_profile && source ~/.bash_profile

This will open up the cluster config (that is actually stored in the S3 bucket we created earlier!) in your favorite text editor. Here is where we can optionally really tweak our cluster for our use case. In this tutorial, we leave it default for now.

Apply the changes

kops update cluster ${NAME} --yes

Accessing your cluster

A friendly reminder that kops runs asynchronously, and it will take your cluster a few minutes to come online.

Remember when you installed kubectl earlier? The configuration for your cluster was automatically generated and written to ~/.kube/config for you!

A simple Kubernetes API call can be used to check if the API is online and listening. Let's use kubectl

kubectl get nodes

You will see a list of nodes that should match the --zones flag defined earlier. This is a great sign that your Kubernetes cluster is online and working.

Also kops ships with a handy validation tool that can be ran to ensure your cluster is working as expected.

kops validate cluster

Another great one liner

kubectl -n kube-system get po

What's next?

Kops has a ton of great features, and an amazing support team. We recommend researching other interesting modes to learn more about generating Terraform configurations, or running your cluster in HA (Highly Available). Also be sure to check out how to run a private network topology in AWS.

Explore the program, and work on getting your cluster config hammered out!

Feedback

We love feedback from the community, and if you are reading this we would love to hear from you and get your thoughts. Read more about getting involved to find out how to track us down.

Legal

AWS Trademark used with limited permission under the AWS Trademark Guidelines

Kubernetes Logo used with permission under the Kubernetes Branding Guidelines