From 5d689c8eee7322084063eb654e39d92c69ebeb65 Mon Sep 17 00:00:00 2001 From: Justin Santa Barbara Date: Wed, 19 Oct 2016 12:31:42 -0400 Subject: [PATCH] Add docs for kops, explain when kops and when kubeadm Quick getting started guide for kops. Also try to provide some guidance as to when to use kops and when kubeadm; based on discussions with sig-cluster-lifecycle that kubeadm is a building block and not a provisioning tool. I used "kubeadm" as a simplifying concept for "kubeadm and the other work done by sig-cluster-lifecycle that kubeadm is a part of", in that tools that don't (yet) use kubeadm are still leveraging the kubeadm stream of work. --- _data/guides.yml | 2 + docs/getting-started-guides/kops.md | 160 +++++++++++++++++++++++++ docs/getting-started-guides/kubeadm.md | 15 ++- docs/index.md | 8 +- 4 files changed, 183 insertions(+), 2 deletions(-) create mode 100644 docs/getting-started-guides/kops.md diff --git a/_data/guides.yml b/_data/guides.yml index 40d47b08d6..d6e63558b4 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -10,6 +10,8 @@ toc: path: /docs/whatisk8s/ - title: Installing Kubernetes on Linux with kubeadm path: /docs/getting-started-guides/kubeadm/ + - title: Installing Kubernetes on AWS with kops + path: /docs/getting-started-guides/kops/ - title: Hello World on Google Container Engine path: /docs/hellonode/ - title: Downloading or Building Kubernetes diff --git a/docs/getting-started-guides/kops.md b/docs/getting-started-guides/kops.md new file mode 100644 index 0000000000..0cc28fb547 --- /dev/null +++ b/docs/getting-started-guides/kops.md @@ -0,0 +1,160 @@ +--- +--- + + + +## Overview + +This quickstart shows you how to easily install a Kubernetes cluster on AWS. +It uses a tool called [`kops`](https://github.com/kubernetes/kops). + +kops is an opinionated provisioning system: + +* Fully automated installation +* Uses DNS to identify clusters +* Self-healing: everything runs in Auto-Scaling Groups +* Limited OS support (Debian preferred, Ubuntu 16.04 supported, early support for CentOS & RHEL) +* High-Availability support +* Can directly provision, or generate terraform manifests + +If your opinions differ from these you may prefer to build your own cluster using [kubeadm](kubeadm) as +a building block. kops builds on the kubeadm work. + +## Creating a cluster + +### (1/5) Install kops + +Download kops from the [releases page](https://github.com/kubernetes/kops/releases) (it is also easy to build from source): + +On MacOS: + +``` +wget https://github.com/kubernetes/kops/releases/download/v1.4.1/kops-darwin-amd64 +chmod +x kops-darwin-amd64 +mv kops-darwin-amd64 /usr/local/bin/kops +``` + +On Linux: + +``` +wget https://github.com/kubernetes/kops/releases/download/v1.4.1/kops-linux-amd64 +chmod +x kops-linux-amd64 +mv kops-linux-amd64 /usr/local/bin/kops +``` + +### (2/5) Create a route53 domain for your cluster + +kops uses DNS for discovery, both inside the cluster and so that you can reach the kubernetes API server +from clients. + +kops has a strong opinion on the cluster name: it should be a valid DNS name. By doing so you will +no longer get your clusters confused, you can share clusters with your colleagues unambigiously, +and you can reach them without relying on remembering an IP address. + +You can, and probably should, use subdomains to divide your clusters. As our example we will use +`useast1.dev.example.com`. The API server endpoint will then be `api.useast1.dev.example.com`. + +A Route53 hosted zone can serve subdomains. Your hosted zone could be `useast1.dev.example.com`, +but also `dev.example.com` or even `example.com`. kops works with any of these, so typically +you choose for organization reasons (e.g. you are allowed to create records under `dev.example.com`, +but not under `example.com`). + +Let's assume you're using `dev.example.com` as your hosted zone. You create that hosted zone using +the [normal process](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingNewSubdomain.html), or +with a command such as `aws route53 create-hosted-zone --name dev.example.com --caller-reference 1`. + +You must then set up your NS records in the parent domain, so that records in the domain will resolve. Here, +you would create NS records in `example.com` for `dev`. If it is a root domain name you would configure the NS +records at your domain registrar (e.g. `example.com` would need to be configured where you bought `example.com`). + +This step is easy to mess up (it is the #1 cause of problems!) You can double-check that +your cluster is configured correctly if you have the dig tool by running: + +`dig NS dev.example.com` + +You should see the 4 NS records that Route53 assigned your hosted zone. + +### (3/5) Create an S3 bucket to store your clusters state + +kops lets you manage your clusters even after installation. To do this, it must keep track of the clusters +that you have created, along with their configuration, the keys they are using etc. This information is stored +in an S3 bucket. S3 permissions are used to control access to the bucket. + +Multiple clusters can use the same S3 bucket, and you can share an S3 bucket between your colleagues that +administer the same clusters - this is much easier than passing around kubecfg files. But anyone with access +to the S3 bucket will have administrative access to all your clusters, so you don't want to share it beyond +the operations team. + +So typically you have one S3 bucket for each ops team (and often the name will correspond +to the name of the hosted zone above!) + +In our example, we chose `dev.example.com` as our hosted zone, so let's pick `clusters.dev.example.com` as +the S3 bucket name. + +* Export `AWS_PROFILE` (if you need to select a profile for the AWS CLI to work) + +* Create the S3 bucket using `aws s3 mb s3://clusters.dev.example.com` + +* You can `export KOPS_STATE_STORE=s3://clusters.dev.example.com` and then kops will use this location by default. + We suggest putting this in your bash profile or similar. + + +### (4/5) Build your cluster configuration + +Run "kops create cluster" to create your cluster configuration: + +`kops create cluster --zones=us-east-1c useast1.dev.example.com` + +kops will create the configuration for your cluster. Note that it _only_ creates the configuration, it does +not actually create the cloud resources - you'll do that in the next step with a `kops update cluster`. This +give you an opportunity to review the configuration or change it. + +It prints commands you can use to explore further: + +* List your clusters with: `kops get cluster` +* Edit this cluster with: `kops edit cluster useast1.dev.example.com` +* Edit your node instance group: `kops edit ig --name=useast1.dev.example.com nodes` +* Edit your master instance group: `kops edit ig --name=useast1.dev.example.com master-us-east-1c` + +If this is your first time using kops, do spend a few minutes to try those out! An instance group is a +set of instances, which will be registered as kubernetes nodes. On AWS this is implemented via auto-scaling-groups. +You can have several instance groups, for example if you wanted nodes that are a mix of spot and on-demand instances, or +GPU and non-GPU instances. + + +### (5/5) Create the cluster in AWS + +Run "kops update cluster" to create your cluster in AWS: + +`kops update cluster useast1.dev.awsdata.com --yes` + +That takes a few seconds to run, but then your cluster will likely take a few minutes to actually be ready. +`kops update cluster` will be the tool you'll use whenever you change the configuration of your cluster; it +applies the changes you have made to the configuration to your cluster - reconfiguring AWS or kubernetes as needed. + +For example, after you `kops edit ig nodes`, then `kops update cluster --yes` to apply your configuration, and +sometimes you will also have to `kops rolling-update cluster` to roll out the configuration immediately. + +Without `--yes`, `kops update cluster` will show you a preview of what it is going to do. This is handy +for production clusters! + +### Explore other add-ons + +See the [list of add-ons](/docs/admin/addons/) to explore other add-ons, including tools for logging, monitoring, network policy, visualization & control of your Kubernetes cluster. + +## What's next + +* Learn more about [Kubernetes concepts and kubectl in Kubernetes 101](/docs/user-guide/walkthrough/). +* Learn about `kops` [advanced usage](https://github.com/kubernetes/kops) + +## Cleanup + +* To delete you cluster: `kops delete cluster useast1.dev.example.com --yes` + +## Feedback + +* Slack Channel: [#sig-aws](https://kubernetes.slack.com/messages/sig-aws/) has a lot of kops users +* [GitHub Issues](https://github.com/kubernetes/kops/issues) + diff --git a/docs/getting-started-guides/kubeadm.md b/docs/getting-started-guides/kubeadm.md index 79fe54667c..08148bd7c3 100644 --- a/docs/getting-started-guides/kubeadm.md +++ b/docs/getting-started-guides/kubeadm.md @@ -21,7 +21,20 @@ It is simple enough that you can easily integrate its use into your own automati See the full [`kubeadm` reference](/docs/admin/kubeadm) for information on all `kubeadm` command-line flags and for advice on automating `kubeadm` itself. -**The `kubeadm` tool is currently in alpha but please try it out and give us [feedback](/docs/getting-started-guides/kubeadm/#feedback)!** +**The `kubeadm` tool is currently in alpha but please try it out and give us [feedback](/docs/getting-started-guides/kubeadm/#feedback)! +Be sure to read the [limitations](#limitations); in particular note that kubeadm doesn't have great support for +automatically configuring cloud providers. Please refer to the specific cloud provider documentation or +use another provisioning system.** + +kubeadm assumes you have a set of machines (virtual or real) that are up and running. It is designed +to be part of a larger provisioning system - or just for easy manual provisioning. kubeadm is a great +choice where you have your own infrastructure (e.g. bare metal), or where you have an existing +orchestration system (e.g. Puppet) that you have to integrate with. + +If you are not constrained, other tools build on kubeadm to give you complete clusters: + +* On GCE, [Google Container Engine](https://cloud.google.com/container-engine/) gives you turn-key Kubernetes +* On AWS, [kops](kops) makes installation and cluster management easy (and supports high availability) ## Prerequisites diff --git a/docs/index.md b/docs/index.md index 3c813670db..5501491e7a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -83,9 +83,15 @@ h2, h3, h4 {

Installing Kubernetes on Linux with kubeadm

-

This quickstart will show you how to install a secure Kubernetes cluster on any computers running Linux, using a tool called kubeadm which is part of Kubernetes. It'll work with local VMs, physical servers and/or cloud servers, either manually or as part of your own automation. It is currently in alpha but please try it out and give us feedback!

+

This quickstart will show you how to install a secure Kubernetes cluster on any computers running Linux, using a tool called kubeadm. It'll work with local VMs, physical servers and/or cloud servers, either manually or as a part of your own automation. It is currently in alpha but please try it out and give us feedback!

+

If you are looking for a fully automated solution, note that kubeadm is intended as a building block. Tools such as GKE and kops build on kubeadm to provision a complete cluster.

Install Kubernetes with kubeadm
+
+

Installing Kubernetes on AWS with kops

+

This quickstart will show you how to bring up a complete Kubernetes cluster on AWS, using a tool called kops.

+ Install Kubernetes with kops +

Guided Tutorial

If you’ve completed one of the quickstarts, a great next step is Kubernetes 101. You will follow a path through the various features of Kubernetes, with code examples along the way, learning all of the core concepts. There's also a Kubernetes 201!