kube-aws

README

Kubernetes on AWS (kube-aws)

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.

Features

• 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.

Getting Started

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

Examples

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

Development

Build

Clone this repository to the appropriate path under the GOPATH.

$ export GOPATH=$HOME/go
$ mkdir -p $GOPATH/src/github.com/kubernetes-incubator/
$ git clone git@github.com: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.

Run Unit Tests

make test

Reformat Code

make format

Modifying Templates

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

Other Resources

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

Kubernetes Incubator

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

Code of conduct

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

Contributing

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