Note: The master branch may be in an unstable or even broken state during development. Please use releases instead of the master branch in order to get stable binaries.

kube-aws is a command-line tool to create/update/destroy Kubernetes clusters on AWS.

View the latest manual for the kube-aws tool on GitHub.

• Create, update and destroy Kubernetes clusters on AWS
• Highly available and scalable Kubernetes clusters backed by multi-AZ deployment and Node Pools
• Deployment to an existing VPC
• Powered by various AWS services including CloudFormation, KMS, Auto Scaling, Spot Fleet, EC2, ELB, S3, etc.

Check out our getting started tutorial on launching your first Kubernetes cluster in AWS.

• Pre-requisites
• Step 1: Configure
  • Download the latest release of kube-aws
  • Define account and cluster settings
• Step 2: Render
  • Compile a re-usable CloudFormation template for the cluster
  • Optionally adjust template configuration
  • Validate the rendered CloudFormation stack
• Step 3: Launch
  • Create the CloudFormation stack and start our EC2 machines
  • Set up CLI access to the new cluster
• Step 4: Update
  • Update the CloudFormation stack
• Step 5: Add Node Pool
  • Create the additional pool of worker nodes
  • Adjust template configuration for each pool of worker nodes
  • Required to support cluster-autoscaler
• Step 6: Configure add-ons
  • Configure various Kubernetes add-ons
• Step 7: Destroy
  • Destroy the cluster
• Optional Features
  • Backup and restore for etcd
  • Backup Kubernetes resources
  • Restore Kubernetes resources
  • Journald logging to AWS CloudWatch
    • kube-aws up/update feedback
  • CloudFormation Streaming

Generate cluster.yaml:

$ mkdir my-cluster
$ cd my-cluster
$ kube-aws init --cluster-name=my-cluster \
--external-dns-name=<my-cluster-endpoint> \
--region=us-west-1 \
--availability-zone=us-west-1c \
--key-name=<key-pair-name> \
--kms-key-arn="arn:aws:kms:us-west-1:xxxxxxxxxx:key/xxxxxxxxxxxxxxxxxxx"

Here us-west-1c is used for parameter --availability-zone, but supported availability zone varies among AWS accounts. 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)

Generate assets:

$ kube-aws render credentials --generate-ca
$ kube-aws render stack

Validate configuration:

$ kube-aws validate --s3-uri s3://<your-bucket>/<optional-prefix>

Launch:

$ kube-aws up --s3-uri s3://<your-bucket>/<optional-prefix>

# Or export your cloudformation stack and dependent assets into the `exported/` directory
$ kube-aws up --s3-uri s3://<your-bucket>/<optional-prefix> --export

# Access the cluster
$ KUBECONFIG=kubeconfig kubectl get nodes --show-labels

Update:

$ $EDITOR cluster.yaml
# Update all the cfn stacks including the one for control-plane and the ones for worker node pools
$ kube-aws update --s3-uri s3://<your-bucket>/<optional-prefix>

Destroy:

# Destroy all the cfn stacks including the one for control-plane and the ones for worker node pools
$ kube-aws destroy

Clone this repository to the appropriate path under the GOPATH.

$ export GOPATH=$HOME/go
$ git clone [email protected]:kubernetes-incubator/kube-aws.git $GOPATH/src/github.com/kubernetes-incubator/kube-aws

Run make build to compile kube-aws locally.

This depends on having:

• golang >= 1.7

The compiled binary will be available at bin/kube-aws.

make test

make format

The various templates are located in the core/controlplane/config/templates/ and the core/nodepool/config/templates/ directory of the source repo. go generate is used to pack these templates into the source code. In order for changes to templates to be reflected in the source code:

make build

Extra or advanced topics in for kube-aws:

• Known Limitations
• Roadmap

The following links can be useful for development:

• AWS CloudFormation resource types

Please feel free to reach out to the kube-aws community on: #kube-aws in the kubernetes slack

This is a Kubernetes Incubator project. The project was established 2017-03-15. The incubator team for the project is:

• Sponsor: Tim Hockin (@thockin)
• Champion: Mike Danese (@mikedanese)
• SIG: sig-aws

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

Submit a PR to this repository, following the contributors guide. The documentation is published from this source.