From 10884384deaeef2936edaea4eb3d4f7a150e8d61 Mon Sep 17 00:00:00 2001 From: Luke Marsden Date: Fri, 23 Sep 2016 14:29:06 +0100 Subject: [PATCH] kubeadm and add-ons docs --- _data/guides.yml | 4 +- docs/admin/addons.md | 9 +- docs/{ => getting-started-guides}/kubeadm.md | 96 +++++++++++--------- docs/index.md | 4 +- CNAME => old.CNAME | 0 5 files changed, 60 insertions(+), 53 deletions(-) rename docs/{ => getting-started-guides}/kubeadm.md (69%) rename CNAME => old.CNAME (100%) diff --git a/_data/guides.yml b/_data/guides.yml index b956870e58..7c41285d0e 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -8,8 +8,8 @@ toc: section: - title: What is Kubernetes? path: /docs/whatisk8s/ - - title: Installing Kubernetes Easily on Linux - path: /docs/kubeadm/ + - title: Installing Kubernetes on Linux with kubeadm + path: /docs/getting-started-guides/kubeadm/ - title: Hello World on Google Container Engine path: /docs/hellonode/ - title: Downloading or Building Kubernetes diff --git a/docs/admin/addons.md b/docs/admin/addons.md index 4a3d1710f6..6e28edfaa2 100644 --- a/docs/admin/addons.md +++ b/docs/admin/addons.md @@ -3,19 +3,20 @@ ## Overview -Add-ons extend the functionality of Kubernetes in a pluggable way. +Add-ons extend the functionality of Kubernetes. This page lists some of the available add-ons and links to their respective installation instructions. ## Networking and Network Policy -* [Weave Net](https://github.com/weaveworks/weave-kube) is an easy, fast and reliable pod network that carries on working in the face of network partitions, does not depend on a database, and supports Kubernetes policy. -* [Calico](https://github.com/projectcalico/calico-containers/tree/master/docs/cni/kubernetes/manifests/kubeadm) is a simple, scalable, secure L3 networking and network policy provider. -* [Canal](https://github.com/tigera/canal/tree/master/k8s-install/kubeadm) unites Flannel and Calico, providing cloud native networking and network policy. +* [Weave Net](https://github.com/weaveworks/weave-kube) provides networking and network policy, will carry on working on both sides of a network partition, and does not require an external database. +* [Calico](https://github.com/projectcalico/calico-containers/tree/master/docs/cni/kubernetes/manifests/kubeadm) is a secure L3 networking and network policy provider. +* [Canal](https://github.com/tigera/canal/tree/master/k8s-install/kubeadm) unites Flannel and Calico, providing networking and network policy. ## Visualization & Control * [Weave Scope](https://www.weave.works/documentation/scope-latest-installing/#k8s) is a tool for graphically visualizing your containers, pods, services etc. Use it in conjunction with a [Weave Cloud account](https://cloud.weave.works/) or host the UI yourself. +* [Dashboard](https://github.com/kubernetes/dashboard#kubernetes-dashboard) is a dashboard web interface for Kubernetes. ## Legacy Add-ons diff --git a/docs/kubeadm.md b/docs/getting-started-guides/kubeadm.md similarity index 69% rename from docs/kubeadm.md rename to docs/getting-started-guides/kubeadm.md index c3f3836d8e..c30b732475 100644 --- a/docs/kubeadm.md +++ b/docs/getting-started-guides/kubeadm.md @@ -7,18 +7,19 @@ li>.highlighter-rouge {position:relative; top:3px;} ## Overview -This quickstart will show you how to easily install a secure Kubernetes cluster on machines running Ubuntu 16.04 or CentOS 7, using a tool called `kubeadm` which is part of Kubernetes. +This quickstart shows you how to easily install a secure Kubernetes cluster on machines running Ubuntu 16.04 or CentOS 7. +The installation uses a tool called `kubeadm` which is part of Kubernetes 1.4. -This process should work with local VMs, physical servers and/or cloud servers. -It is intended to be simple enough that you can easily integrate its use into your own automation (Terraform, Chef, Puppet, etc). +This process works with local VMs, physical servers and/or cloud servers. +It is simple enough that you can easily integrate its use into your own automation (Terraform, Chef, Puppet, etc). -**The `kubeadm` tool is currently in alpha but please try it out and give us [feedback](/docs/kubeadm/#feedback)!** +**The `kubeadm` tool is currently in alpha but please try it out and give us [feedback](/docs/getting-started-guides/kubeadm/#feedback)!** ## Prerequisites 1. One or more machines running Ubuntu 16.04 or CentOS 7 -1. 2GB or more of RAM per machine -1. A network connection with open ports between the machines (public or private network is fine) +1. 1GB or more of RAM per machine (any less will leave little room for your apps) +1. Full network connectivity between all machines in the cluster (public or private network is fine) ## Objectives @@ -30,7 +31,7 @@ It is intended to be simple enough that you can easily integrate its use into yo ### (1/4) Installing kubelet and kubeadm on your hosts -You will now install the following packages on all the machines: +You will install the following packages on all the machines: * `docker`: the container runtime, which Kubernetes depends on. * `kubelet`: the most core component of Kubernetes. @@ -44,22 +45,20 @@ For each host in turn: * SSH into the machine and become `root` if you are not already (for example, run `sudo su -`). * If the machine is running Ubuntu 16.04, run: - # apt-get install -y docker.io socat + # apt-get install -y docker.io socat apt-transport-https # curl -s -L \ - "https://www.dropbox.com/s/tso6dc7b94ch2sk/debs-5ab576.txz?dl=1" | tar xJv - # dpkg -i debian/bin/unstable/xenial/*.deb + https://storage.googleapis.com/kubeadm/kubernetes-xenial-preview-bundle.txz | tar xJv + # dpkg -i kubernetes-xenial-preview-bundle/*.deb If the machine is running CentOS 7, run: @@ -74,24 +73,16 @@ For each host in turn: # systemctl enable docker && systemctl start docker # systemctl enable kubelet && systemctl start kubelet -The kubelet will now be restarting every few seconds, as it waits in a crashloop for `kubeadm` to tell it what to do. - -Optionally, see also [more details on installing Docker](https://docs.docker.com/engine/installation/#/on-linux). +The kubelet is now restarting every few seconds, as it waits in a crashloop for `kubeadm` to tell it what to do. ### (2/4) Initializing your master The master is the machine where the "control plane" components run, including `etcd` (the cluster database) and the API server (which the `kubectl` CLI communicates with). -All of these components will run in pods started by `kubelet`. +All of these components run in pods started by `kubelet`. To initialize the master, pick one of the machines you previously installed `kubelet` and `kubeadm` on, and run: -* If you want to be able to schedule pods on the master, for example if you want a single-machine Kubernetes cluster for development, run: - - # kubeadm init --schedule-pods-here - -* If you do not want to be able to schedule pods on the master (perhaps for security reasons), run: - - # kubeadm init + # kubeadm init This will download and install the cluster database and "control plane" components. This may take several minutes. @@ -119,13 +110,20 @@ The output should look like: Make a record of the `kubeadm join` command that `kubeadm init` outputs. You will need this in a moment. -The key included here is secret, keep it safe — anyone with this key will be able to add authenticated nodes to your cluster. +The key included here is secret, keep it safe — anyone with this key can add authenticated nodes to your cluster. The key is used for mutual authentication between the master and the joining nodes. +By default, your cluster will not schedule pods on the master for security reasons. +If you want to be able to schedule pods on the master, for example if you want a single-machine Kubernetes cluster for development, run: + + # kubectl taint nodes --all dedicated- + +This will remove the "dedicated" taint from all nodes, including the master node, meaning that the scheduler will then be able to schedule pods everywhere. + ### (3/4) Joining your nodes -The nodes are where your workloads (containers and pods, etc) will run. +The nodes are where your workloads (containers and pods, etc) run. If you want to add any new machines as nodes to your cluster, for each machine: SSH to that machine, become root (e.g. `sudo su -`) and run the command that was output by `kubeadm init`. For example: @@ -154,31 +152,29 @@ Before you can deploy applications to it, you need to install a pod network. ### (4/4) Installing a pod network You must install a pod network add-on so that your pods can communicate with each other when they are on different hosts. +**It is necessary to do this before you try to deploy any applications to your cluster.** Several projects provide Kubernetes pod networks. You can see a complete list of available network add-ons on the [add-ons page](/docs/admin/addons/). -By way of example, you can install Weave Net by running on the master: +By way of example, you can install [Weave Net](https://github.com/weaveworks/weave-kube) by logging in to the master and running: # kubectl apply -f https://git.io/weave-kube daemonset "weave-net" created -**You should install a pod network on the master before you try to deploy any applications to your cluster.** - -Once a pod network command has installed, a few seconds later you should see the `kube-dns` pod go into `Running` in the output of `kubectl get pods --all-namespaces`. +If you prefer [Calico](https://github.com/projectcalico/calico-containers/tree/master/docs/cni/kubernetes/manifests/kubeadm) or [Canal](https://github.com/tigera/canal/tree/master/k8s-install/kubeadm), please refer to their respective installation guides. +You should only install one pod network per cluster. +Once a pod network has been installed, you can confirm that it is working by checking that the `kube-dns` pod is `Running` in the output of `kubectl get pods --all-namespaces`. **This signifies that your cluster is ready.** -You can learn more about other available pod networks on the [add-ons page](/docs/admin/addons/). - ### (Optional) Installing a sample application -As an example, you will now install a sample microservices application, a socks shop, to put your cluster through its paces. +As an example, install a sample microservices application, a socks shop, to put your cluster through its paces. To learn more about the sample microservices app, see the [GitHub README](https://github.com/microservices-demo/microservices-demo). -Here you will install the NodePort version of the Socks Shop, which doesn't depend on Load Balancer integration, since our cluster doesn't have that: - - # kubectl apply -f https://raw.githubusercontent.com/lukemarsden/microservices-demo/master/deploy/kubernetes/definitions/wholeWeaveDemo-NodePort.yaml + # git clone https://github.com/microservices-demo/microservices-demo + # kubectl apply -f microservices-demo/deploy/kubernetes/manifests You can then find out the port that the [NodePort feature of services](/docs/user-guide/services/) allocated for the front-end service by running: @@ -194,11 +190,11 @@ You can then find out the port that the [NodePort feature of services](/docs/use Endpoints: Session Affinity: None -It will take several minutes to download and start all the containers, watch the output of `kubectl get pods` to see when they're all up and running. +It takes several minutes to download and start all the containers, watch the output of `kubectl get pods` to see when they're all up and running. Then go to the IP address of your cluster's master node in your browser, and specify the given port. So for example, `http://:`. -In the example above, this was `31869`, but it will be a different port for you. +In the example above, this was `31869`, but it is a different port for you. If there is a firewall, make sure it exposes this port to the internet before you try to access it. @@ -215,9 +211,19 @@ See the [list of add-ons](/docs/admin/addons/) to explore other add-ons, includi ## Cleanup -* To uninstall the socks shop, run `kubectl delete -f https://raw.githubusercontent.com/lukemarsden/microservices-demo/master/deploy/kubernetes/definitions/wholeWeaveDemo-NodePort.yaml`. -* To uninstall Kubernetes, simply delete the machines you created for this tutorial. - Or alternatively, uninstall the `kubelet`, `kubeadm` and `kubectl` packages and then manually delete all the Docker container that were created by this process. +* To uninstall the socks shop, run `kubectl delete -f microservices-demo/deploy/kubernetes/manifests` on the master. + +* To uninstall Kubernetes, simply delete the machines you created for this tutorial, or run the script below. +
+ ``` + systemctl stop kubelet + docker rm -f $(docker ps -q); mount | grep "/var/lib/kubelet/*" | awk '{print $3}' | xargs umount 1>/dev/null 2>/dev/null + rm -rf /var/lib/kubelet /etc/kubernetes /var/lib/etcd /etc/cni + ip link set cbr0 down; ip link del cbr0 + ip link set cni0 down; ip link del cni0 + systemctl start kubelet + ``` +
## Feedback @@ -233,8 +239,8 @@ Please note: `kubeadm` is a work in progress and these limitations will be addre To easily obtain a cluster which works with LBs and PVs Kubernetes, try [the "hello world" GKE tutorial](/docs/hellonode) or [one of the other cloud-specific installation tutorials](/docs/getting-started-guides/). Workaround: use the [NodePort feature of services](/docs/user-guide/services/#type-nodeport) to demonstrate exposing the sample application on the internet. -1. The cluster created here will have a single master, with a single `etcd` database running on it. - This means that if the master fails, your cluster will lose its configuration data and will need to be recreated from scratch. +1. The cluster created here has a single master, with a single `etcd` database running on it. + This means that if the master fails, your cluster loses its configuration data and will need to be recreated from scratch. Adding HA support (multiple `etcd` servers, multiple API servers, etc) to `kubeadm` is still a work-in-progress. Workaround: regularly [back up etcd](https://coreos.com/etcd/docs/latest/admin_guide.html). @@ -244,4 +250,4 @@ Please note: `kubeadm` is a work in progress and these limitations will be addre Workaround: use `docker logs` on the nodes where the containers are running as a workaround. 1. There is not yet an easy way to generate a `kubeconfig` file which can be used to authenticate to the cluster remotely with `kubectl` on, for example, your workstation. - Workaround: copy the kubelet's `kubeconfig` from the master: use `scp root@:/etc/kubernetes/kubelet.conf .` and then e.g. `kubectl --kubeconfig ./kubelet.conf get nodes` from your workstation. + Workaround: copy the kubelet's `kubeconfig` from the master: use `scp root@:/etc/kubernetes/admin.conf .` and then e.g. `kubectl --kubeconfig ./admin.conf get nodes` from your workstation. diff --git a/docs/index.md b/docs/index.md index 6c83b696a0..5e29c42dcb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -82,9 +82,9 @@ h2, h3, h4 { Get Started on GKE
-

Installing Kubernetes Easily on Linux

+

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!

- Install Kubernetes Easily + Install Kubernetes with kubeadm

Guided Tutorial

diff --git a/CNAME b/old.CNAME similarity index 100% rename from CNAME rename to old.CNAME