Add a central simple getting started guide with kubernetes guide.

Point several getting started guides at this doc.
kubernetes · May 2, 2015 · 37eedef · 37eedef
1 parent 262c34e
commit 37eedef
Show file tree

Hide file tree

Showing 10 changed files with 213 additions and 212 deletions.
diff --git a/docs/design/simple-rolling-update.md b/docs/design/simple-rolling-update.md
@@ -57,7 +57,6 @@ then ```foo-next``` is synthesized using the pattern ```<controller-name>-<hash-
 #### Initialization
    * If ```foo``` and ```foo-next``` do not exist:
       * Exit, and indicate an error to the user, that the specified controller doesn't exist.
-      * Goto Rollout
    * If ```foo``` exists, but ```foo-next``` does not:
       * Create ```foo-next``` populate it with the ```v2``` image, set ```desired-replicas``` to ```foo.Spec.Replicas```
       * Goto Rollout

diff --git a/docs/getting-started-guides/aws.md b/docs/getting-started-guides/aws.md
@@ -32,97 +32,21 @@ Once the cluster is up, it will print the ip address of your cluster, this proce
 export KUBERNETES_MASTER=https://<ip-address>
 ```
 
-Also setup your path to point to the released binaries:
-```
-export PATH=$PATH:$PWD:/kubernetes/cluster
-```
-
-If you run into trouble come ask questions on IRC at #google-containers on freenode.
-
-
-### Running a container (simple version)
-
-Once you have your cluster created you can use ```${SOME_DIR}/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
-cluster/kubectl.sh run-container my-nginx --image=nginx --replicas=2 --port=80
-```
-
-To stop the containers:
-
-```bash
-cluster/kubectl.sh stop rc my-nginx
-```
-
-To delete the containers:
+Copy the appropriate ```kubectl``` binary to somewhere in your ```PATH```, for example:
 
 ```bash
-cluster/kubectl.sh delete rc my-nginx
-```
-
-### Running a container (more complete version)
-
-```bash
-cd kubernetes
-cluster/kubectl.sh create -f docs/getting-started-guides/pod.json
-```
+# OS X
+sudo cp kubernetes/platforms/darwin/amd64/kubectl /usr/local/bin/kubectl
 
-Where pod.json contains something like:
-
-```json
-{
-  "id": "php",
-  "kind": "Pod",
-  "apiVersion": "v1beta1",
-  "desiredState": {
-    "manifest": {
-      "version": "v1beta1",
-      "id": "php",
-      "containers": [{
-        "name": "nginx",
-        "image": "nginx",
-        "ports": [{
-          "containerPort": 80,
-          "hostPort": 8081
-        }],
-        "livenessProbe": {
-          "enabled": true,
-          "type": "http",
-          "initialDelaySeconds": 30,
-          "httpGet": {
-            "path": "/index.html",
-            "port": 8081
-          }
-        }
-      }]
-    }
-  },
-  "labels": {
-    "name": "foo"
-  }
-}
+# Linux
+sudo cp kubernetes/platforms/linux/amd64/kubectl /usr/local/bin/kubectl
 ```
 
-You can see your cluster's pods:
-
-```bash
-cluster/kubectl.sh get pods
-```
-
-and delete the pod you just created:
-
-```bash
-cluster/kubectl.sh delete pods php
-```
 
-Since this pod is scheduled on a minion running in AWS, you will have to enable incoming tcp traffic via the port specified in the
-pod manifest before you see the nginx welcome page. After doing so, it should be visible at http://<external ip of minion running nginx>:<port from manifest>.
+### Getting started with your cluster
+See [a simple nginx example](../../examples/simple-nginx.md) to try out your new cluster.
 
