guestbook-go/

directory
v1.1.0-alpha.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 11, 2015 License: Apache-2.0

README

Guestbook Example

This example shows how to build a simple multi-tier web application using Kubernetes and Docker. The application consists of a web front-end, Redis master for storage, and replicated set of Redis slaves, all for which we will create Kubernetes replication controllers, pods, and services.

If you are running a cluster in Google Container Engine (GKE), instead see the Guestbook Example for Google Container Engine.

Table of Contents
  • [Step Zero: Prerequisites](<#step-zero)
  • [Step One: Create the Redis master pod](<#step-one)
  • [Step Two: Create the Redis master service](<#step-two)
  • [Step Three: Create the Redis slave pods](<#step-three)
  • [Step Four: Create the Redis slave service](<#step-four)
  • [Step Five: Create the guestbook pods](<#step-five)
  • [Step Six: Create the guestbook service](<#step-six)
  • [Step Seven: View the guestbook](<#step-seven)
  • Step Eight: Cleanup

Step Zero: Prerequisites

This example assumes that you have a working cluster. See the Getting Started Guides for details about creating a cluster.

Tip: View all the kubectl commands, including their options and descriptions in the kudectl CLI reference.

Step One: Create the Redis master pod

Use the examples/guestbook-go/redis-master-controller.json file to create a replication controller and Redis master pod. The pod runs a Redis key-value server in a container. Using a replication controller is the preferred way to launch long-running pods, even for 1 replica, so that the pod benefits from the self-healing mechanism in Kubernetes (keeps the pods alive).

  1. Use the examples/guestbook-go/redis-master-controller.json file to create the Redis master replication controller in your Kubernetes cluster by running the kubectl create -f filename command:

    $ kubectl create -f examples/guestbook-go/redis-master-controller.json
    replicationcontrollers/redis-master
    
  2. To verify that the redis-master-controller is up, list all the replication controllers in the cluster with the kubectl get rc command:

    $ kubectl get rc
    CONTROLLER             CONTAINER(S)            IMAGE(S)                    SELECTOR                         REPLICAS
    redis-master           redis-master            gurpartap/redis             app=redis,role=master            1
    ...
    

    Result: The replication controller then creates the single Redis master pod.

  3. To verify that the redis-master pod is running, list all the pods in cluster with the kubectl get pods command:

    $ kubectl get pods
    NAME                        READY     STATUS    RESTARTS   AGE
    redis-master-xx4uv          1/1       Running   0          1m
    ...
    

    Result: You'll see a single Redis master pod and the machine where the pod is running after the pod gets placed (may take up to thirty seconds).

  4. To verify what containers are running in the redis-master pod, you can SSH to that machine with gcloud comput ssh --zone zone_name host_name and then run docker ps:

    me@workstation$ gcloud compute ssh --zone us-central1-b kubernetes-minion-bz1p
    
    me@kubernetes-minion-3:~$ sudo docker ps
    CONTAINER ID        IMAGE                      COMMAND                CREATED             STATUS
    d5c458dabe50        gurpartap/redis:latest     "/usr/local/bin/redi   5 minutes ago       Up 5 minutes
    

    Note: The initial docker pull can take a few minutes, depending on network conditions.

Step Two: Create the Redis 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 or DNS.

Services find the containers to load balance based on pod labels. The pod that you created in Step One has the label app=redis and role=master. The selector field of the service determines which pods will receive the traffic sent to the service.

  1. Use the examples/guestbook-go/redis-master-service.json file to create the service in your Kubernetes cluster by running the kubectl create -f filename command:

    $ kubectl create -f examples/guestbook-go/redis-master-service.json
    services/redis-master
    
  2. To verify that the redis-master service is up, list all the services in the cluster with the kubectl get services command:

    $ kubectl get services
    NAME               LABELS                    SELECTOR                     IP(S)          PORT(S)
    redis-master       app=redis,role=master     app=redis,role=master        10.0.136.3     6379/TCP
    ...
    

    Result: All new pods will see the redis-master service running on the host ($REDIS_MASTER_SERVICE_HOST environment variable) at port 6379, or running on redis-master:6379. After the service is created, the service proxy on each node is configured to set up a proxy on the specified port (in our example, that's port 6379).

Step Three: Create the Redis slave pods

The Redis master we created earlier is a single pod (REPLICAS = 1), while the Redis read slaves we are creating here are 'replicated' pods. In Kubernetes, a replication controller is responsible for managing the multiple instances of a replicated pod.

  1. Use the file examples/guestbook-go/redis-slave-controller.json to create the replication controller by running the kubectl create -f filename command:

    $ kubectl create -f examples/guestbook-go/redis-slave-controller.json
    replicationcontrollers/redis-slave
    
  2. To verify that the guestbook replication controller is running, run the kubectl get rc command:

    $ kubectl get rc
    CONTROLLER              CONTAINER(S)            IMAGE(S)               SELECTOR                    REPLICAS
    redis-master            redis-master            gurpartap/redis        app=redis,role=master       1
    redis-slave             redis-slave             gurpartap/redis        app=redis,role=slave        2
    ...
    

    Result: The replication controller creates and configures the Redis slave pods through the redis-master service (name:port pair, in our example that's redis-master:6379).

    Example: The Redis slaves get started by the replication controller with the following command:

    redis-server --slaveof redis-master 6379
    
  3. To verify that the Redis master and slaves pods are running, run the kubectl get pods command:

    $ kubectl get pods
    NAME                          READY     STATUS    RESTARTS   AGE
    redis-master-xx4uv            1/1       Running   0          18m
    redis-slave-b6wj4             1/1       Running   0          1m
    redis-slave-iai40             1/1       Running   0          1m
    ...
    

    Result: You see the single Redis master and two Redis slave pods.

Step Four: Create the Redis slave service

Just like the master, we want to have a service to proxy connections to the read slaves. In this case, in addition to discovery, the Redis slave service provides transparent load balancing to clients.

  1. Use the examples/guestbook-go/redis-slave-service.json file to create the Redis slave service by running the kubectl create -f filename command:

    $ kubectl create -f examples/guestbook-go/redis-slave-service.json
    services/redis-slave
    
  2. To verify that the redis-slave service is up, list all the services in the cluster with the kubectl get services command:

    $ kubectl get services
    NAME               LABELS                    SELECTOR                        IP(S)          PORT(S)
    redis-master       app=redis,role=master     app=redis,role=master           10.0.136.3     6379/TCP
    redis-slave        app=redis,role=slave      app=redis,role=slave            10.0.21.92     6379/TCP
    ...
    

    Result: The service is created with labels app=redis and role=slave to identify that the pods are running the Redis slaves.

Tip: It is helpful to set labels on your services themselves--as we've done here--to make it easy to locate them later.

Step Five: Create the guestbook pods

This is a simple Go net/http (negroni based) server that is configured to talk to either the slave or master services depending on whether the request is a read or a write. The pods we are creating expose a simple JSON interface and serves a jQuery-Ajax based UI. Like the Redis read slaves, these pods are also managed by a replication controller.

  1. Use the examples/guestbook-go/guestbook-controller.json file to create the guestbook replication controller by running the kubectl create -f filename command:

    $ kubectl create -f examples/guestbook-go/guestbook-controller.json
    replicationcontrollers/guestbook
    
  2. To verify that the guestbook replication controller is running, run the kubectl get rc command:

    $ kubectl get rc
    CONTROLLER            CONTAINER(S)         IMAGE(S)                    SELECTOR                  REPLICAS
    guestbook             guestbook            kubernetes/guestbook:v2     app=guestbook             3
    redis-master          redis-master         gurpartap/redis             app=redis,role=master     1
    redis-slave           redis-slave          gurpartap/redis             app=redis,role=slave      2
    ...
    
  3. To verify that the guestbook pods are running (it might take up to thirty seconds to create the pods), list all the pods in cluster with the kubectl get pods command:

    $ kubectl get pods
    NAME                           READY     STATUS    RESTARTS   AGE
    guestbook-3crgn                1/1       Running   0          2m
    guestbook-gv7i6                1/1       Running   0          2m
    guestbook-x405a                1/1       Running   0          2m
    redis-master-xx4uv             1/1       Running   0          23m
    redis-slave-b6wj4              1/1       Running   0          6m
    redis-slave-iai40              1/1       Running   0          6m
    ... 
    

    Result: You see a single Redis master, two Redis slaves, and three guestbook pods.

Step Six: Create the guestbook service

Just like the others, we create a service to group the guestbook pods but this time, to make the guestbook front-end externally visible, we specify "type": "LoadBalancer".

  1. Use the examples/guestbook-go/guestbook-service.json file to create the guestbook service by running the kubectl create -f filename command:

    $ kubectl create -f examples/guestbook-go/guestbook-service.json
    	  An external load-balanced service was created.  On many platforms (e.g. Google Compute Engine),
          you will also need to explicitly open a Firewall rule for the service port(s) (tcp:3000) to serve traffic.
          See https://github.com/GoogleCloudPlatform/kubernetes/tree/master/docs/services-firewall.md for more details.
    
  2. To verify that the guestbook service is up, list all the services in the cluster with the kubectl get services command:

    $ kubectl get services
    NAME             LABELS                     SELECTOR                        IP(S)          PORT(S)
    guestbook        app=guestbook              app=guestbook                   10.0.217.218   3000/TCP
                                                                                146.148.81.8   
    redis-master     app=redis,role=master      app=redis,role=master           10.0.136.3     6379/TCP
    redis-slave      app=redis,role=slave       app=redis,role=slave            10.0.21.92     6379/TCP
    ...
    

    Result: The service is created with label app=guestbook.

Step Seven: View the guestbook

You can now play with the guestbook that you just created by opening it in a browser (it might take a few moments for the guestbook to come up).

  • Local Host: If you are running Kubernetes locally, to view the guestbook, navigate to http://localhost:3000 in your browser.

  • Remote Host:

    1. To view the guestbook on a remote host, locate the external IP of the load balancer in the IP column of the kubectl get services output. In our example, the internal IP address is 10.0.217.218 and the external IP address is 146.148.81.8 (Note: you might need to scroll to see the IP column).

    2. Append port 3000 to the IP address (for example http://146.148.81.8:3000), and then navigate to that address in your browser.

    Remember: You might need to open the firewall for port 3000. If you're using Google Compute Engine, you can use the Developers Console or the gcloud CLI to open port 3000.

    To use the gcloud CLI, you can run the following command to allow traffic from any source to instances tagged kubernetes-minion:

    $ gcloud compute firewall-rules create --allow=tcp:3000 --target-tags=kubernetes-minion kubernetes-minion-3000
    

    Result: The guestbook displays in your browser:

    Guestbook

    Further Reading: If you're using Google Compute Engine, see the details about limiting traffic to specific sources at Google Compute Engine firewall documentation.

Step Eight: Cleanup

After you're done playing with the guestbook, you can cleanup by deleting the guestbook service and removing the associated resources that were created, including load balancers, forwarding rules, target pools, and Kuberentes replication controllers and services.

Delete all the resources by running the following kubectl delete -f filename command:

$ kubectl delete -f examples/guestbook-go
guestbook-controller
guestbook
redid-master-controller
redis-master
redis-slave-controller
redis-slave

Tip: To turn down your Kubernetes cluster, follow the corresponding instructions in the version of the Getting Started Guides that you previously used to create your cluster.

Analytics

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL