Skip to content

Commit

Permalink
Add tables of contents to getting started guides.
Browse files Browse the repository at this point in the history
  • Loading branch information
@erictune
erictune committed Jun 22, 2015
1 parent 51e0647 commit f39eead
Show file tree
Hide file tree
Showing 21 changed files with 308 additions and 43 deletions.
14 changes: 14 additions & 0 deletions docs/getting-started-guides/aws.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,19 @@
# Getting started on AWS EC2

## Contents

- [Getting started on AWS EC2](#getting-started-on-aws-ec2)
- [Contents](#contents)
- [Prerequisites](#prerequisites)
- [Cluster turnup](#cluster-turnup)
- [Supported procedure: `get-kube`](#supported-procedure-get-kube)
- [Alternatives](#alternatives)
- [Getting started with your cluster](#getting-started-with-your-cluster)
- [Command line administration tool: `kubectl`](#command-line-administration-tool-kubectl)
- [Examples](#examples)
- [Tearing down the cluster](#tearing-down-the-cluster)
- [Further reading](#further-reading)

## Prerequisites

1. You need an AWS account. Visit [http://aws.amazon.com](http://aws.amazon.com) to get started
Expand Down
23 changes: 17 additions & 6 deletions docs/getting-started-guides/azure.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,31 @@
## Getting started on Microsoft Azure
# Getting started on Microsoft Azure

### Azure Prerequisites
## Contents

- [Getting started on Microsoft Azure](#getting-started-on-microsoft-azure)
- [Contents](#contents)
- [Azure Prerequisites](#azure-prerequisites)
- [Prerequisites for your workstation](#prerequisites-for-your-workstation)
- [Setup](#setup)
- [Getting started with your cluster](#getting-started-with-your-cluster)
- [Tearing down the cluster](#tearing-down-the-cluster)


## Azure Prerequisites

1. You need an Azure account. Visit http://azure.microsoft.com/ to get started.
2. Install and configure the Azure cross-platform command-line interface. http://azure.microsoft.com/en-us/documentation/articles/xplat-cli/
3. Make sure you have a default account set in the Azure cli, using `azure account set`

### Prerequisites for your workstation
## Prerequisites for your workstation

1. Be running a Linux or Mac OS X.
2. Get or build a [binary release](binary_release.md)
3. If you want to build your own release, you need to have [Docker
installed](https://docs.docker.com/installation/). On Mac OS X you can use
[boot2docker](http://boot2docker.io/).

### Setup
## Setup
The cluster setup scripts can setup Kubernetes for multiple targets. First modify `cluster/kube-env.sh` to specify azure:

KUBERNETES_PROVIDER="azure"
Expand All @@ -37,12 +48,12 @@ You can then use the `cluster/kube-*.sh` scripts to manage your azure cluster, s
The script above will start (by default) a single master VM along with 4 worker VMs. You
can tweak some of these parameters by editing `cluster/azure/config-default.sh`.

### Getting started with your cluster
## Getting started with your cluster
See [a simple nginx example](../../examples/simple-nginx.md) to try out your new cluster.

For more complete applications, please look in the [examples directory](../../examples).

### Tearing down the cluster
## Tearing down the cluster
```
cluster/kube-down.sh
```
Expand Down
10 changes: 8 additions & 2 deletions docs/getting-started-guides/centos/centos_manual_config.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@

##Getting started on [CentOS](http://centos.org)
#Getting started on [CentOS](http://centos.org)

## Contents

- [Getting started on [CentOS](http://centos.org)](#getting-started-on-centoshttpcentosorg)
- [Contents](#contents)
- [Starting a cluster](#starting-a-cluster)

## Starting a cluster
This is a getting started guide for CentOS. It is a manual configuration so you understand all the underlying packages / services / ports, etc...

This guide will only get ONE minion working. Multiple minions requires a functional [networking configuration](http://docs.k8s.io/networking.md) done outside of kubernetes. Although the additional kubernetes configuration requirements should be obvious.
Expand Down
23 changes: 16 additions & 7 deletions docs/getting-started-guides/cloudstack.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
## Deploying Kubernetes on [CloudStack](http://cloudstack.apache.org)

## Contents

- [Deploying Kubernetes on [CloudStack](http://cloudstack.apache.org)](#deploying-kubernetes-on-cloudstackhttpcloudstackapacheorg)
- [Contents](#contents)
- [Introduction](#introduction)
- [Ansible playbook](#ansible-playbook)
- [Prerequisites](#prerequisites)
- [Clone the playbook](#clone-the-playbook)
- [Create a Kubernetes cluster](#create-a-kubernetes-cluster)

## Introduction

CloudStack is a software to build public and private clouds based on hardware virtualization principles (traditional IaaS). To deploy Kubernetes on CloudStack there are several possibilities depending on the Cloud being used and what images are made available. [Exoscale](http://exoscale.ch) for instance makes a [CoreOS](http://coreos.com) template available, therefore instructions to deploy Kubernetes on coreOS can be used. CloudStack also has a vagrant plugin available, hence Vagrant could be used to deploy Kubernetes either using the existing shell provisioner or using new Salt based recipes.

[CoreOS](http://coreos.com) templates for CloudStack are built [nightly](http://stable.release.core-os.net/amd64-usr/current/). CloudStack operators need to [register](http://docs.cloudstack.apache.org/projects/cloudstack-administration/en/latest/templates.html) this template in their cloud before proceeding with these Kubernetes deployment instructions.
Expand All @@ -12,12 +24,11 @@ There are currently two deployment techniques.
* [Ansible playbook](https://github.com/runseb/ansible-kubernetes).
This is completely automated, a single playbook deploys Kubernetes based on the coreOS [instructions](http://docs.k8s.io/getting-started-guides/coreos/coreos_multinode_cluster.md).

#Ansible playbook
## Ansible playbook

This [Ansible](http://ansibleworks.com) playbook deploys Kubernetes on a CloudStack based Cloud using CoreOS images. The playbook, creates an ssh key pair, creates a security group and associated rules and finally starts coreOS instances configured via cloud-init.

Prerequisites
-------------
###Prerequisites

$ sudo apt-get install -y python-pip
$ sudo pip install ansible
Expand All @@ -39,16 +50,14 @@ Or create a `~/.cloudstack.ini` file:

We need to use the http POST method to pass the _large_ userdata to the coreOS instances.

Clone the playbook
------------------
###Clone the playbook

$ git clone --recursive https://github.com/runseb/ansible-kubernetes.git
$ cd ansible-kubernetes

The [ansible-cloudstack](https://github.com/resmo/ansible-cloudstack) module is setup in this repository as a submodule, hence the `--recursive`.

Create a Kubernetes cluster
---------------------------
###Create a Kubernetes cluster

You simply need to run the playbook.

Expand Down
12 changes: 12 additions & 0 deletions docs/getting-started-guides/coreos/azure/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Kubernetes on Azure with CoreOS and [Weave](http://weave.works)

## Contents

- [Kubernetes on Azure with CoreOS and [Weave](http://weave.works)](#kubernetes-on-azure-with-coreos-and-weavehttpweaveworks)
- [Contents](#contents)
- [Introduction](#introduction)
- [Let's go!](#lets-go)
- [Deploying the workload](#deploying-the-workload)
- [Scaling](#scaling)
- [Exposing the app to the outside world](#exposing-the-app-to-the-outside-world)
- [Next steps](#next-steps)
- [Tear down...](#tear-down)

## Introduction

In this guide I will demonstrate how to deploy a Kubernetes cluster to Azure cloud. You will be using CoreOS with Weave, which implements simple and secure networking, in a transparent, yet robust way. The purpose of this guide is to provide an out-of-the-box implementation that can ultimately be taken into production with little change. It will demonstrate how to provision a dedicated Kubernetes master and etcd nodes, and show how to scale the cluster with ease.
Expand Down
23 changes: 22 additions & 1 deletion docs/getting-started-guides/coreos/bare_metal_offline.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,27 @@
# Bare Metal CoreOS with Kubernetes (OFFLINE)
Deploy a CoreOS running Kubernetes environment. This particular guild is made to help those in an OFFLINE system, wither for testing a POC before the real deal, or you are restricted to be totally offline for your applications.

## Contents

- [Bare Metal CoreOS with Kubernetes (OFFLINE)](#bare-metal-coreos-with-kubernetes-offline)
- [Contents](#contents)
- [High Level Design](#high-level-design)
- [Pre-requisites](#pre-requisites)
- [This Guides variables](#this-guides-variables)
- [Setup PXELINUX CentOS](#setup-pxelinux-centos)
- [Adding CoreOS to PXE](#adding-coreos-to-pxe)
- [DHCP configuration](#dhcp-configuration)
- [Kubernetes](#kubernetes)
- [Cloud Configs](#cloud-configs)
- [master.yml](#masteryml)
- [cloud-config](#cloud-config)
- [node.yml](#nodeyml)
- [cloud-config](#cloud-config)
- [New pxelinux.cfg file](#new-pxelinuxcfg-file)
- [Specify the pxelinux targets](#specify-the-pxelinux-targets)
- [Creating test pod](#creating-test-pod)
- [Helping commands for debugging](#helping-commands-for-debugging)


## High Level Design
1. Manage the tftp directory
Expand Down Expand Up @@ -159,7 +180,7 @@ This section covers configuring the DHCP server to hand out our new images. In t

We will be specifying the node configuration later in the guide.

# Kubernetes
## Kubernetes
To deploy our configuration we need to create an ```etcd``` master. To do so we want to pxe CoreOS with a specific cloud-config.yml. There are two options we have here.
1. Is to template the cloud config file and programmatically create new static configs for different cluster setups.
2. Have a service discovery protocol running in our stack to do auto discovery.
Expand Down
14 changes: 9 additions & 5 deletions docs/getting-started-guides/docker-multinode.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,18 @@
### Running Multi-Node Kubernetes Using Docker
# Running Multi-Node Kubernetes Using Docker

_Note_:
These instructions are somewhat significantly more advanced than the [single node](docker.md) instructions. If you are
interested in just starting to explore Kubernetes, we recommend that you start there.

## Table of Contents
* [Overview](#overview)
* [Installing the master node](#master-node)
* [Installing a worker node](#adding-a-worker-node)
* [Testing your cluster](#testing-your-cluster)

- [Running Multi-Node Kubernetes Using Docker](#running-multi-node-kubernetes-using-docker)
- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [Bootstrap Docker](#bootstrap-docker)
- [Master Node](#master-node)
- [Adding a worker node](#adding-a-worker-node)
- [Testing your cluster](#testing-your-cluster)

## Overview
This guide will set up a 2-node kubernetes cluster, consisting of a _master_ node which hosts the API server and orchestrates work
Expand Down
17 changes: 16 additions & 1 deletion docs/getting-started-guides/docker.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,19 @@
## Running kubernetes locally via Docker
# Running kubernetes locally via Docker

## Contents

- [Running kubernetes locally via Docker](#running-kubernetes-locally-via-docker)
- [Contents](#contents)
- [Setting up a Cluster](#setting-up-a-cluster)
- [Step One: Run etcd](#step-one-run-etcd)
- [Step Two: Run the master](#step-two-run-the-master)
- [Step Three: Run the service proxy](#step-three-run-the-service-proxy)
- [Test it out](#test-it-out)
- [Run an application](#run-an-application)
- [Expose it as a service:](#expose-it-as-a-service)
- [A note on turning down your cluster](#a-note-on-turning-down-your-cluster)

## Setting up a Cluster

The following instructions show you how to set up a simple, single node kubernetes cluster using Docker.

Expand Down
13 changes: 12 additions & 1 deletion docs/getting-started-guides/fedora/fedora_ansible_config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,18 @@

Configuring kubernetes on Fedora via Ansible offers a simple way to quickly create a clustered environment with little effort.

Requirements:
## Contents

- [Configuring kubernetes on [Fedora](http://fedoraproject.org) via [Ansible](http://www.ansible.com/home).](#configuring-kubernetes-on-fedorahttpfedoraprojectorg-via-ansiblehttpwwwansiblecomhome)
- [Contents](#contents)
- [Requirements](#requirements)
- [Architecture of the cluster](#architecture-of-the-cluster)
- [Configuring ssh access to the cluster](#configuring-ssh-access-to-the-cluster)
- [Configuring the internal kubernetes network](#configuring-the-internal-kubernetes-network)
- [Setting up the cluster](#setting-up-the-cluster)
- [Testing and using your new cluster](#testing-and-using-your-new-cluster)

##Requirements

1. Host able to run ansible and able to clone the following repo: [kubernetes-ansible](https://github.com/eparis/kubernetes-ansible)
2. A Fedora 20+ or RHEL7 host to act as cluster master
Expand Down
10 changes: 9 additions & 1 deletion docs/getting-started-guides/fedora/fedora_manual_config.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,12 @@
##Getting started on [Fedora](http://fedoraproject.org)
#Getting started on [Fedora](http://fedoraproject.org)

## Contents

- [Getting started on [Fedora](http://fedoraproject.org)](#getting-started-on-fedorahttpfedoraprojectorg)
- [Contents](#contents)
- [Instructions](#instructions)

## Instructions

This is a getting started guide for Fedora. It is a manual configuration so you understand all the underlying packages / services / ports, etc...

Expand Down
21 changes: 18 additions & 3 deletions docs/getting-started-guides/fedora/flannel_multi_node_cluster.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,21 @@
#**Kubernetes multiple nodes cluster with flannel on Fedora**
#Kubernetes multiple nodes cluster with flannel on Fedora

## Contents

- [Kubernetes multiple nodes cluster with flannel on Fedora](#kubernetes-multiple-nodes-cluster-with-flannel-on-fedora)
- [Contents](#contents)
- [Introduction](#introduction)
- [Master Setup](#master-setup)
- [Node Setup](#node-setup)
- [**Test the cluster and flannel configuration**](#test-the-cluster-and-flannel-configuration)

## Introduction

This document describes how to deploy kubernetes on multiple hosts to set up a multi-node cluster and networking with flannel. Follow fedora [getting started guide](fedora_manual_config.md) to setup 1 master (fed-master) and 2 or more nodes (minions). Make sure that all nodes (minions) have different names (fed-node1, fed-node2 and so on) and labels (fed-node1-label, fed-node2-label, and so on) to avoid any conflict. Also make sure that the kubernetes master host is running etcd, kube-controller-manager, kube-scheduler, and kube-apiserver services, and the nodes (minions) are running docker, kube-proxy and kubelet services. Now install flannel on kubernetes nodes (minions). flannel on each node configures an overlay network that docker uses. flannel runs on each node to setup a unique class-C container network.

##**Perform following commands on the kubernetes master**
## Master Setup

**Perform following commands on the kubernetes master**

* Configure flannel by creating a `flannel-config.json` in your current directory on fed-master. flannel provides udp and vxlan among other overlay networking backend options. In this guide, we choose kernel based vxlan backend. The contents of the json are:

Expand Down Expand Up @@ -30,7 +43,9 @@ This document describes how to deploy kubernetes on multiple hosts to set up a m
# etcdctl get /coreos.com/network/config
```

##**Perform following commands on all kubernetes nodes**
## Node Setup

**Perform following commands on all kubernetes nodes**

* Edit the flannel configuration file /etc/sysconfig/flanneld as follows:

Expand Down
30 changes: 16 additions & 14 deletions docs/getting-started-guides/gce.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,22 @@

**Table of Contents**

- [Before you start](#before-you-start)
- [Prerequisites](#prerequisites)
- [Starting a cluster](#starting-a-cluster)
- [Installing the kubernetes command line tools on your workstation](#installing-the-kubernetes-command-line-tools-on-your-workstation)
- [Getting started with your cluster](#getting-started-with-your-cluster)
- [Inspect your cluster](#inspect-your-cluster)
- [Run some examples](#run-some-examples)
- [Tearing down the cluster](#tearing-down-the-cluster)
- [Customizing](#customizing)
- [Troubleshooting](#troubleshooting)
- [Project settings](#project-settings)
- [Cluster initialization hang](#cluster-initialization-hang)
- [SSH](#ssh)
- [Networking](#networking)
- [Getting started on Google Compute Engine](#getting-started-on-google-compute-engine)
- [Before you start](#before-you-start)
- [Prerequisites](#prerequisites)
- [Starting a cluster](#starting-a-cluster)
- [Installing the kubernetes command line tools on your workstation](#installing-the-kubernetes-command-line-tools-on-your-workstation)
- [Getting started with your cluster](#getting-started-with-your-cluster)
- [Inspect your cluster](#inspect-your-cluster)
- [Run some examples](#run-some-examples)
- [Tearing down the cluster](#tearing-down-the-cluster)
- [Customizing](#customizing)
- [Troubleshooting](#troubleshooting)
- [Project settings](#project-settings)
- [Cluster initialization hang](#cluster-initialization-hang)
- [SSH](#ssh)
- [Networking](#networking)


The example below creates a Kubernetes cluster with 4 worker node Virtual Machines and a master Virtual Machine (i.e. 5 VMs in your cluster). This cluster is set up and controlled from your workstation (or wherever you find convenient).

Expand Down
16 changes: 16 additions & 0 deletions docs/getting-started-guides/juju.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,22 @@ Juju handles provisioning machines and deploying complex systems to a
wide number of clouds, supporting service orchestration once the bundle of
services has been deployed.

## Contents

- [Getting started with Juju](#getting-started-with-juju)
- [Contents](#contents)
- [Prerequisites](#prerequisites)
- [On Ubuntu](#on-ubuntu)
- [With Docker](#with-docker)
- [Launch Kubernetes cluster](#launch-kubernetes-cluster)
- [Exploring the cluster](#exploring-the-cluster)
- [Run some containers!](#run-some-containers)
- [Scale out cluster](#scale-out-cluster)
- [Launch the "k8petstore" example app](#launch-the-k8petstore-example-app)
- [Tear down cluster](#tear-down-cluster)
- [More Info](#more-info)
- [Cloud compatibility](#cloud-compatibility)


### Prerequisites

Expand Down
15 changes: 15 additions & 0 deletions docs/getting-started-guides/libvirt-coreos.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,20 @@
## Getting started with libvirt CoreOS

## Contents

- [Getting started with libvirt CoreOS](#getting-started-with-libvirt-coreos)
- [Contents](#contents)
- [Highlights](#highlights)
- [Prerequisites](#prerequisites)
- [Setup](#setup)
- [Interacting with your Kubernetes cluster with the `kube-*` scripts.](#interacting-with-your-kubernetes-cluster-with-the-kube--scripts)
- [Troubleshooting](#troubleshooting)
- [!!! Cannot find kubernetes-server-linux-amd64.tar.gz](#-cannot-find-kubernetes-server-linux-amd64targz)
- [Can't find virsh in PATH, please fix and retry.](#cant-find-virsh-in-path-please-fix-and-retry)
- [error: Failed to connect socket to '/var/run/libvirt/libvirt-sock': No such file or directory](#error-failed-to-connect-socket-to-varrunlibvirtlibvirt-sock-no-such-file-or-directory)
- [error: Failed to connect socket to '/var/run/libvirt/libvirt-sock': Permission denied](#error-failed-to-connect-socket-to-varrunlibvirtlibvirt-sock-permission-denied)
- [error: Out of memory initializing network (virsh net-create...)](#error-out-of-memory-initializing-network-virsh-net-create)

### Highlights

* Super-fast cluster boot-up (few seconds instead of several minutes for vagrant)
Expand Down
Loading

0 comments on commit f39eead

Please sign in to comment.