From cacbf7ca350824ea05699552ac20496bbc1f82fb Mon Sep 17 00:00:00 2001 From: masstomato Date: Mon, 24 Oct 2016 23:22:37 +0900 Subject: [PATCH 1/3] Fix typo Fix 'ectdclt' to 'etcdctl'. --- docs/getting-started-guides/centos/centos_manual_config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started-guides/centos/centos_manual_config.md b/docs/getting-started-guides/centos/centos_manual_config.md index 75b7cccbf7..fc091e7357 100644 --- a/docs/getting-started-guides/centos/centos_manual_config.md +++ b/docs/getting-started-guides/centos/centos_manual_config.md @@ -123,7 +123,7 @@ KUBE_API_ARGS="" ```shell $ etcdctl mkdir /kube-centos/network -$ etcdclt mk /kube-centos/network/config "{ \"Network\": \"172.30.0.0/16\", \"SubnetLen\": 24, \"Backend\": { \"Type\": \"vxlan\" } }" +$ etcdctl mk /kube-centos/network/config "{ \"Network\": \"172.30.0.0/16\", \"SubnetLen\": 24, \"Backend\": { \"Type\": \"vxlan\" } }" ``` * Configure flannel to overlay Docker network in /etc/sysconfig/flanneld on the master (also in the nodes as we'll see): From 519ceca719e5d866543340c6b320511d5ac5a0ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20K=C3=A4ldstr=C3=B6m?= Date: Tue, 25 Oct 2016 22:55:48 +0300 Subject: [PATCH 2/3] Update and refactor the kubeadm documentation + add HypriotOS instructions as well --- docs/getting-started-guides/kubeadm.md | 120 ++++++++++++++++--------- 1 file changed, 76 insertions(+), 44 deletions(-) diff --git a/docs/getting-started-guides/kubeadm.md b/docs/getting-started-guides/kubeadm.md index cd73f3e73f..79fe54667c 100644 --- a/docs/getting-started-guides/kubeadm.md +++ b/docs/getting-started-guides/kubeadm.md @@ -1,4 +1,10 @@ --- +assignees: +- mikedanese +- luxas +- errordeveloper +- jbeda + --- + +## 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!