Merge pull request #11396 from mikedanese/fixups

fixup kubectl walktrough example
kubernetes · Jul 17, 2015 · 5124a15 · 5124a15
2 parents 665c951 + a654318
commit 5124a15
Show file tree

Hide file tree

Showing 3 changed files with 77 additions and 69 deletions.
diff --git a/docs/user-guide/prereqs.md b/docs/user-guide/prereqs.md
@@ -39,10 +39,41 @@ export PATH=<path/to/kubernetes-directory>/platforms/linux/amd64:$PATH
 ##Configure kubectl
 In order for kubectl to find and access the Kubernetes cluster, it needs a [kubeconfig file](kubeconfig-file.md), which is created automatically when creating a cluster using kube-up.sh (see the [getting started guides](../../docs/getting-started-guides/) for more about creating clusters). If you need access to a cluster you didn’t create, see the [Sharing Cluster Access document](sharing-clusters.md).
 
+#### Installing Kubectl
+
+If you downloaded a pre-compiled release, kubectl should be under `platforms/<os>/<arch>`.
+
+If you built from source, kubectl should be either under `_output/local/bin/<os>/<arch>` or `_output/dockerized/bin/<os>/<arch>`.
+
+The kubectl binary doesn't have to be installed to be executable, but the rest of the walkthrough will assume that it's in your PATH.
+
+The simplest way to install is to copy or move kubectl into a dir already in PATH (e.g. `/usr/local/bin`). For example:
+
+```bash
+# OS X
+sudo cp kubernetes/platforms/darwin/amd64/kubectl /usr/local/bin/kubectl
+# Linux
+sudo cp kubernetes/platforms/linux/amd64/kubectl /usr/local/bin/kubectl
+ ```
+
+#### Configuring Kubectl
+
+If you used `./cluster/kube-up.sh` to deploy your Kubernetes cluster, kubectl should already be locally configured.
+
+By default, kubectl configuration lives at `~/.kube/config`.
+
+If your cluster was deployed by other means (e.g. a [getting started guide](../getting-started-guides/README.md)) your kubectl client will typically be configured during that process. If for some reason your kubectl client is not yet configured, check out [kubeconfig-file.md](kubeconfig-file.md).
+
+#### Making sure you're ready
+
 Check that kubectl is properly configured by getting the cluster state:
