Merge pull request kubernetes#1784 from JaysonRaymond/master

CoreOS Getting Started Guide: should specify required cloud-config changes kubernetes#1770
duda · Oct 27, 2014 · de8a68e · de8a68e
2 parents b8ad04d + 9892b0e
commit de8a68e
Show file tree

Hide file tree

Showing 3 changed files with 137 additions and 12 deletions.
diff --git a/docs/getting-started-guides/coreos/coreos_cloud_config.md b/docs/getting-started-guides/coreos/coreos_cloud_config.md
@@ -4,32 +4,74 @@ The recommended way to run Kubernetes on CoreOS is to use [Cloud-Config](https:/
 
 ## Setup
 
+Get the cloud-config templates which we'll be editing in place for this example.
+```
+git clone https://github.com/GoogleCloudPlatform/kubernetes.git
+cd kubernetes/docs/getting-started-guides/coreos/configs
+```
+
 ### Standalone
 
-The standalone cloud-config file can be used to setup a single node Kubernetes cluster.
+The standalone cloud-config file can be used to setup a single node Kubernetes cluster that has had CoreOS installed.
 
 * [standalone.yml](configs/standalone.yml)
 
-### Cluster
-
-The following cloud-config files can be used to setup a three node Kubernetes cluster.
-
+Skip to ['Configure Access'](#configure-access).
+
+
+### Cluster 
+
+These are the current instructions for [Kelsey Hightowers blog post Running Kubernetes on CoreOS Part 2](https://coreos.com/blog/running-kubernetes-example-on-CoreOS-part-2/)
+which provides a good background context for understanding Kubernetes and how to set this up using VMWare Fusion Pro.
+
+#### Machine Configuration
+To start we'll need 3 nodes for our cluster with the following:
+*  1 CPU
+*  512 MB RAM
+*  20 GB HDD
+*  2 Network Interfaces
+*  CD ROM (to install CoreOS and to provide configuration from [cloud-drive] (http://coreos.com/docs/cluster-management/setup/cloudinit-config-drive/)
+
+The primary network interface for each machine should be on a network with access to the outside world in order to 
+update CoreOS, access the Docker repository, download Kubernetes, etc. The second interface on each machine should each 
+be connected to a switch. (VMWare Fusion Pro users can create a custom network with DHCP and NAT disabled that these 
+secondary interfaces connected to - see [the blog post](https://coreos.com/blog/running-kubernetes-example-on-CoreOS-part-2/)
+ for screenshots).
+
+Boot each node from the [CoreOS](https://coreos.com/) ISO. Hit 'Return' a few times in the console window of a node. 
+Above the login prompt CoreOS lists the names it has generated for the network interfaces followed by the IP address it 
+has been assigned. Note the first interface name, and proceed to install CoreOS. 
+
+#### Cloud Configuration
+The following cloud-config templates are used to setup a three node Kubernetes cluster.
 * [master.yml](configs/master.yml)
 * [node1.yml](configs/node1.yml)
 * [node2.yml](configs/node2.yml)
 
-### Creating config-drives
+Search for occurrences of 'ens33' in these templates and replace with the interface name provided by CoreOS.
+
+Replace all occurrences of '192.168.12.10' with the IP address you wish to apply to the master node, '192.168.12.11' 
+with the IP address to assign to node1, '192.168.12.12' with IP address for node2. In the section 
+'coreos/units/static.network' set the DNS and Gateway entries to match your network. (VMWare Fusion users can find this 
+information in: "/Library/Preferences/VMware Fusion/vmnet8/dhcpd.conf" see [the blog post](https://coreos.com/blog/running-kubernetes-example-on-CoreOS-part-2/)
+ - be sure to choose static IPs outside the dynamic ip range specified here).
+
+### Configure Access
+
+For both the standalone and cluster configurations, the final change required to the cloud-config file(s) is to replace 
+<ssh_public_key> with your public ssh key (typically the contents of ~/.ssh/id_rsa.pub).
+
+### Create config-drives
+
+Now create the ISO images that cloud-config will access when booting your node(s). 
 
 ```
 mkdir -p /tmp/new-drive/openstack/latest/
 mkdir -p ~/iso
 ```
-```
-git clone https://github.com/GoogleCloudPlatform/kubernetes.git
-cd kubernetes/docs/getting-started-guides/coreos/configs
-```
 
 Using Linux:
+
 ```
 for i in standalone master node1 node2; do
   cp ${i}.yml /tmp/new-drive/openstack/latest/user_data
@@ -38,17 +80,22 @@ done
 ```
 
 Using OS X:
+
 ```
 for i in standalone master node1 node2; do
   cp ${i}.yml /tmp/new-drive/openstack/latest/user_data
   hdiutil makehybrid -iso -joliet -joliet-volume-name "config-2" -joliet -o ~/iso/${i}.iso /tmp/new-drive
 done
 ```
 
+Make each ISO file accessible to its corresponding node by using it to define a cd/dvd drive for the VM (or create a 
+physical CD for bare metal), and boot the node. At the consoles login prompt, confirm the configured IP address for the 
+node is listed next to the interface name.
 
 ## Remote Access
 
-Setup a SSH tunnel to the Kubernetes API Server.
+Setup a SSH tunnel to the Kubernetes API Server, replacing ${APISERVER} with the IP address of your master or 
+standalone node. 
 
 ```
 sudo ssh -f -nNT -L 8080:127.0.0.1:8080 core@${APISERVER}
@@ -73,3 +120,12 @@ Issue commands remotely using the kubecfg command line tool.
 ```
 kubecfg list /pods
 ```
+
+Test a sample pod:
+
+````
+kubecfg -c examples/guestbook-go/redis-master-pod.json create pods
+kubecfg list /pods
+```
+
+Your pod should now be listed as 'running'.
diff --git a/docs/getting-started-guides/coreos/coreos_quick_start.md b/docs/getting-started-guides/coreos/coreos_quick_start.md
@@ -1,6 +1,8 @@
 # CoreOS Quick Start Guide
 
-The following steps will setup a single node Kubernetes cluster. For a more robust setup using cloud-config see the [Installation Guide](docs/installation.md).
+The following steps will setup a single node Kubernetes cluster. For a more robust setup using cloud-config see the 
+[Installation Guide](coreos_cloud_config.md) which automates the entire set-up. Those not installing via cloud-config 
+need to define the required network configuration from in the [Network Guide](networking.md).
 
 ### Install Kubernetes binaries
 

diff --git a/docs/getting-started-guides/coreos/networking.md b/docs/getting-started-guides/coreos/networking.md
@@ -0,0 +1,67 @@
+# Network Setup Guide
+
+This guide demostrates a network setup that will work for environments with access to layer 2 networking 
+(bare metal, vmware, etc). The following steps are not required when following the [Installation Guide](coreos_cloud_config.md).
+
+Please note: With some hypervisors, you may have to enable special settings on the virtual network cards for bridging to work (for example, you need to allow 'MAC address spoofing' in Microsoft Hyper-V).
+
+## Hostnames
+
+On each node ensure the hostname is set.
+
+```
+hostnamectl set-hostname master
+hostnamectl set-hostname node1
+hostnamectl set-hostname node2
+```
+
+### Setup /etc/hosts
+
+On each node add the following lines to /etc/hosts:
+
+```
+192.168.12.10 master
+192.168.12.11 node1
+192.168.12.12 node2
+```
+
+## Create the cbr0 bridge
+
+On each node run the following commands to setup the cbr0 bridge used by Docker and Kubernetes.
+
+```
+brctl addbr cbr0
+brctl addif cbr0 ens34
+ip link set dev cbr0 mtu 1460
+ip addr add 10.244.0.1/24 dev cbr0   # this will be different for each minion
+ip link set dev cbr0 up
+ip route add 10.0.0.0/8 dev cbr0
+```
+
+Each node should use a different address. For example:
+
+master
+
+```
+ip addr add 10.244.0.1/24 dev cbr0
+```
+
+node1
+
+```
+ip addr add 10.244.1.1/24 dev cbr0
+```
+
+node2
+
+```
+ip addr add 10.244.2.1/24 dev cbr0
+```
+
+## Configure IP tables
+
+On each node run the following command to allow containers to reach the internet.
+
+```
+iptables -t nat -A POSTROUTING -o ens33 -j MASQUERADE \! -d 10.0.0.0/8
+```