Add a central simple getting started guide with kubernetes guide.

Point several getting started guides at this doc.

examples/examples_test.go

@@ -115,9 +115,6 @@ func walkJSONFiles(inDir string, fn func(name, path string, data []byte)) error
 
 func TestExampleObjectSchemas(t *testing.T) {
 	cases := map[string]map[string]runtime.Object{
-		"../docs/getting-started-guides": {
-			"pod": &api.Pod{},
-		},
 		"../cmd/integration": {
 			"v1beta1-controller": &api.ReplicationController{},
 			"v1beta3-controller": &api.ReplicationController{},
@@ -177,6 +174,10 @@ func TestExampleObjectSchemas(t *testing.T) {
 		"../examples/glusterfs/v1beta3": {
 			"glusterfs": &api.Pod{},
 		},
+		"../examples": {
+			"pod":         &api.Pod{},
+			"replication": &api.ReplicationController{},
+		},
 	}
 
 	for path, expected := range cases {
@@ -225,14 +226,18 @@ var sampleRegexp = regexp.MustCompile("(?ms)^```(?:(?P<type>yaml)\\w*\\n(?P<cont
 var subsetRegexp = regexp.MustCompile("(?ms)\\.{3}")
 
 func TestReadme(t *testing.T) {
-	paths := []string{
-		"../README.md",
-		"../examples/walkthrough/README.md",
-		"../examples/iscsi/README.md",
+	paths := []struct {
+		file         string
+		expectedType []runtime.Object
+	}{
+		{"../README.md", []runtime.Object{&api.Pod{}}},
+		{"../examples/walkthrough/README.md", []runtime.Object{&api.Pod{}}},
+		{"../examples/iscsi/README.md", []runtime.Object{&api.Pod{}}},
+		{"../examples/simple-yaml.md", []runtime.Object{&api.Pod{}, &api.ReplicationController{}}},
 	}
 
 	for _, path := range paths {
-		data, err := ioutil.ReadFile(path)
+		data, err := ioutil.ReadFile(path.file)
 		if err != nil {
 			t.Errorf("Unable to read file %s: %v", path, err)
 			continue
@@ -242,6 +247,7 @@ func TestReadme(t *testing.T) {
 		if matches == nil {
 			continue
 		}
+		ix := 0
 		for _, match := range matches {
 			var content, subtype string
 			for i, name := range sampleRegexp.SubexpNames() {
@@ -257,8 +263,13 @@ func TestReadme(t *testing.T) {
 				continue
 			}
 
-			//t.Logf("testing (%s): \n%s", subtype, content)
-			expectedType := &api.Pod{}
+			var expectedType runtime.Object
+			if len(path.expectedType) == 1 {
+				expectedType = path.expectedType[0]
+			} else {
+				expectedType = path.expectedType[ix]
+				ix++
+			}
 			json, err := yaml.ToJSON([]byte(content))
 			if err != nil {
 				t.Errorf("%s could not be converted to JSON: %v\n%s", path, err, string(content))

examples/pod.yaml

@@ -0,0 +1,16 @@
+apiVersion: v1beta3
+kind: Pod
+metadata:
+  labels:
+    name: nginx
+  name: nginx
+  namespace: default
+spec:
+  containers:
+  - image: nginx
+    imagePullPolicy: IfNotPresent
+    name: nginx
+    ports:
+    - containerPort: 80
+      protocol: TCP
+  restartPolicy: Always

examples/replication.yaml

@@ -0,0 +1,23 @@
+apiVersion: v1beta3
+kind: ReplicationController
+metadata:
+  name: nginx
+  namespace: default
+spec:
+  replicas: 3
+  selector:
+    app: nginx
+  template:
+    metadata:
+      name: nginx
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        imagePullPolicy: IfNotPresent
+        name: nginx
+        ports:
+        - containerPort: 80
+          protocol: TCP
+      restartPolicy: Always

examples/simple-nginx.md

@@ -0,0 +1,44 @@
+## Running your first containers in Kubernetes
+
+Ok, you've run one of the [getting started guides](../docs/getting-started-guides/) and you have
+successfully turned up a Kubernetes cluster.  Now what?  This guide will help you get oriented
+to Kubernetes and running your first containers on the cluster.
+
+### Running a container (simple version)
+
+Assume that ```${KUBERNETES_HOME}``` points to the directory where you installed the kubernetes directory.
+
+Once you have your cluster created you can use ```${KUBERNETES_HOME/kubernetes/cluster/kubectl.sh``` to access
+the kubernetes api.
+
+The `kubectl.sh` line below spins up two containers running
+[Nginx](http://nginx.org/en/) running on port 80:
+
+```bash
+kubectl run-container my-nginx --image=nginx --replicas=2 --port=80
+```
+
+Once the pods are created, you can list them to see what is up and running:
+```base
+kubectl get pods
+```
+
+To stop the two replicated containers:
+
+```bash
+kubectl stop rc my-nginx
+```
+
+### Exposing your pods to the internet.
+On some platforms (for example Google Compute Engine) the kubectl command can integrate with your cloud provider to add a public IP address for the pods,
+to do this run:
+
+```bash
+kubectl expose rc nginx --port=80 --create-external-load-balancer
+```
+
+This should print the service that has been created, and map an external IP address to the service.
+
+### Next: Configuration files
+Most people will eventually want to use declarative configuration files for creating/modifying their applications.  A [simplified introduction](simple-yaml.md)
+is given in a different document.

examples/simple-yaml.md

@@ -0,0 +1,89 @@
+## Getting started with config files.
+
+In addition to the imperative style commands described [elsewhere](simple-nginx.md), Kubernetes
+supports declarative YAML or JSON configuration files.  Often times config files are prefereable
+to imperative commands, since they can be checked into version control and changes to the files
+can be code reviewed, producing a more robust, reliable and archival system.
+
+### Running a container from a pod configuration file
+
+```bash
+cd kubernetes
+kubectl create -f pod.yaml
+```
+
+Where pod.yaml contains something like:
+
+```yaml
+apiVersion: v1beta3
+kind: Pod
+metadata:
+  labels:
+    app: nginx
+  name: nginx
+  namespace: default
+spec:
+  containers:
+  - image: nginx
+    imagePullPolicy: IfNotPresent
+    name: nginx
+    ports:
+    - containerPort: 80
+      protocol: TCP
+  restartPolicy: Always
+```
+
+You can see your cluster's pods:
+
+```bash
+kubectl get pods
+```
+
+and delete the pod you just created:
+
+```bash
+kubectl delete pods nginx
+```
+
+### Running a replicated set of containers from a configuration file
+To run replicated containers, you need a [Replication Controller](../docs/replication-controller.md).
+A replication controller is responsible for ensuring that a specific number of pods exist in the
+cluster.
+
+```bash
+cd kubernetes
+kubectl create -f replication.yaml
+```
+
+Where ```replication.yaml``` contains:
+
+```yaml
+apiVersion: v1beta3
+kind: ReplicationController
+metadata:
+  name: nginx
+  namespace: default
+spec:
+  replicas: 3
+  selector:
+    app: nginx
+  template:
+    metadata:
+      name: nginx
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        imagePullPolicy: IfNotPresent
+        name: nginx
+        ports:
+        - containerPort: 80
+          protocol: TCP
+      restartPolicy: Always
+```
+
+To delete the replication controller (and the pods it created):
+```bash
+kubectl delete rc nginx
+```