github.com/kubernetes-incubator/kube-aws@v0.16.4/docs/tutorials/quick-start.md (about) 1 # Quick Start 2 3 Get started with kube-aws and deploy a fully-functional Kubernetes cluster running on Flatcar Container Linux using AWS CloudFormation. 4 5 After completing this guide, you will be able to deploy applications to Kubernetes on AWS and interact with the Kubernetes API using the `kubectl` CLI tool. 6 7 # Pre-requisites 8 9 Prior to using setting up your first Kubernetes cluster using kube-aws, you will need to setup the following. More details on each pre-requisite are available in the rest of the documentation. 10 11 1. [Install](http://docs.aws.amazon.com/cli/latest/userguide/installing.html) and [Configure](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) the AWS CLI 12 1. [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) which is the CLI for controlling a Kubernetes cluster 13 1. Create an [EC2 Key Pair](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) in your chosen AWS region and record the name of the key for step 2 in this guide 14 1. Have a Route 53 hosted zone ready to expose the Kubernetes API and record the hosted zone ID and domain name for step 2 in this guide 15 1. Create a [KMS Key](http://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in your chosen AWS region and record the ARN for step 2 in this guide 16 1. Create an [S3 Bucket](http://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) to store kube-aws assets and record the bucket name for step 2 and 3 in this guide 17 18 # Step 1: Download kube-aws 19 20 Go to the [releases](https://github.com/kubernetes-incubator/kube-aws/releases) and download the latest release tarball for your architecture. Extract the binary and add kube-aws to your path: 21 22 ```bash 23 ➜ tar zxvf kube-aws-${PLATFORM}.tar.gz 24 ➜ sudo mv ${PLATFORM}/kube-aws /usr/local/bin 25 ➜ kube-aws --help 26 ``` 27 28 # Step 2: Render 29 30 First run `init` using the information from the pre-requisites section. For example: 31 32 ```bash 33 ➜ kube-aws init \ 34 --cluster-name=quick-start-k8 \ 35 --region=us-west-1 \ 36 --availability-zone=us-west-1a \ 37 --hosted-zone-id=ZBN159WIK8JJD \ 38 --external-dns-name=quick-start-k8s.mycompany.com \ 39 --key-name=ec2-key-pair-name \ 40 --kms-key-arn="arn:aws:kms:us-west-1:123456789012:key/c4f79cb0-f9fb-434a-ac3c-47c5697d51e6" \ 41 --s3-uri=s3://kube-aws-assets/ 42 ``` 43 44 This will generate a `cluster.yaml` file which forms the main configuration for your new cluster. The `cluster.yaml` has many options to adjust your cluster, leave them as the defaults for now. 45 46 Next use `render credentials` to generate new credentials for your cluster into the `credentials` directory: 47 48 ```bash 49 ➜ kube-aws render credentials --generate-ca 50 ``` 51 52 The files generated are TLS assets which allow communication between nodes and also allow super admins to administer the cluster. After the quick start you may wish to use your own CA assets. 53 54 Next use `render stack` to generate the CloudFormation stack templates and user data into the `stack-templates` and `userdata` directories: 55 56 ```bash 57 ➜ kube-aws render stack 58 ``` 59 60 The files generated form the basis of the deployment. 61 62 Before we move onto deploying, let's run `validate` to check the work above using the S3 bucket name from the pre-requisites section. For example: 63 64 ```bash 65 ➜ kube-aws validate 66 ``` 67 68 # Step 3: Launch 69 70 Now you've generated and validated the various assets needed to launch a new cluster, let's run the deploy! Run `apply` using the S3 bucket name from the pre-requisites section. For example: 71 72 ```bash 73 ➜ kube-aws apply 74 ``` 75 76 # Step 4: Deploy an Application 77 78 Let's deploy our first application to the new cluster, nginx is easy to start with: 79 80 ```bash 81 ➜ export KUBECONFIG=$PWD/kubeconfig 82 ➜ kubectl run quick-start-nginx --image=nginx --port=80 83 deployment "quick-start-nginx" created 84 85 ➜ kubectl get pods 86 NAME READY STATUS RESTARTS AGE 87 quick-start-nginx-6687bdfc67-6qsr8 1/1 Running 0 10s 88 ``` 89 90 You can see above the pod is running and ready. To try it out we can forward a local port to the pod: 91 92 ```bash 93 ➜ kubectl port-forward $(kubectl get pods -l "run=quick-start-nginx" -o jsonpath="{.items[0].metadata.name}") 8080:80 94 Forwarding from 127.0.0.1:8080 -> 80 95 ``` 96 97 Then load the nginx home page in a browser: 98 99 ```bash 100 ➜ open http://localhost:8080/ 101 ``` 102 103 You should see a `Welcome to nginx!` page. 104 105 If you'd like to try exposing a public load balancer, first run: 106 107 ```bash 108 ➜ kubectl expose deployment quick-start-nginx --port=80 --type=LoadBalancer 109 ``` 110 111 Wait a few seconds for Kubernetes to create an AWS ELB to to expose the service and then run: 112 113 ```bash 114 ➜ open http://$(kubectl get svc quick-start-nginx -o jsonpath="{.status.loadBalancer.ingress[0].hostname}") 115 ``` 116 117 You should see the same `Welcome to nginx!` page as above. 118 119 The above commands demonstrate some basic `kubectl` imperative commands to create a Kubernetes Deployment and Service object. Declarative object configuration is also available, for more information see [Kubernetes Object Management](https://kubernetes.io/docs/tutorials/object-management-kubectl/object-management/). 120 121 # Step 5: Tear Down 122 123 Once you no longer need the quick start cluster created during this guide, tear it down: 124 125 ```bash 126 ➜ kubectl delete svc quick-start-nginx 127 service "quick-start-nginx" deleted 128 129 ➜ kube-aws destroy 130 ``` 131 132 The first command deletes the Service object created in step 4 so the AWS ELB is removed otherwise the network interface attachments may block the CloudFormation stack from being deleted.