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.