Merge pull request kubernetes#3594 from jayunit100/master

Clarify origin of REDIS_MASTER_SERVICE_HOST variable.
duda · Jan 20, 2015 · 1e36cb1 · 1e36cb1
2 parents 9a151fc + 2fc8c08
commit 1e36cb1
Showing 1 changed file with 6 additions and 3 deletions.
diff --git a/examples/guestbook/README.md b/examples/guestbook/README.md
@@ -6,7 +6,7 @@ The example combines a web frontend, a redis master for storage and a replicated
 
 ### Step Zero: Prerequisites
 
-This example assumes that you have forked the repository and [turned up a Kubernetes cluster](https://github.com/GoogleCloudPlatform/kubernetes#contents):
+This example assumes that have a basic understanding of kubernetes services and that you have forked the repository and [turned up a Kubernetes cluster](https://github.com/GoogleCloudPlatform/kubernetes#contents):
 
 ```shell
 $ cd kubernetes
@@ -72,10 +72,11 @@ CONTAINER ID  IMAGE                     COMMAND                CREATED         S
 e3eed3e5e6d1  dockerfile/redis:latest   "redis-server /etc/re  2 minutes ago   Up 2 minutes            k8s_master.9c0a9146_redis-master.etcd_6296f4bd-70fa-11e4-8469-0800279696e1_45331ebc
 ```
 
-(Note that initial `docker pull` may take a few minutes, depending on network conditions.)
+(Note that initial `docker pull` may take a few minutes, depending on network conditions.  During this time, the `get pods` command will return `Pending` because the container has not yet started )
 
 ### Step Two: Turn up the master service
-A Kubernetes 'service' is a named load balancer that proxies traffic to one or more containers. The services in a Kubernetes cluster are discoverable inside other containers via environment variables. Services find the containers to load balance based on pod labels.
+
+A Kubernetes 'service' is a named load balancer that proxies traffic to one or more containers. The services in a Kubernetes cluster are discoverable inside other containers via *environment variables*. Services find the containers to load balance based on pod labels.  These environment variables are typically referenced in application code, shell scripts, or other places where one node needs to talk to another in a distributed system.  You should catch up on [kubernetes services](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/services.md) before proceeding.
 
 The pod that you created in Step One has the label `name=redis-master`. The selector field of the service determines which pods will receive the traffic sent to the service. Use the file `examples/guestbook/redis-master-service.json`:
 
@@ -165,6 +166,8 @@ The redis slave configures itself by looking for the Kubernetes service environm
 redis-server --slaveof ${REDIS_MASTER_SERVICE_HOST:-$SERVICE_HOST} $REDIS_MASTER_SERVICE_PORT
 ```
 
+You might be curious about where the *REDIS_MASTER_SERVICE_HOST* is coming from.  It is provided to this container when it is launched via the kubernetes services, which create environment variables (there is a well defined syntax for how service names get transformed to environment variable names in the documentation linked above).
+
 Once that's up you can list the pods in the cluster, to verify that the master and slaves are running:
 
 ```shell