github.com/qsunny/k8s@v0.0.0-20220101153623-e6dca256d5bf/examples-master/guestbook-go/README.md (about) 1 ## Guestbook Example 2 3 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. 4 5 If you are running a cluster in Google Container Engine (GKE), instead see the [Guestbook Example for Google Container Engine](https://cloud.google.com/container-engine/docs/tutorials/guestbook). 6 7 ##### Table of Contents 8 9 * [Step Zero: Prerequisites](#step-zero) 10 * [Step One: Create the Redis master pod](#step-one) 11 * [Step Two: Create the Redis master service](#step-two) 12 * [Step Three: Create the Redis slave pods](#step-three) 13 * [Step Four: Create the Redis slave service](#step-four) 14 * [Step Five: Create the guestbook pods](#step-five) 15 * [Step Six: Create the guestbook service](#step-six) 16 * [Step Seven: View the guestbook](#step-seven) 17 * [Step Eight: Cleanup](#step-eight) 18 19 ### Step Zero: Prerequisites <a id="step-zero"></a> 20 21 This example assumes that you have a working cluster. See the [Getting Started Guides](https://kubernetes.io/docs/setup/) for details about creating a cluster. 22 23 **Tip:** View all the `kubectl` commands, including their options and descriptions in the [kubectl CLI reference](https://kubernetes.io/docs/user-guide/kubectl-overview/). 24 25 ### Step One: Create the Redis master pod<a id="step-one"></a> 26 27 Use the `examples/guestbook-go/redis-master-controller.json` file to create a [replication controller](https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/) and Redis master [pod](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/). 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). 28 29 1. Use the [redis-master-controller.json](redis-master-controller.json) file to create the Redis master replication controller in your Kubernetes cluster by running the `kubectl create -f` *`filename`* command: 30 31 ```console 32 $ kubectl create -f examples/guestbook-go/redis-master-controller.json 33 34 ``` 35 36 2. To verify that the redis-master controller is up, list the replication controllers you created in the cluster with the `kubectl get rc` command(if you don't specify a `--namespace`, the `default` namespace will be used. The same below): 37 38 ```console 39 $ kubectl get rc 40 CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS 41 redis-master redis-master gurpartap/redis app=redis,role=master 1 42 ... 43 ``` 44 45 Result: The replication controller then creates the single Redis master pod. 46 47 3. To verify that the redis-master pod is running, list the pods you created in cluster with the `kubectl get pods` command: 48 49 ```console 50 $ kubectl get pods 51 NAME READY STATUS RESTARTS AGE 52 redis-master-xx4uv 1/1 Running 0 1m 53 ... 54 ``` 55 56 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). 57 58 4. To verify what containers are running in the redis-master pod, you can SSH to that machine with `gcloud compute ssh --zone` *`zone_name`* *`host_name`* and then run `docker ps`: 59 60 ```console 61 me@workstation$ gcloud compute ssh --zone us-central1-b kubernetes-node-bz1p 62 63 me@kubernetes-node-3:~$ sudo docker ps 64 CONTAINER ID IMAGE COMMAND CREATED STATUS 65 d5c458dabe50 redis "/entrypoint.sh redis" 5 minutes ago Up 5 minutes 66 ``` 67 68 Note: The initial `docker pull` can take a few minutes, depending on network conditions. 69 70 ### Step Two: Create the Redis master service <a id="step-two"></a> 71 72 A Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/) is a named load balancer that proxies traffic to one or more pods. The services in a Kubernetes cluster are discoverable inside other pods via environment variables or DNS. 73 74 Services find the pods 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. 75 76 1. Use the [redis-master-service.json](redis-master-service.json) file to create the service in your Kubernetes cluster by running the `kubectl create -f` *`filename`* command: 77 78 ```console 79 $ kubectl create -f examples/guestbook-go/redis-master-service.json 80 81 ``` 82 83 2. To verify that the redis-master service is up, list the services you created in the cluster with the `kubectl get services` command: 84 85 ```console 86 $ kubectl get services 87 NAME CLUSTER_IP EXTERNAL_IP PORT(S) SELECTOR AGE 88 redis-master 10.0.136.3 <none> 6379/TCP app=redis,role=master 1h 89 ... 90 ``` 91 92 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). 93 94 95 ### Step Three: Create the Redis slave pods <a id="step-three"></a> 96 97 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. 98 99 1. Use the file [redis-slave-controller.json](redis-slave-controller.json) to create the replication controller by running the `kubectl create -f` *`filename`* command: 100 101 ```console 102 $ kubectl create -f examples/guestbook-go/redis-slave-controller.json 103 104 ``` 105 106 2. To verify that the redis-slave controller is running, run the `kubectl get rc` command: 107 108 ```console 109 $ kubectl get rc 110 CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS 111 redis-master redis-master redis app=redis,role=master 1 112 redis-slave redis-slave k8s.gcr.io/redis-slave:v2 app=redis,role=slave 2 113 ... 114 ``` 115 116 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`). 117 118 Example: 119 The Redis slaves get started by the replication controller with the following command: 120 121 ```console 122 redis-server --slaveof redis-master 6379 123 ``` 124 125 3. To verify that the Redis master and slaves pods are running, run the `kubectl get pods` command: 126 127 ```console 128 $ kubectl get pods 129 NAME READY STATUS RESTARTS AGE 130 redis-master-xx4uv 1/1 Running 0 18m 131 redis-slave-b6wj4 1/1 Running 0 1m 132 redis-slave-iai40 1/1 Running 0 1m 133 ... 134 ``` 135 136 Result: You see the single Redis master and two Redis slave pods. 137 138 ### Step Four: Create the Redis slave service <a id="step-four"></a> 139 140 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. 141 142 1. Use the [redis-slave-service.json](redis-slave-service.json) file to create the Redis slave service by running the `kubectl create -f` *`filename`* command: 143 144 ```console 145 $ kubectl create -f examples/guestbook-go/redis-slave-service.json 146 147 ``` 148 149 2. To verify that the redis-slave service is up, list the services you created in the cluster with the `kubectl get services` command: 150 151 ```console 152 $ kubectl get services 153 NAME CLUSTER_IP EXTERNAL_IP PORT(S) SELECTOR AGE 154 redis-master 10.0.136.3 <none> 6379/TCP app=redis,role=master 1h 155 redis-slave 10.0.21.92 <none> 6379/TCP app-redis,role=slave 1h 156 ... 157 ``` 158 159 Result: The service is created with labels `app=redis` and `role=slave` to identify that the pods are running the Redis slaves. 160 161 Tip: It is helpful to set labels on your services themselves--as we've done here--to make it easy to locate them later. 162 163 ### Step Five: Create the guestbook pods <a id="step-five"></a> 164 165 This is a simple Go `net/http` ([negroni](https://github.com/codegangsta/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 slave pods, these pods are also managed by a replication controller. 166 167 1. Use the [guestbook-controller.json](guestbook-controller.json) file to create the guestbook replication controller by running the `kubectl create -f` *`filename`* command: 168 169 ```console 170 $ kubectl create -f examples/guestbook-go/guestbook-controller.json 171 172 ``` 173 174 Tip: If you want to modify the guestbook code open the `_src` of this example and read the README.md and the Makefile. If you have pushed your custom image be sure to update the `image` accordingly in the guestbook-controller.json. 175 176 2. To verify that the guestbook replication controller is running, run the `kubectl get rc` command: 177 178 ```console 179 $ kubectl get rc 180 CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS 181 guestbook guestbook k8s.gcr.io/guestbook:v3 app=guestbook 3 182 redis-master redis-master redis app=redis,role=master 1 183 redis-slave redis-slave k8s.gcr.io/redis-slave:v2 app=redis,role=slave 2 184 ... 185 ``` 186 187 3. To verify that the guestbook pods are running (it might take up to thirty seconds to create the pods), list the pods you created in cluster with the `kubectl get pods` command: 188 189 ```console 190 $ kubectl get pods 191 NAME READY STATUS RESTARTS AGE 192 guestbook-3crgn 1/1 Running 0 2m 193 guestbook-gv7i6 1/1 Running 0 2m 194 guestbook-x405a 1/1 Running 0 2m 195 redis-master-xx4uv 1/1 Running 0 23m 196 redis-slave-b6wj4 1/1 Running 0 6m 197 redis-slave-iai40 1/1 Running 0 6m 198 ... 199 ``` 200 201 Result: You see a single Redis master, two Redis slaves, and three guestbook pods. 202 203 ### Step Six: Create the guestbook service <a id="step-six"></a> 204 205 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"`. 206 207 1. Use the [guestbook-service.json](guestbook-service.json) file to create the guestbook service by running the `kubectl create -f` *`filename`* command: 208 209 ```console 210 $ kubectl create -f examples/guestbook-go/guestbook-service.json 211 ``` 212 213 214 2. To verify that the guestbook service is up, list the services you created in the cluster with the `kubectl get services` command: 215 216 ```console 217 $ kubectl get services 218 NAME CLUSTER_IP EXTERNAL_IP PORT(S) SELECTOR AGE 219 guestbook 10.0.217.218 146.148.81.8 3000/TCP app=guestbook 1h 220 redis-master 10.0.136.3 <none> 6379/TCP app=redis,role=master 1h 221 redis-slave 10.0.21.92 <none> 6379/TCP app-redis,role=slave 1h 222 ... 223 ``` 224 225 Result: The service is created with label `app=guestbook`. 226 227 ### Step Seven: View the guestbook <a id="step-seven"></a> 228 229 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). 230 231 * **Local Host:** 232 If you are running Kubernetes locally, to view the guestbook, navigate to `http://localhost:3000` in your browser. 233 234 * **Remote Host:** 235 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*). 236 237 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. 238 239 Result: The guestbook displays in your browser: 240 241  242 243 **Further Reading:** 244 If you're using Google Compute Engine, see the details about limiting traffic to specific sources at [Google Compute Engine firewall documentation][gce-firewall-docs]. 245 246 [cloud-console]: https://console.developer.google.com 247 [gce-firewall-docs]: https://cloud.google.com/compute/docs/networking#firewalls 248 249 ### Step Eight: Cleanup <a id="step-eight"></a> 250 251 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 Kubernetes replication controllers and services. 252 253 Delete all the resources by running the following `kubectl delete -f` *`filename`* command: 254 255 ```console 256 $ kubectl delete -f examples/guestbook-go 257 guestbook-controller 258 guestbook 259 redid-master-controller 260 redis-master 261 redis-slave-controller 262 redis-slave 263 ``` 264 265 Tip: To turn down your Kubernetes cluster, follow the corresponding instructions in the version of the 266 [Getting Started Guides](https://kubernetes.io/docs/getting-started-guides/) that you previously used to create your cluster. 267 268 269 <!-- BEGIN MUNGE: GENERATED_ANALYTICS --> 270 []() 271 <!-- END MUNGE: GENERATED_ANALYTICS -->