Guide style update

- Don't indent top-level lists
- Use 2 space list item indentation, unless using multi-line items, then use 4 space indents
- Use underline for page title
- Auto-generate table of contents
- Start with lvl 2 headers (lvl 1 headers look too much like the page title)
pull/6/head
Karl Isenberg 2015-12-03 16:15:07 -08:00
parent b9f31ca2c4
commit c3c7c81b33
4 changed files with 159 additions and 104 deletions

View File

@ -31,12 +31,30 @@ Documentation for other releases can be found at
<!-- END MUNGE: UNVERSIONED_WARNING --> <!-- END MUNGE: UNVERSIONED_WARNING -->
# Creating a Kubernetes Cluster Creating a Kubernetes Cluster
----------------------------------------
Kubernetes can run on a range of platforms, from your laptop, to VMs on a cloud provider, to rack of Kubernetes can run on a range of platforms, from your laptop, to VMs on a cloud provider, to rack of
bare metal servers. The effort required to set up a cluster varies from running a single command to bare metal servers. The effort required to set up a cluster varies from running a single command to
crafting your own customized cluster. We'll guide you in picking a solution that fits for your needs. crafting your own customized cluster. We'll guide you in picking a solution that fits for your needs.
**Table of Contents**
<!-- BEGIN MUNGE: GENERATED_TOC -->
- [Picking the Right Solution](#picking-the-right-solution)
- [Local-machine Solutions](#local-machine-solutions)
- [Hosted Solutions](#hosted-solutions)
- [Turn-key Cloud Solutions](#turn-key-cloud-solutions)
- [Custom Solutions](#custom-solutions)
- [Cloud](#cloud)
- [On-Premises VMs](#on-premises-vms)
- [Bare Metal](#bare-metal)
- [Integrations](#integrations)
- [Table of Solutions](#table-of-solutions)
<!-- END MUNGE: GENERATED_TOC -->
## Picking the Right Solution ## Picking the Right Solution
If you just want to "kick the tires" on Kubernetes, we recommend the [local Docker-based](docker.md) solution. If you just want to "kick the tires" on Kubernetes, we recommend the [local Docker-based](docker.md) solution.
@ -61,9 +79,10 @@ physical machine. Setup is completely automated and doesn't require a cloud pro
But their size and availability is limited to that of a single machine. But their size and availability is limited to that of a single machine.
The local-machine solutions are: The local-machine solutions are:
- [Local Docker-based](docker.md) (recommended starting point)
- [Vagrant](vagrant.md) (works on any platform with Vagrant: Linux, MacOS, or Windows.) - [Local Docker-based](docker.md) (recommended starting point)
- [No-VM local cluster](locally.md) (Linux only) - [Vagrant](vagrant.md) (works on any platform with Vagrant: Linux, MacOS, or Windows.)
- [No-VM local cluster](locally.md) (Linux only)
### Hosted Solutions ### Hosted Solutions
@ -75,6 +94,7 @@ clusters.
These solutions allow you to create Kubernetes clusters on a range of Cloud IaaS providers with only a These solutions allow you to create Kubernetes clusters on a range of Cloud IaaS providers with only a
few commands, and have active community support. few commands, and have active community support.
- [GCE](gce.md) - [GCE](gce.md)
- [AWS](aws.md) - [AWS](aws.md)
- [Azure](coreos/azure/README.md) - [Azure](coreos/azure/README.md)
@ -95,6 +115,7 @@ writing a new solution](../../docs/devel/writing-a-getting-started-guide.md).
#### Cloud #### Cloud
These solutions are combinations of cloud provider and OS not covered by the above solutions. These solutions are combinations of cloud provider and OS not covered by the above solutions.
- [AWS + coreos](coreos.md) - [AWS + coreos](coreos.md)
- [GCE + CoreOS](coreos.md) - [GCE + CoreOS](coreos.md)
- [AWS + Ubuntu](juju.md) - [AWS + Ubuntu](juju.md)
@ -178,21 +199,23 @@ any | any | any | any | [docs](scratch.md)
*Note*: The above table is ordered by version test/used in notes followed by support level. *Note*: The above table is ordered by version test/used in notes followed by support level.
Definition of columns: Definition of columns:
- **IaaS Provider** is who/what provides the virtual or physical machines (nodes) that Kubernetes runs on.
- **OS** is the base operating system of the nodes. - **IaaS Provider** is who/what provides the virtual or physical machines (nodes) that Kubernetes runs on.
- **Config. Mgmt** is the configuration management system that helps install and maintain Kubernetes software on the - **OS** is the base operating system of the nodes.
nodes. - **Config. Mgmt** is the configuration management system that helps install and maintain Kubernetes software on the
- **Networking** is what implements the [networking model](../../docs/admin/networking.md). Those with networking type nodes.
_none_ may not support more than one node, or may support multiple VM nodes only in the same physical node. - **Networking** is what implements the [networking model](../../docs/admin/networking.md). Those with networking type
- **Conformance** indicates whether a cluster created with this configuration has passed the project's conformance _none_ may not support more than one node, or may support multiple VM nodes only in the same physical node.
tests for supporting the API and base features of Kubernetes v1.0.0. - **Conformance** indicates whether a cluster created with this configuration has passed the project's conformance
- Support Levels tests for supporting the API and base features of Kubernetes v1.0.0.
- **Project**: Kubernetes Committers regularly use this configuration, so it usually works with the latest release - Support Levels
of Kubernetes. - **Project**: Kubernetes Committers regularly use this configuration, so it usually works with the latest release
- **Commercial**: A commercial offering with its own support arrangements. of Kubernetes.
- **Community**: Actively supported by community contributions. May not work with more recent releases of Kubernetes. - **Commercial**: A commercial offering with its own support arrangements.
- **Inactive**: No active maintainer. Not recommended for first-time Kubernetes users, and may be deleted soon. - **Community**: Actively supported by community contributions. May not work with more recent releases of Kubernetes.
- **Notes** is relevant information such as the version of Kubernetes used. - **Inactive**: No active maintainer. Not recommended for first-time Kubernetes users, and may be deleted soon.
- **Notes** is relevant information such as the version of Kubernetes used.
<!-- reference style links below here --> <!-- reference style links below here -->
<!-- GCE conformance test result --> <!-- GCE conformance test result -->

View File

@ -30,18 +30,22 @@ Documentation for other releases can be found at
<!-- END STRIP_FOR_RELEASE --> <!-- END STRIP_FOR_RELEASE -->
<!-- END MUNGE: UNVERSIONED_WARNING --> <!-- END MUNGE: UNVERSIONED_WARNING -->
Getting started with Kubernetes on DCOS Getting started with Kubernetes on DCOS
---------------------------------------- ----------------------------------------
This guide will walk you through installing [Kubernetes-Mesos](https://github.com/mesosphere/kubernetes-mesos) on [Datacenter Operating System (DCOS)](https://mesosphere.com/product/) with the [DCOS CLI](https://github.com/mesosphere/dcos-cli) and operating Kubernetes with the [DCOS Kubectl plugin](https://github.com/mesosphere/dcos-kubectl). This guide will walk you through installing [Kubernetes-Mesos](https://github.com/mesosphere/kubernetes-mesos) on [Datacenter Operating System (DCOS)](https://mesosphere.com/product/) with the [DCOS CLI](https://github.com/mesosphere/dcos-cli) and operating Kubernetes with the [DCOS Kubectl plugin](https://github.com/mesosphere/dcos-kubectl).
**Table of Contents** **Table of Contents**
<!-- BEGIN MUNGE: GENERATED_TOC -->
- [About Kubernetes on DCOS](#about-kubernetes-on-dcos) - [About Kubernetes on DCOS](#about-kubernetes-on-dcos)
- [Resources](#resources) - [Resources](#resources)
- [Prerequisites](#prerequisites) - [Prerequisites](#prerequisites)
- [Install](#install) - [Install](#install)
- [Uninstall](#uninstall) - [Uninstall](#uninstall)
<!-- END MUNGE: GENERATED_TOC -->
## About Kubernetes on DCOS ## About Kubernetes on DCOS
@ -83,70 +87,70 @@ Explore the following resources for more information about Kubernetes, Kubernete
1. Configure and validate the [Mesosphere Multiverse](https://github.com/mesosphere/multiverse) as a package source repository 1. Configure and validate the [Mesosphere Multiverse](https://github.com/mesosphere/multiverse) as a package source repository
``` ```
$ dcos config prepend package.sources https://github.com/mesosphere/multiverse/archive/version-1.x.zip $ dcos config prepend package.sources https://github.com/mesosphere/multiverse/archive/version-1.x.zip
$ dcos package update --validate $ dcos package update --validate
``` ```
2. Install etcd 2. Install etcd
By default, the Kubernetes DCOS package starts a single-node etcd. In order to avoid state loss in the event of Kubernetes component container failure, install an HA [etcd-mesos](https://github.com/mesosphere/etcd-mesos) cluster on DCOS. By default, the Kubernetes DCOS package starts a single-node etcd. In order to avoid state loss in the event of Kubernetes component container failure, install an HA [etcd-mesos](https://github.com/mesosphere/etcd-mesos) cluster on DCOS.
``` ```
$ dcos package install etcd $ dcos package install etcd
``` ```
3. Verify that etcd is installed and healthy 3. Verify that etcd is installed and healthy
The etcd cluster takes a short while to deploy. Verify that `/etcd` is healthy before going on to the next step. The etcd cluster takes a short while to deploy. Verify that `/etcd` is healthy before going on to the next step.
``` ```
$ dcos marathon app list $ dcos marathon app list
ID MEM CPUS TASKS HEALTH DEPLOYMENT CONTAINER CMD ID MEM CPUS TASKS HEALTH DEPLOYMENT CONTAINER CMD
/etcd 128 0.2 1/1 1/1 --- DOCKER None /etcd 128 0.2 1/1 1/1 --- DOCKER None
``` ```
4. Create Kubernetes installation configuration 4. Create Kubernetes installation configuration
Configure Kubernetes to use the HA etcd installed on DCOS. Configure Kubernetes to use the HA etcd installed on DCOS.
``` ```
$ cat >/tmp/options.json <<EOF $ cat >/tmp/options.json <<EOF
{ {
"kubernetes": { "kubernetes": {
"etcd-mesos-framework-name": "etcd" "etcd-mesos-framework-name": "etcd"
}
} }
} EOF
EOF ```
```
5. Install Kubernetes 5. Install Kubernetes
``` ```
$ dcos package install --options=/tmp/options.json kubernetes $ dcos package install --options=/tmp/options.json kubernetes
``` ```
6. Verify that Kubernetes is installed and healthy 6. Verify that Kubernetes is installed and healthy
The Kubernetes cluster takes a short while to deploy. Verify that `/kubernetes` is healthy before going on to the next step. The Kubernetes cluster takes a short while to deploy. Verify that `/kubernetes` is healthy before going on to the next step.
``` ```
$ dcos marathon app list $ dcos marathon app list
ID MEM CPUS TASKS HEALTH DEPLOYMENT CONTAINER CMD ID MEM CPUS TASKS HEALTH DEPLOYMENT CONTAINER CMD
/etcd 128 0.2 1/1 1/1 --- DOCKER None /etcd 128 0.2 1/1 1/1 --- DOCKER None
/kubernetes 768 1 1/1 1/1 --- DOCKER None /kubernetes 768 1 1/1 1/1 --- DOCKER None
``` ```
7. Verify that Kube-DNS & Kube-UI are deployed, running, and ready 7. Verify that Kube-DNS & Kube-UI are deployed, running, and ready
``` ```
$ dcos kubectl get pods --namespace=kube-system $ dcos kubectl get pods --namespace=kube-system
NAME READY STATUS RESTARTS AGE NAME READY STATUS RESTARTS AGE
kube-dns-v8-tjxk9 4/4 Running 0 1m kube-dns-v8-tjxk9 4/4 Running 0 1m
kube-ui-v2-tjq7b 1/1 Running 0 1m kube-ui-v2-tjq7b 1/1 Running 0 1m
``` ```
Names and ages may vary. Names and ages may vary.
Now that Kubernetes is installed on DCOS, you may wish to explore the [Kubernetes Examples](../../examples/README.md) or the [Kubernetes User Guide](../user-guide/README.md). Now that Kubernetes is installed on DCOS, you may wish to explore the [Kubernetes Examples](../../examples/README.md) or the [Kubernetes User Guide](../user-guide/README.md).
@ -156,24 +160,24 @@ Now that Kubernetes is installed on DCOS, you may wish to explore the [Kubernete
1. Stop and delete all replication controllers and pods in each namespace: 1. Stop and delete all replication controllers and pods in each namespace:
Before uninstalling Kubernetes, destroy all the pods and replication controllers. The uninstall process will try to do this itself, but by default it times out quickly and may leave your cluster in a dirty state. Before uninstalling Kubernetes, destroy all the pods and replication controllers. The uninstall process will try to do this itself, but by default it times out quickly and may leave your cluster in a dirty state.
``` ```
$ dcos kubectl delete rc,pods --all --namespace=default $ dcos kubectl delete rc,pods --all --namespace=default
$ dcos kubectl delete rc,pods --all --namespace=kube-system $ dcos kubectl delete rc,pods --all --namespace=kube-system
``` ```
2. Validate that all pods have been deleted 2. Validate that all pods have been deleted
``` ```
$ dcos kubectl get pods --all-namespaces $ dcos kubectl get pods --all-namespaces
``` ```
3. Uninstall Kubernetes 3. Uninstall Kubernetes
``` ```
$ dcos package uninstall kubernetes $ dcos package uninstall kubernetes
``` ```
<!-- BEGIN MUNGE: GENERATED_ANALYTICS --> <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->

View File

@ -31,12 +31,33 @@ Documentation for other releases can be found at
<!-- END MUNGE: UNVERSIONED_WARNING --> <!-- END MUNGE: UNVERSIONED_WARNING -->
## Getting Started With Kubernetes on Mesos on Docker Getting Started With Kubernetes on Mesos on Docker
----------------------------------------
The mesos/docker provider uses docker-compose to launch Kubernetes as a Mesos framework, running in docker with its The mesos/docker provider uses docker-compose to launch Kubernetes as a Mesos framework, running in docker with its
dependencies (etcd & mesos). dependencies (etcd & mesos).
### Cluster Goals **Table of Contents**
<!-- BEGIN MUNGE: GENERATED_TOC -->
- [Cluster Goals](#cluster-goals)
- [Cluster Topology](#cluster-topology)
- [Prerequisites](#prerequisites)
- [Install on Mac (Homebrew)](#install-on-mac-homebrew)
- [Install on Linux](#install-on-linux)
- [Boot2Docker Config (Mac)](#boot2docker-config-mac)
- [Walkthrough](#walkthrough)
- [Addons](#addons)
- [KubeUI](#kubeui)
- [End To End Testing](#end-to-end-testing)
- [Kubernetes CLI](#kubernetes-cli)
- [Helpful scripts](#helpful-scripts)
- [Build Locally](#build-locally)
<!-- END MUNGE: GENERATED_TOC -->
## Cluster Goals
- kubernetes development - kubernetes development
- pod/service development - pod/service development
@ -58,7 +79,7 @@ Non-Goals:
- long running - long running
- state persistence across restarts - state persistence across restarts
### Cluster Topology ## Cluster Topology
The cluster consists of several docker containers linked together by docker-managed hostnames: The cluster consists of several docker containers linked together by docker-managed hostnames:
@ -72,7 +93,7 @@ The cluster consists of several docker containers linked together by docker-mana
| Kubernetes Controller Manager | controller | | | Kubernetes Controller Manager | controller | |
| Kubernetes Scheduler | scheduler | Schedules container deployment by accepting Mesos offers | | Kubernetes Scheduler | scheduler | Schedules container deployment by accepting Mesos offers |
### Prerequisites ## Prerequisites
Required: Required:
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - version control system - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - version control system
@ -89,7 +110,7 @@ Optional:
- [Make](https://en.wikipedia.org/wiki/Make_(software)) - Utility for building executables from source - [Make](https://en.wikipedia.org/wiki/Make_(software)) - Utility for building executables from source
- Required to build Kubernetes locally with make - Required to build Kubernetes locally with make
#### Install on Mac (Homebrew) ### Install on Mac (Homebrew)
It's possible to install all of the above via [Homebrew](http://brew.sh/) on a Mac. It's possible to install all of the above via [Homebrew](http://brew.sh/) on a Mac.
@ -106,7 +127,7 @@ boot2docker up
brew install docker-compose brew install docker-compose
``` ```
#### Install on Linux ### Install on Linux
Most of the above are available via apt and yum, but depending on your distribution, you may have to install via other Most of the above are available via apt and yum, but depending on your distribution, you may have to install via other
means to get the latest versions. means to get the latest versions.
@ -118,7 +139,7 @@ In order to build Kubernetes, the current user must be in a docker group with su
See the docker docs for [instructions](https://docs.docker.com/installation/ubuntulinux/#create-a-docker-group). See the docker docs for [instructions](https://docs.docker.com/installation/ubuntulinux/#create-a-docker-group).
#### Boot2Docker Config (Mac) ### Boot2Docker Config (Mac)
If on a mac using boot2docker, the following steps will make the docker IPs (in the virtualbox VM) reachable from the If on a mac using boot2docker, the following steps will make the docker IPs (in the virtualbox VM) reachable from the
host machine (mac). host machine (mac).
@ -146,7 +167,7 @@ host machine (mac).
To delete the route later: `sudo route delete 172.17.0.0` To delete the route later: `sudo route delete 172.17.0.0`
### Walkthrough ## Walkthrough
1. Checkout source 1. Checkout source
@ -226,10 +247,10 @@ host machine (mac).
1. Explore examples 1. Explore examples
To learn more about Pods, Volumes, Labels, Services, and Replication Controllers, start with the To learn more about Pods, Volumes, Labels, Services, and Replication Controllers, start with the
[Kubernetes Walkthrough](../user-guide/walkthrough/). [Kubernetes Walkthrough](../user-guide/walkthrough/).
To skip to a more advanced example, see the [Guestbook Example](../../examples/guestbook/) To skip to a more advanced example, see the [Guestbook Example](../../examples/guestbook/)
1. Destroy cluster 1. Destroy cluster
@ -237,7 +258,7 @@ host machine (mac).
./cluster/kube-down.sh ./cluster/kube-down.sh
``` ```
### Addons ## Addons
The `kube-up` for the mesos/docker provider will automatically deploy KubeDNS and KubeUI addons as pods/services. The `kube-up` for the mesos/docker provider will automatically deploy KubeDNS and KubeUI addons as pods/services.
@ -247,7 +268,7 @@ Check their status with:
./cluster/kubectl.sh get pods --namespace=kube-system ./cluster/kubectl.sh get pods --namespace=kube-system
``` ```
#### KubeUI ### KubeUI
The web-based Kubernetes UI is accessible in a browser through the API Server proxy: `https://<apiserver>:6443/ui/`. The web-based Kubernetes UI is accessible in a browser through the API Server proxy: `https://<apiserver>:6443/ui/`.
@ -256,7 +277,7 @@ By default, basic-auth is configured with user `admin` and password `admin`.
The IP of the API Server can be found using `./cluster/kubectl.sh cluster-info`. The IP of the API Server can be found using `./cluster/kubectl.sh cluster-info`.
### End To End Testing ## End To End Testing
Warning: e2e tests can take a long time to run. You may not want to run them immediately if you're just getting started. Warning: e2e tests can take a long time to run. You may not want to run them immediately if you're just getting started.
@ -277,7 +298,7 @@ make test_e2e
``` ```
### Kubernetes CLI ## Kubernetes CLI
When compiling from source, it's simplest to use the `./cluster/kubectl.sh` script, which detects your platform & When compiling from source, it's simplest to use the `./cluster/kubectl.sh` script, which detects your platform &
architecture and proxies commands to the appropriate `kubectl` binary. architecture and proxies commands to the appropriate `kubectl` binary.
@ -285,7 +306,7 @@ architecture and proxies commands to the appropriate `kubectl` binary.
ex: `./cluster/kubectl.sh get pods` ex: `./cluster/kubectl.sh get pods`
### Helpful scripts ## Helpful scripts
- Kill all docker containers - Kill all docker containers
@ -299,7 +320,7 @@ ex: `./cluster/kubectl.sh get pods`
docker run -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/docker:/var/lib/docker --rm martin/docker-cleanup-volumes docker run -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/docker:/var/lib/docker --rm martin/docker-cleanup-volumes
``` ```
### Build Locally ## Build Locally
The steps above tell you how to build in a container, for minimal local dependencies. But if you have Go and Make installed you can build locally much faster: The steps above tell you how to build in a container, for minimal local dependencies. But if you have Go and Make installed you can build locally much faster:

View File

@ -30,20 +30,25 @@ Documentation for other releases can be found at
<!-- END STRIP_FOR_RELEASE --> <!-- END STRIP_FOR_RELEASE -->
<!-- END MUNGE: UNVERSIONED_WARNING --> <!-- END MUNGE: UNVERSIONED_WARNING -->
Getting started with Kubernetes on Mesos Getting started with Kubernetes on Mesos
---------------------------------------- ----------------------------------------
**Table of Contents** **Table of Contents**
<!-- BEGIN MUNGE: GENERATED_TOC -->
- [About Kubernetes on Mesos](#about-kubernetes-on-mesos) - [About Kubernetes on Mesos](#about-kubernetes-on-mesos)
- [Prerequisites](#prerequisites) - [Prerequisites](#prerequisites)
- [Deploy Kubernetes-Mesos](#deploy-kubernetes-mesos) - [Deploy Kubernetes-Mesos](#deploy-kubernetes-mesos)
- [Deploy etcd](#deploy-etcd) - [Deploy etcd](#deploy-etcd)
- [Start Kubernetes-Mesos Services](#start-kubernetes-mesos-services) - [Start Kubernetes-Mesos Services](#start-kubernetes-mesos-services)
- [Validate KM Services](#validate-km-services) - [Validate KM Services](#validate-km-services)
- [Spin up a pod](#spin-up-a-pod) - [Spin up a pod](#spin-up-a-pod)
- [Run the Example Guestbook App](#run-the-example-guestbook-app) - [Launching kube-dns](#launching-kube-dns)
- [Test Guestbook App](#test-guestbook-app) - [What next?](#what-next)
<!-- END MUNGE: GENERATED_TOC -->
## About Kubernetes on Mesos ## About Kubernetes on Mesos
@ -64,13 +69,13 @@ Further information is available in the Kubernetes on Mesos [contrib directory][
### Prerequisites ### Prerequisites
* Understanding of [Apache Mesos][6] - Understanding of [Apache Mesos][6]
* A running [Mesos cluster on Google Compute Engine][5] - A running [Mesos cluster on Google Compute Engine][5]
* A [VPN connection][10] to the cluster - A [VPN connection][10] to the cluster
* A machine in the cluster which should become the Kubernetes *master node* with: - A machine in the cluster which should become the Kubernetes *master node* with:
* GoLang > 1.2 - GoLang > 1.2
* make (i.e. build-essential) - make (i.e. build-essential)
* Docker - Docker
**Note**: You *can*, but you *don't have to* deploy Kubernetes-Mesos on the same machine the Mesos master is running on. **Note**: You *can*, but you *don't have to* deploy Kubernetes-Mesos on the same machine the Mesos master is running on.
@ -260,6 +265,7 @@ started the Kubernetes pod.
Kube-dns is an addon for Kubernetes which adds DNS-based service discovery to the cluster. For a detailed explanation see [DNS in Kubernetes][4]. Kube-dns is an addon for Kubernetes which adds DNS-based service discovery to the cluster. For a detailed explanation see [DNS in Kubernetes][4].
The kube-dns addon runs as a pod inside the cluster. The pod consists of three co-located containers: The kube-dns addon runs as a pod inside the cluster. The pod consists of three co-located containers:
- a local etcd instance - a local etcd instance
- the [skydns][11] DNS server - the [skydns][11] DNS server
- the kube2sky process to glue skydns to the state of the Kubernetes cluster. - the kube2sky process to glue skydns to the state of the Kubernetes cluster.
@ -267,6 +273,7 @@ The kube-dns addon runs as a pod inside the cluster. The pod consists of three c
The skydns container offers DNS service via port 53 to the cluster. The etcd communication works via local 127.0.0.1 communication The skydns container offers DNS service via port 53 to the cluster. The etcd communication works via local 127.0.0.1 communication
We assume that kube-dns will use We assume that kube-dns will use
- the service IP `10.10.10.10` - the service IP `10.10.10.10`
- and the `cluster.local` domain. - and the `cluster.local` domain.