-Look in `examples/` for more examples
+For more complete applications, please look in the [examples directory](../../examples)
 
 ### Tearing down the cluster
 ```bash

diff --git a/docs/getting-started-guides/docker-multinode.md b/docs/getting-started-guides/docker-multinode.md
@@ -40,4 +40,6 @@ See [here](docker-multinode/worker.md) for detailed instructions.
 
 ## Testing your cluster
 
-Once your cluster has been created you can [test it out](docker-multinode/testing.md)
+Once your cluster has been created you can [test it out](docker-multinode/testing.md)
+
+For more complete applications, please look in the [examples directory](../../examples)
diff --git a/docs/getting-started-guides/gce.md b/docs/getting-started-guides/gce.md
@@ -33,99 +33,24 @@ wget -q -O - https://get.k8s.io | bash
 
 This will leave you with a ```kubernetes``` directory on your workstation, and a running cluster.
 
-Feel free to move the ```kubernetes``` directory to the appropriate directory on your workstation (e.g. ```/opt/kubernetes```) then ```cd``` into that directory:
+Copy the appropriate ```kubectl``` binary to somewhere in your ```PATH```, for example:
 
 ```bash
-mv kubernetes ${SOME_DIR}/kubernetes
-cd ${SOME_DIR}/kubernetes
-```
-
-If you run into trouble please see the section on [troubleshooting](https://github.com/brendandburns/kubernetes/blob/docs/docs/getting-started-guides/gce.md#troubleshooting), or come ask questions on IRC at #google-containers on freenode.
-
+# OS X
+sudo cp kubernetes/platforms/darwin/amd64/kubectl /usr/local/bin/kubectl
 
-### Running a container (simple version)
-
-Once you have your cluster created you can use ```${SOME_DIR}/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
-cluster/kubectl.sh run-container my-nginx --image=nginx --replicas=2 --port=80
+# Linux
+sudo cp kubernetes/platforms/linux/amd64/kubectl /usr/local/bin/kubectl
 ```
 
-To stop the containers:
-
-```bash
-cluster/kubectl.sh stop rc my-nginx
-```
-
-To delete the containers:
-
-```bash
-cluster/kubectl.sh delete rc my-nginx
-```
-
-### Running a container (more complete version)
-
-```bash
-cd kubernetes
-cluster/kubectl.sh create -f docs/getting-started-guides/pod.json
-```
-
-Where pod.json contains something like:
-
-```json
-{
-  "id": "php",
-  "kind": "Pod",
-  "apiVersion": "v1beta1",
-  "desiredState": {
-    "manifest": {
-      "version": "v1beta1",
-      "id": "php",
-      "containers": [{
-        "name": "nginx",
-        "image": "nginx",
-        "ports": [{
-          "containerPort": 80,
-          "hostPort": 8081
-        }],
-        "livenessProbe": {
-          "enabled": true,
-          "type": "http",
-          "initialDelaySeconds": 30,
-          "httpGet": {
-            "path": "/index.html",
-            "port": 8081
-          }
-        }
-      }]
-    }
-  },
-  "labels": {
-    "name": "foo"
-  }
-}
-```
-
-You can see your cluster's pods:
-
-```bash
-cluster/kubectl.sh get pods
-```
+If you run into trouble please see the section on [troubleshooting](https://github.com/brendandburns/kubernetes/blob/docs/docs/getting-started-guides/gce.md#troubleshooting), or come ask questions on IRC at #google-containers on freenode.
 
-and delete the pod you just created:
 
-```bash
-cluster/kubectl.sh delete pods php
-```
+### Getting started with your cluster
+See [a simple nginx example](../../examples/simple-nginx.md) to try out your new cluster.
 
-Since this pod is scheduled on a minion running in GCE, you will have to enable incoming tcp traffic via the port specified in the
-pod manifest before you see the nginx welcome page. After doing so, it should be visible at http://<external ip of minion running nginx>:<port from manifest>.
+For more complete applications, please look in the [examples directory](../../examples)
 
-Look in `examples/` for more examples
 
 ### Tearing down the cluster
 

diff --git a/docs/getting-started-guides/pod.json b/docs/getting-started-guides/pod.json
diff --git a/examples/examples_test.go b/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))

diff --git a/examples/pod.yaml b/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
diff --git a/examples/replication.yaml b/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