-```
+
+```sh
 $ kubectl cluster-info
 ```
+
+If you see a url response, you are ready to go.
+
 ## What's next?
 
 [Learn how to launch and expose your application.](quick-start.md)

diff --git a/docs/user-guide/walkthrough/README.md b/docs/user-guide/walkthrough/README.md
@@ -20,60 +20,33 @@ certainly want the docs that go with that version.</h1>
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
-# Kubernetes 101 - Kubectl CLI & Pods
+# Kubernetes 101 - Kubectl CLI and Pods
 
 For Kubernetes 101, we will cover kubectl, pods, volumes, and multiple containers
 
 In order for the kubectl usage examples to work, make sure you have an examples directory locally, either from [a release](https://github.com/GoogleCloudPlatform/kubernetes/releases) or [the source](https://github.com/GoogleCloudPlatform/kubernetes).
 
-Table of Contents
-- [Kubectl CLI](#kubectl-cli)
-  - [Install Kubectl](#install-kubectl)
-  - [Configure Kubectl](#configure-kubectl)
-- [Pods](#pods)
-  - [Pod Definition](#pod-definition)
-  - [Pod Management](#pod-management)
-  - [Volumes](#volumes)
-  - [Multiple Containers](#multiple-containers)
-- [What's Next?](#whats-next)
+**Table of Contents**
+<!-- BEGIN MUNGE: GENERATED_TOC -->
+- [Kubernetes 101 - Kubectl CLI and Pods](#kubernetes-101---kubectl-cli-and-pods)
+  - [Kubectl CLI](#kubectl-cli)
+  - [Pods](#pods)
+      - [Pod Definition](#pod-definition)
+      - [Pod Management](#pod-management)
+      - [Volumes](#volumes)
+        - [Volume Types](#volume-types)
+      - [Multiple Containers](#multiple-containers)
+  - [What's Next?](#whats-next)
 
+<!-- END MUNGE: GENERATED_TOC -->
 
 ## Kubectl CLI
 
-The easiest way to interact with Kubernetes is via the command-line interface.
-
-If you downloaded a pre-compiled release, kubectl should be under `platforms/<os>/<arch>`.
-
-If you built from source, kubectl should be either under `_output/local/bin/<os>/<arch>` or `_output/dockerized/bin/<os>/<arch>`.
+The easiest way to interact with Kubernetes is via the [kubectl](../kubectl/kubectl.md) command-line interface.
 
 For more info about kubectl, including its usage, commands, and parameters, see the [kubectl CLI reference](../kubectl/kubectl.md).
 
-#### Install Kubectl
-
-The kubectl binary doesn't have to be installed to be executable, but the rest of the walkthrough will assume that it's in your PATH.
-
-The simplest way to install is to copy or move kubectl into a dir already in PATH (like `/usr/local/bin`).
-
-An alternate method, useful if you're building from source and want to rebuild without re-installing is to use `./cluster/kubectl.sh` instead of kubectl. That script will auto-detect the location of kubectl and proxy commands to it (ex: `./cluster/kubectl.sh cluster-info`).
-
-#### Configure Kubectl
-
-If you used `./cluster/kube-up.sh` to deploy your Kubernetes cluster, kubectl should already be locally configured.
-
-By default, kubectl configuration lives at `~/.kube/config`.
-
-If your cluster was deployed by other means (e.g. a [getting started guide](../../getting-started-guides/README.md)), you may want to configure the path to the Kubernetes apiserver in your shell environment:
-
-```sh
-export KUBERNETES_MASTER=http://<ip>:<port>/api
-```
-
-Check that kubectl is properly configured by getting the cluster state:
-
-```sh
-kubectl cluster-info
-```
-
+If you haven't installed and configured kubectl, finish the [prerequisites](../prereqs.md) before continuing.
 
 ## Pods
 In Kubernetes, a group of one or more containers is called a _pod_. Containers in a pod are deployed together, and are started, stopped, and replicated as a group.
@@ -108,27 +81,27 @@ See the [design document](../../../DESIGN.md) for more details.
 Create a pod containing an nginx server ([pod-nginx.yaml](pod-nginx.yaml)):
 
 ```sh
-kubectl create -f docs/user-guide/walkthrough/pod-nginx.yaml
+$ kubectl create -f docs/user-guide/walkthrough/pod-nginx.yaml
 ```
 
 List all pods:
 
 ```sh
-kubectl get pods
+$ kubectl get pods
 ```
 
 On most providers, the pod IPs are not externally accessible. The easiest way to test that the pod is working is to create a busybox pod and exec commands on it remotely. See the [command execution documentation](../kubectl/kubectl_exec.md) for details.
 
 Provided the pod IP is accessible, you should be able to access its http endpoint with curl on port 80:
 
 ```sh
-curl http://$(kubectl get pod nginx -o=template -t={{.status.podIP}})
+$ curl http://$(kubectl get pod nginx -o=template -t={{.status.podIP}})
 ```
 
 Delete the pod by name:
 
 ```sh
