github.com/kubernetes-incubator/kube-aws@v0.16.4/README.md (about) 1 # Kubernetes on AWS (kube-aws) 2 3 [![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-incubator/kube-aws)](https://goreportcard.com/report/github.com/kubernetes-incubator/kube-aws) 4 [![Build Status](https://travis-ci.org/kubernetes-incubator/kube-aws.svg?branch=master)](https://travis-ci.org/kubernetes-incubator/kube-aws) 5 [![License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg)](LICENSE) 6 7 **Note**: The `master` branch may be in an *unstable or even broken state* during development. Please use [releases](https://github.com/kubernetes-incubator/kube-aws/releases) instead of the `master` branch in order to get stable binaries. 8 9 `kube-aws` is a command-line tool to create/update/destroy Kubernetes clusters on AWS. 10 11 ## Features 12 13 * Create, update and destroy Kubernetes clusters on AWS 14 * Review changes before applying 15 * Highly available and scalable Kubernetes clusters backed by multi-AZ deployment and Node Pools 16 * Deployment to an existing VPC 17 * Powered by various AWS services including CloudFormation, KMS, Auto Scaling, Spot Fleet, EC2, ELB, S3, etc. 18 19 ## Getting Started / Manual 20 21 [View the latest manual for `kube-aws`](https://kubernetes-incubator.github.io/kube-aws/) 22 23 Check out our [getting started tutorial](https://kubernetes-incubator.github.io/kube-aws/getting-started/) 24 to launch your first Kubernetes cluster on AWS. 25 26 ## Global options 27 28 Each command supports following options: 29 30 - `-s` `--silent` do not show messages 31 - `-v` `--verbose` show debug messages 32 - `--color` use color for messages 33 34 ## Examples 35 36 Generate `cluster.yaml`: 37 38 ``` 39 $ mkdir my-cluster 40 $ cd my-cluster 41 $ kube-aws init \ 42 --cluster-name=my-cluster \ 43 --region=us-west-1 \ 44 --availability-zone=us-west-1c \ 45 --hosted-zone-id=<my-hosted-zone> \ 46 --external-dns-name=<my-cluster-endpoint> \ 47 --key-name=<key-pair-name> \ 48 --kms-key-arn="arn:aws:kms:us-west-1:xxxxxxxxxx:key/xxxxxxxxxxxxxxxxxxx" \ 49 --s3-uri=s3://examplebucket/mydir 50 ``` 51 52 Here `us-west-1c` is used for parameter `--availability-zone`, but supported availability zone varies among AWS accounts. 53 Please check if `us-west-1c` is supported by `aws ec2 --region us-west-1 describe-availability-zones`, if not switch to other supported availability zone. (e.g., `us-west-1a`, or `us-west-1b`) 54 55 Generate assets: 56 57 ``` 58 $ kube-aws render credentials --generate-ca 59 $ kube-aws render stack 60 ``` 61 62 View generated certificates: 63 64 ``` 65 $ kube-aws show certificates 66 ``` 67 68 Validate configuration: 69 70 ``` 71 $ kube-aws validate 72 ``` 73 74 Launch: 75 76 ``` 77 $ kube-aws apply 78 79 # Or export your cloudformation stack and dependent assets into the `exported/` directory 80 $ kube-aws apply --export 81 82 # Access the cluster 83 $ KUBECONFIG=kubeconfig kubectl get nodes --show-labels 84 ``` 85 86 Update: 87 88 ``` 89 # Modify your cluster.yaml 90 $ $EDITOR cluster.yaml 91 92 # Reviews changes to cfn stacks and EC2 userdata 93 $ kube-aws diff --context 3 --color 94 95 # Update all the cfn stacks including the one for control-plane and the ones for worker node pools 96 $ kube-aws apply 97 ``` 98 99 Destroy: 100 101 ``` 102 # Destroy all the cfn stacks including the one for control-plane and the ones for worker node pools. Use `--force` for skip confirmation. 103 $ kube-aws destroy 104 ``` 105 106 ## Other Resources 107 108 Extra or advanced topics in for kube-aws: 109 110 * [Known Limitations](/docs/troubleshooting/known-limitations.md) 111 * [Roadmap](/ROADMAP.md) 112 113 The following links can be useful for development: 114 115 - [AWS CloudFormation resource types](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) 116 117 Please feel free to reach out to the kube-aws community on: [#kube-aws in the kubernetes slack](https://kubernetes.slack.com/messages/C5GP8LPEC/) 118 119 ## Kubernetes Incubator 120 121 This is a [Kubernetes Incubator project](https://github.com/kubernetes/community/blob/master/incubator.md). The project was established 2017-03-15. The incubator team for the project is: 122 123 - Sponsor: Tim Hockin (@thockin) 124 - Champion: Mike Danese (@mikedanese) 125 - SIG: sig-aws 126 127 ### Code of conduct 128 129 Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md). 130 131 ## Contributing 132 133 Submit a PR to this repository, following the [contributors guide](CONTRIBUTING.md). 134 135 Details of how to develop kube-aws are in our [Developer Guide](https://kubernetes-incubator.github.io/kube-aws/guides/developer-guide.html).