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 -->
# 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
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.
**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
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.
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.)
- [No-VM local cluster](locally.md) (Linux only)
- [Local Docker-based](docker.md) (recommended starting point)
- [Vagrant](vagrant.md) (works on any platform with Vagrant: Linux, MacOS, or Windows.)
- [No-VM local cluster](locally.md) (Linux only)
### 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
few commands, and have active community support.
- [GCE](gce.md)
- [AWS](aws.md)
- [Azure](coreos/azure/README.md)
@ -95,6 +115,7 @@ writing a new solution](../../docs/devel/writing-a-getting-started-guide.md).
#### Cloud
These solutions are combinations of cloud provider and OS not covered by the above solutions.
- [AWS + coreos](coreos.md)
- [GCE + CoreOS](coreos.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.
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.
- **Config. Mgmt** is the configuration management system that helps install and maintain Kubernetes software on the
nodes.
- **Networking** is what implements the [networking model](../../docs/admin/networking.md). Those with networking type
_none_ may not support more than one node, or may support multiple VM nodes only in the same physical node.
- **Conformance** indicates whether a cluster created with this configuration has passed the project's conformance
tests for supporting the API and base features of Kubernetes v1.0.0.
- Support Levels
- **Project**: Kubernetes Committers regularly use this configuration, so it usually works with the latest release
of Kubernetes.
- **Commercial**: A commercial offering with its own support arrangements.
- **Community**: Actively supported by community contributions. May not work with more recent releases of Kubernetes.
- **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.
- **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.
- **Config. Mgmt** is the configuration management system that helps install and maintain Kubernetes software on the
nodes.
- **Networking** is what implements the [networking model](../../docs/admin/networking.md). Those with networking type
_none_ may not support more than one node, or may support multiple VM nodes only in the same physical node.
- **Conformance** indicates whether a cluster created with this configuration has passed the project's conformance
tests for supporting the API and base features of Kubernetes v1.0.0.
- Support Levels
- **Project**: Kubernetes Committers regularly use this configuration, so it usually works with the latest release
of Kubernetes.
- **Commercial**: A commercial offering with its own support arrangements.
- **Community**: Actively supported by community contributions. May not work with more recent releases of Kubernetes.
- **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 -->
<!-- GCE conformance test result -->

View File

@ -30,18 +30,22 @@ Documentation for other releases can be found at
<!-- END STRIP_FOR_RELEASE -->
<!-- END MUNGE: UNVERSIONED_WARNING -->
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).
**Table of Contents**
<!-- BEGIN MUNGE: GENERATED_TOC -->
- [About Kubernetes on DCOS](#about-kubernetes-on-dcos)
- [Resources](#resources)
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Uninstall](#uninstall)
- [About Kubernetes on DCOS](#about-kubernetes-on-dcos)
- [Resources](#resources)
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Uninstall](#uninstall)
<!-- END MUNGE: GENERATED_TOC -->
## 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
```
$ dcos config prepend package.sources https://github.com/mesosphere/multiverse/archive/version-1.x.zip
$ dcos package update --validate
```
```
$ dcos config prepend package.sources https://github.com/mesosphere/multiverse/archive/version-1.x.zip
$ dcos package update --validate
```
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
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
ID MEM CPUS TASKS HEALTH DEPLOYMENT CONTAINER CMD
/etcd 128 0.2 1/1 1/1 --- DOCKER None
```
```
$ dcos marathon app list
ID MEM CPUS TASKS HEALTH DEPLOYMENT CONTAINER CMD
/etcd 128 0.2 1/1 1/1 --- DOCKER None
```
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
{
"kubernetes": {
"etcd-mesos-framework-name": "etcd"
```
$ cat >/tmp/options.json <<EOF
{
"kubernetes": {
"etcd-mesos-framework-name": "etcd"
}
}
}
EOF
```
EOF
```
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
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
ID MEM CPUS TASKS HEALTH DEPLOYMENT CONTAINER CMD
/etcd 128 0.2 1/1 1/1 --- DOCKER None
/kubernetes 768 1 1/1 1/1 --- DOCKER None
```
```
$ dcos marathon app list
ID MEM CPUS TASKS HEALTH DEPLOYMENT CONTAINER CMD
/etcd 128 0.2 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
```
$ dcos kubectl get pods --namespace=kube-system
NAME READY STATUS RESTARTS AGE
kube-dns-v8-tjxk9 4/4 Running 0 1m
kube-ui-v2-tjq7b 1/1 Running 0 1m
```
```
$ dcos kubectl get pods --namespace=kube-system
NAME READY STATUS RESTARTS AGE
kube-dns-v8-tjxk9 4/4 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).
@ -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:
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=kube-system
```
```
$ dcos kubectl delete rc,pods --all --namespace=default
$ dcos kubectl delete rc,pods --all --namespace=kube-system
```
2. Validate that all pods have been deleted
```
$ dcos kubectl get pods --all-namespaces
```
```
$ dcos kubectl get pods --all-namespaces
```
3. Uninstall Kubernetes
```
$ dcos package uninstall kubernetes
```
```
$ dcos package uninstall kubernetes
```
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->

View File

@ -31,12 +31,33 @@ Documentation for other releases can be found at
<!-- 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
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
- pod/service development
@ -58,7 +79,7 @@ Non-Goals:
- long running
- state persistence across restarts
### Cluster Topology
## Cluster Topology
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 Scheduler | scheduler | Schedules container deployment by accepting Mesos offers |
### Prerequisites
## Prerequisites
Required:
- [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
- 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.
@ -106,7 +127,7 @@ boot2docker up
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
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).
#### 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
host machine (mac).
@ -146,7 +167,7 @@ host machine (mac).
To delete the route later: `sudo route delete 172.17.0.0`
### Walkthrough
## Walkthrough
1. Checkout source
@ -226,10 +247,10 @@ host machine (mac).
1. Explore examples
To learn more about Pods, Volumes, Labels, Services, and Replication Controllers, start with the
[Kubernetes Walkthrough](../user-guide/walkthrough/).
To learn more about Pods, Volumes, Labels, Services, and Replication Controllers, start with the
[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
@ -237,7 +258,7 @@ host machine (mac).
./cluster/kube-down.sh
```
### Addons
## Addons
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
```
#### KubeUI
### KubeUI
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`.
### 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.
@ -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 &
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`
### Helpful scripts
## Helpful scripts
- 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
```
### 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:

View File

@ -30,20 +30,25 @@ Documentation for other releases can be found at
<!-- END STRIP_FOR_RELEASE -->
<!-- END MUNGE: UNVERSIONED_WARNING -->
Getting started with Kubernetes on Mesos
----------------------------------------
**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)
- [Deploy Kubernetes-Mesos](#deploy-kubernetes-mesos)
- [Deploy etcd](#deploy-etcd)
- [Start Kubernetes-Mesos Services](#start-kubernetes-mesos-services)
- [Validate KM Services](#validate-km-services)
- [Spin up a pod](#spin-up-a-pod)
- [Run the Example Guestbook App](#run-the-example-guestbook-app)
- [Test Guestbook App](#test-guestbook-app)
- [Validate KM Services](#validate-km-services)
- [Spin up a pod](#spin-up-a-pod)
- [Launching kube-dns](#launching-kube-dns)
- [What next?](#what-next)
<!-- END MUNGE: GENERATED_TOC -->
## About Kubernetes on Mesos
@ -64,13 +69,13 @@ Further information is available in the Kubernetes on Mesos [contrib directory][
### Prerequisites
* Understanding of [Apache Mesos][6]
* A running [Mesos cluster on Google Compute Engine][5]
* A [VPN connection][10] to the cluster
* A machine in the cluster which should become the Kubernetes *master node* with:
* GoLang > 1.2
* make (i.e. build-essential)
* Docker
- Understanding of [Apache Mesos][6]
- A running [Mesos cluster on Google Compute Engine][5]
- A [VPN connection][10] to the cluster
- A machine in the cluster which should become the Kubernetes *master node* with:
- GoLang > 1.2
- make (i.e. build-essential)
- Docker
**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].
The kube-dns addon runs as a pod inside the cluster. The pod consists of three co-located containers:
- a local etcd instance
- the [skydns][11] DNS server
- 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
We assume that kube-dns will use
- the service IP `10.10.10.10`
- and the `cluster.local` domain.