-kubectl delete pod nginx
+$ kubectl delete pod nginx
 ```
 
 

diff --git a/docs/user-guide/walkthrough/k8s201.md b/docs/user-guide/walkthrough/k8s201.md
@@ -20,24 +20,28 @@ certainly want the docs that go with that version.</h1>
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
-# Kubernetes 201 - Labels, Replication Controllers, Services & Health Checking
+# Kubernetes 201 - Labels, Replication Controllers, Services and Health Checking
 
 If you went through [Kubernetes 101](README.md), you learned about kubectl, pods, volumes, and multiple containers.
 For Kubernetes 201, we will pick up where 101 left off and cover some slightly more advanced topics in Kubernetes, related to application productionization, deployment and
 scaling.
 
 In order for the kubectl usage examples to work, make sure you have an examples directory locally, either from [a release](https://github.com/GoogleCloudPlatform/kubernetes/releases) or [the source](https://github.com/GoogleCloudPlatform/kubernetes).
 
-Table of Contents
-- [Labels](#labels)
-- [Replication Controllers](#replication-controllers)
-  - [Replication Controller Management](#replication-controller-management)
-- [Services](#services)
-  - [Service Management](#service-management)
-- [Health Checking](#health-checking)
-  - [Process Health Checking](#process-health-checking)
-  - [Application Health Checking](#application-health-checking)
-- [What's Next?](#whats-next)
+**Table of Contents**
+<!-- BEGIN MUNGE: GENERATED_TOC -->
+- [Kubernetes 201 - Labels, Replication Controllers, Services and Health Checking](#kubernetes-201---labels,-replication-controllers,-services-and-health-checking)
+  - [Labels](#labels)
+  - [Replication Controllers](#replication-controllers)
+      - [Replication Controller Management](#replication-controller-management)
+  - [Services](#services)
+      - [Service Management](#service-management)
+  - [Health Checking](#health-checking)
+      - [Process Health Checking](#process-health-checking)
+      - [Application Health Checking](#application-health-checking)
+  - [What's Next?](#whats-next)
+
+<!-- END MUNGE: GENERATED_TOC -->
 
 
 ## Labels
@@ -71,13 +75,13 @@ spec:
 Create the labeled pod ([pod-nginx-with-label.yaml](pod-nginx-with-label.yaml)):
 
 ```sh
-kubectl create -f docs/user-guide/walkthrough/pod-nginx-with-label.yaml
+$ kubectl create -f docs/user-guide/walkthrough/pod-nginx-with-label.yaml
 ```
 
 List all pods with the label `app=nginx`:
 
 ```sh
-kubectl get pods -l app=nginx
+$ kubectl get pods -l app=nginx
 ```
 
 For more information, see [Labels](../labels.md).
@@ -124,19 +128,19 @@ spec:
 Create an nginx replication controller ([replication-controller.yaml](replication-controller.yaml)):
 
 ```sh
-kubectl create -f docs/user-guide/walkthrough/replication-controller.yaml
+$ kubectl create -f docs/user-guide/walkthrough/replication-controller.yaml
 ```
 
 List all replication controllers:
 
 ```sh
-kubectl get rc
+$ kubectl get rc
 ```
 
 Delete the replication controller by name:
 
 ```sh
-kubectl delete rc nginx-controller
+$ kubectl delete rc nginx-controller
 ```
 
 For more information, see [Replication Controllers](../replication-controller.md).
@@ -172,29 +176,29 @@ spec:
 Create an nginx service ([service.yaml](service.yaml)):
 
 ```sh
-kubectl create -f docs/user-guide/walkthrough/service.yaml
+$ kubectl create -f docs/user-guide/walkthrough/service.yaml
 ```
 
 List all services:
 
 ```sh
-kubectl get services
+$ kubectl get services
 ```
 
 On most providers, the service IPs are not externally accessible. The easiest way to test that the service is working is to create a busybox pod and exec commands on it remotely. See the [command execution documentation](../kubectl/kubectl_exec.md) for details.
 
 Provided the service IP is accessible, you should be able to access its http endpoint with curl on port 80:
 
 ```sh
-SERVICE_IP=$(kubectl get service nginx-service -o=template -t={{.spec.clusterIP}})
-SERVICE_PORT=$(kubectl get service nginx-service -o=template '-t={{(index .spec.ports 0).port}}')
-curl http://${SERVICE_IP}:${SERVICE_PORT}
+$ export SERVICE_IP=$(kubectl get service nginx-service -o=template -t={{.spec.clusterIP}})
+$ export SERVICE_PORT=$(kubectl get service nginx-service -o=template '-t={{(index .spec.ports 0).port}}')
+$ curl http://${SERVICE_IP}:${SERVICE_PORT}
 ```
 
 To delete the service by name:
 
 ```sh
-kubectl delete service nginx-controller
+$ kubectl delete service nginx-controller
 ```
 
 When created, each service is assigned a unique IP address.  This address is tied to the lifespan of the Service, and will not change while the Service is alive.  Pods can be configured to talk to the service, and know that communication to the service will be automatically load-balanced out to some pod that is a member of the set identified by the label selector in the Service.