Merge pull request #1299 from Gurpartap/guestbook-go

Rewrite of the Guestbook example in Go
This commit is contained in:
Brendan Burns 2014-09-23 13:34:15 -07:00
commit 9c8ba8495d
18 changed files with 677 additions and 0 deletions

View File

@ -0,0 +1,174 @@
## GuestBook example
This example shows how to build a simple multi-tier web application using Kubernetes and Docker.
The example combines a web frontend, a redis master for storage and a replicated set of redis slaves.
### Step Zero: Prerequisites
This example assumes that you have forked the repository and [turned up a Kubernetes cluster](https://github.com/GoogleCloudPlatform/kubernetes#contents):
```shell
$ cd kubernetes
$ hack/dev-build-and-up.sh
```
### Step One: Turn up the redis master.
Use the file `examples/guestbook-go/redis-master-pod.json` which describes a single pod running a redis key-value server in a container.
Create the redis pod in your Kubernetes cluster using the `kubecfg` CLI:
```shell
$ cluster/kubecfg.sh -c examples/guestbook-go/redis-master-pod.json create pods
```
Once that's up you can list the pods in the cluster, to verify that the master is running:
```shell
$ cluster/kubecfg.sh list pods
```
You'll see a single redis master pod. It will also display the machine that the pod is running on once it gets placed (may take up to thirty seconds).
```
ID Image(s) Host Labels Status
---------- ---------- ---------- ---------- ----------
redis-master-pod gurpartap/redis kubernetes-minion-3.c.briandpe-api.internal name=redis,role=master Running
```
If you ssh to that machine, you can run `docker ps` to see the actual pod:
```shell
$ gcutil ssh --zone us-central1-b kubernetes-minion-3
$ sudo docker ps
me@kubernetes-minion-3:~$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS
e443647cd064 gurpartap/redis:latest redis-server /etc/r 22 minutes ago Up 22 minutes
```
(Note that initial `docker pull` may take a few minutes, depending on network conditions.)
### 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.
The pod that you created in Step One has the label `name=redis` and `role=master`. The selector field of the service determines which pods will receive the traffic sent to the service. Use the file `examples/guestbook-go/redis-master-service.json`
To create the service with the `kubecfg` cli:
```shell
$ cluster/kubecfg.sh -c examples/guestbook-go/redis-master-service.json create services
ID Labels Selector Port
---------- ---------- ---------- ----------
redis-master name=redis,role=master 6379
```
This will cause all pods to see the redis master apparently running on localhost:6379.
Once created, the service proxy on each minion is configured to set up a proxy on the specified port (in this case port 6379).
### Step Three: Turn up the replicated slave pods.
Although the redis master is a single pod, the redis read slaves are a 'replicated' pod. In Kubernetes, a replication controller is responsible for managing multiple instances of a replicated pod.
Use the file `examples/guestbook-go/redis-slave-controller.json`
to create the replication controller by running:
```shell
$ cluster/kubecfg.sh -c examples/guestbook-go/redis-slave-controller.json create replicationControllers
ID Image(s) Selector Replicas
---------- ---------- ---------- ----------
redis-slave-controller gurpartap/redis name=redis,role=slave 2
```
The redis slave configures itself by looking for the Kubernetes service environment variables in the container environment. In particular, the redis slave is started with the following command:
```shell
redis-server --slaveof $SERVICE_HOST $REDIS_MASTER_SERVICE_PORT
```
Once that's up you can list the pods in the cluster, to verify that the master and slaves are running:
```shell
$ cluster/kubecfg.sh list pods
ID Image(s) Host Labels Status
---------- ---------- ---------- ---------- ----------
redis-master-pod gurpartap/redis kubernetes-minion-3.c.briandpe-api.internal name=redis,role=master Running
4d65822107fcfd52 gurpartap/redis kubernetes-minion-3.c.briandpe-api.internal name=redis,role=slave,replicationController=redis-slave-controller Running
78629a0f5f3f164f gurpartap/redis kubernetes-minion-4.c.briandpe-api.internal name=redis,role=slave,replicationController=redis-slave-controller Running
```
You will see a single redis master pod 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 slave service provides transparent load balancing to clients. The service specification for the slaves is in `examples/guestbook-go/redis-slave-service.json`
This time the selector for the service is `name=redis,role=slave`, because that identifies the pods running redis slaves. It may also be helpful to set labels on your service itself--as we've done here--to make it easy to locate them with the `kubecfg -l "label=value" list services` command.
Now that you have created the service specification, create it in your cluster with the `kubecfg` CLI:
```shell
$ cluster/kubecfg.sh -c examples/guestbook-go/redis-slave-service.json create services
ID Labels Selector Port
---------- ---------- ---------- ----------
redis-slave name=redis-slave name=redis,role=slave 6379
```
### Step Five: Create the guestbook pod.
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. It exposes a simple JSON interface, and serves a jQuery-Ajax based UX. Like the redis read slaves it is a replicated service instantiated by a replication controller.
The pod is described in the file `examples/guestbook-go/guestbook-controller.json`:
Using this file, you can turn up your guestbook with:
```shell
$ cluster/kubecfg.sh -c examples/guestbook-go/guestbook-controller.json create replicationControllers
ID Image(s) Selector Replicas
---------- ---------- ---------- ----------
guestbook-controller gurpartap/redis name=guestbook 3
```
Once that's up (it may take ten to thirty seconds to create the pods) you can list the pods in the cluster, to verify that the master, slaves and guestbook frontends are running:
```shell
$ cluster/kubecfg.sh list pods
ID Image(s) Host Labels Status
---------- ---------- ---------- ---------- ----------
redis-master-pod gurpartap/redis kubernetes-minion-3.c.briandpe-api.internal name=redis,role=master Running
4d65822107fcfd52 gurpartap/redis kubernetes-minion-3.c.briandpe-api.internal name=redis,role=slave,replicationController=redis-slave-controller Running
380704bb7b4d7c03 kubernetes/guestbook kubernetes-minion-3.c.briandpe-api.internal name=guestbook,replicationController=guestbook-controller Running
55104dc76695721d kubernetes/guestbook kubernetes-minion-2.c.briandpe-api.internal name=guestbook,replicationController=guestbook-controller Running
365a858149c6e2d1 kubernetes/guestbook kubernetes-minion-1.c.briandpe-api.internal name=guestbook,replicationController=guestbook-controller Running
78629a0f5f3f164f gurpartap/redis kubernetes-minion-4.c.briandpe-api.internal name=redis,role=slave,replicationController=redis-slave-controller Running
```
You will see a single redis master pod, two redis slaves, and three guestbook pods.
To play with the service itself, find the name of a guestbook, grab the external IP of that host from the [Google Cloud Console][cloud-console] or the `gcutil` tool, and visit `http://<host-ip>:3000`.
```shell
$ gcutil listinstances
```
You may need to open the firewall for port 3000 using the [console][cloud-console] or the `gcutil` tool. The following command will allow traffic from any source to instances tagged `kubernetes-minion`:
```shell
$ gcutil addfirewall --allowed=tcp:3000 --target_tags=kubernetes-minion kubernetes-minion-3000
```
If you are running Kubernetes locally, you can just visit http://localhost:3000
For details about limiting traffic to specific sources, see the [gcutil documentation][gcutil-docs]
[cloud-console]: https://console.developer.google.com
[gcutil-docs]: https://developers.google.com/compute/docs/gcutil/reference/firewall#addfirewall
### Step Six: Cleanup
To turn down a Kubernetes cluster:
```shell
$ cluster/kube-down.sh
```

View File

@ -0,0 +1,9 @@
FROM google/golang:latest
RUN mkdir -p /gopath/src/github.com/GoogleCloudPlatform/ && cd /gopath/src/github.com/GoogleCloudPlatform/ && \
git clone http://github.com/GoogleCloudPlatform/kubernetes && \
cd /gopath/src/github.com/GoogleCloudPlatform/kubernetes/examples/guestbook-go/src/ && \
go get && go build -o ../bin/guestbook && \
cp ./guestbook/Dockerfile /gopath/src/github.com/GoogleCloudPlatform/kubernetes/examples/guestbook-go/
CMD docker build --rm --force-rm -t kubernetes/guestbook /gopath/src/github.com/GoogleCloudPlatform/kubernetes/examples/guestbook-go/

View File

@ -0,0 +1,42 @@
## Building and releasing Guestbook Image
Guestbook build process employs the usage of docker-in-docker to build an image within another. This requires that the build image has access to the `docker` program's binary, which defaults to the docker available on your host machine. In the case of boot2docker, `DOCKER_BIN` must be set to the binary's location in the boot2docker's vm.
Releasing the image requires that you have access to the docker registry user account which will host the image.
To build and release the guestbook image:
cd examples/guestbook-go/src
./script/release.sh
If you're using boot2docker, specify the `DOCKER_BIN` environment variable
DOCKER_BIN="$(boot2docker ssh which docker)" ./script/release.sh
#### Step by step
If you may want to, you can build and push the image step by step.
###### Start fresh before building
./script/clean.sh 2> /dev/null
###### Build
Builds a docker image that builds the app and packages it into a minimal docker image
./script/build.sh
If you're using boot2docker, specify the `DOCKER_BIN` environment variable
DOCKER_BIN="$(boot2docker ssh which docker)" ./script/build.sh
###### Push
Accepts an optional tag (defaults to "latest")
./script/push.sh [TAG]
###### Clean up
./script/clean.sh

View File

@ -0,0 +1,10 @@
FROM busybox:ubuntu-14.04
ADD ./bin/guestbook /app/guestbook
ADD ./src/public/index.html /app/public/index.html
ADD ./src/public/script.js /app/public/script.js
ADD ./src/public/style.css /app/public/style.css
WORKDIR /app
CMD ["./guestbook"]
EXPOSE 3000

View File

@ -0,0 +1,86 @@
/*
Copyright 2014 Google Inc. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package main
import (
"encoding/json"
"net/http"
"os"
"strings"
"github.com/codegangsta/negroni"
"github.com/gorilla/mux"
"github.com/xyproto/simpleredis"
)
var pool *simpleredis.ConnectionPool
func ListRangeHandler(rw http.ResponseWriter, req *http.Request) {
key := mux.Vars(req)["key"]
list := simpleredis.NewList(pool, key)
members := HandleError(list.GetAll()).([]string)
membersJSON := HandleError(json.MarshalIndent(members, "", " ")).([]byte)
rw.Write(membersJSON)
}
func ListPushHandler(rw http.ResponseWriter, req *http.Request) {
key := mux.Vars(req)["key"]
value := mux.Vars(req)["value"]
list := simpleredis.NewList(pool, key)
HandleError(nil, list.Add(value))
ListRangeHandler(rw, req)
}
func InfoHandler(rw http.ResponseWriter, req *http.Request) {
info := HandleError(pool.Get(0).Do("INFO")).([]byte)
rw.Write(info)
}
func EnvHandler(rw http.ResponseWriter, req *http.Request) {
environment := make(map[string]string)
for _, item := range os.Environ() {
splits := strings.Split(item, "=")
key := splits[0]
val := strings.Join(splits[1:], "=")
environment[key] = val
}
envJSON := HandleError(json.MarshalIndent(environment, "", " ")).([]byte)
rw.Write(envJSON)
}
func HandleError(result interface{}, err error) (r interface{}) {
if err != nil {
panic(err)
}
return result
}
func main() {
pool = simpleredis.NewConnectionPoolHost(os.Getenv("SERVICE_HOST") + ":" + os.Getenv("REDIS_MASTER_SERVICE_PORT"))
defer pool.Close()
r := mux.NewRouter()
r.Path("/lrange/{key}").Methods("GET").HandlerFunc(ListRangeHandler)
r.Path("/rpush/{key}/{value}").Methods("GET").HandlerFunc(ListPushHandler)
r.Path("/info").Methods("GET").HandlerFunc(InfoHandler)
r.Path("/env").Methods("GET").HandlerFunc(EnvHandler)
n := negroni.Classic()
n.UseHandler(r)
n.Run(":3000")
}

View File

@ -0,0 +1,34 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta charset="utf-8">
<meta content="width=device-width" name="viewport">
<link href="/style.css" rel="stylesheet">
<title>Guestbook</title>
</head>
<body>
<div id="header">
<h1>Guestbook</h1>
</div>
<div id="guestbook-entries">
<p>Waiting for database connection...</p>
</div>
<div>
<form id="guestbook-form">
<input autocomplete="off" id="guestbook-entry-content" type="text">
<a href="#" id="guestbook-submit">Submit</a>
</form>
</div>
<div>
<p><h2 id="guestbook-host-address"></h2></p>
<p><a href="/env">/env</a>
<a href="/info">/info</a></p>
</div>
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<script src="/script.js"></script>
</body>
</html>

View File

@ -0,0 +1,46 @@
$(document).ready(function() {
var headerTitleElement = $("#header h1");
var entriesElement = $("#guestbook-entries");
var formElement = $("#guestbook-form");
var submitElement = $("#guestbook-submit");
var entryContentElement = $("#guestbook-entry-content");
var hostAddressElement = $("#guestbook-host-address");
var appendGuestbookEntries = function(data) {
entriesElement.empty();
$.each(data, function(key, val) {
entriesElement.append("<p>" + val + "</p>");
});
}
var handleSubmission = function(e) {
e.preventDefault();
var entryValue = entryContentElement.val()
if (entryValue.length > 0) {
entriesElement.append("<p>...</p>");
$.getJSON("rpush/guestbook/" + entryValue, appendGuestbookEntries);
}
return false;
}
// colors = purple, blue, red, green, yellow
var colors = ["#549", "#18d", "#d31", "#2a4", "#db1"];
var randomColor = colors[Math.floor(5 * Math.random())];
(function setElementsColor(color) {
headerTitleElement.css("color", color);
entryContentElement.css("box-shadow", "inset 0 0 0 2px " + color);
submitElement.css("background-color", color);
})(randomColor);
submitElement.click(handleSubmission);
formElement.submit(handleSubmission);
hostAddressElement.append(document.URL);
// Poll every second.
(function fetchGuestbook() {
$.getJSON("lrange/guestbook").done(appendGuestbookEntries).always(
function() {
setTimeout(fetchGuestbook, 1000);
});
})();
});

View File

@ -0,0 +1,61 @@
body, input {
color: #123;
font-family: "Gill Sans", sans-serif;
}
div {
overflow: hidden;
padding: 1em 0;
position: relative;
text-align: center;
}
h1, h2, p, input, a {
font-weight: 300;
margin: 0;
}
h1 {
color: #BDB76B;
font-size: 3.5em;
}
h2 {
color: #999;
}
form {
margin: 0 auto;
max-width: 50em;
text-align: center;
}
input {
border: 0;
border-radius: 1000px;
box-shadow: inset 0 0 0 2px #BDB76B;
display: inline;
font-size: 1.5em;
margin-bottom: 1em;
outline: none;
padding: .5em 5%;
width: 55%;
}
form a {
background: #BDB76B;
border: 0;
border-radius: 1000px;
color: #FFF;
font-size: 1.25em;
font-weight: 400;
padding: .75em 2em;
text-decoration: none;
text-transform: uppercase;
white-space: normal;
}
p {
font-size: 1.5em;
line-height: 1.5;
}

View File

@ -0,0 +1,35 @@
#!/bin/bash
# Copyright 2014 Google Inc. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# Usage: ./script/build.sh
set -o errexit
set -o nounset
set -o pipefail
if [[ "${DOCKER_BIN+set}" == "set" ]]; then
echo "Using DOCKER_BIN=\"${DOCKER_BIN}\" from the environment."
elif DOCKER_BIN=$(which docker); then
echo "Setting DOCKER_BIN=\"${DOCKER_BIN}\" from host machine."
else
echo "Could not find a working docker binary and none passed in DOCKER_BIN." >&2
exit 1
fi
docker build --rm --force-rm -t kubernetes/guestbook-build .
docker run --rm -v "${DOCKER_BIN}:/usr/local/bin/docker" \
-v "/var/run/docker.sock:/var/run/docker.sock" \
-ti --name guestbook-build kubernetes/guestbook-build

View File

@ -0,0 +1,25 @@
#!/bin/bash
# Copyright 2014 Google Inc. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# Usage: ./script/clean.sh
set -o errexit
set -o nounset
set -o pipefail
docker rm -f guestbook-build 2> /dev/null || true
docker rmi -f kubernetes/guestbook-build || true
docker rmi -f kubernetes/guestbook || true

View File

@ -0,0 +1,24 @@
#!/bin/bash
# Copyright 2014 Google Inc. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# Usage: ./script/push.sh [TAG]
set -o errexit
set -o nounset
set -o pipefail
guestbook_version=${1:-latest}
docker push "kubernetes/guestbook:${guestbook_version}"

View File

@ -0,0 +1,40 @@
#!/bin/bash
# Copyright 2014 Google Inc. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# Usage: ./script/release.sh [TAG]
set -o errexit
set -o nounset
set -o pipefail
base_dir=$(dirname "$0")
base_dir=$(cd "${base_dir}" && pwd)
guestbook_version=${1:-latest}
echo " ---> Cleaning up before building..."
"${base_dir}/clean.sh" 2> /dev/null
echo " ---> Building..."
"${base_dir}/build.sh"
echo " ---> Pushing kubernetes/guestbook:${guestbook_version}..."
"${base_dir}/push.sh" "${guestbook_version}"
echo " ---> Cleaning up..."
"${base_dir}/clean.sh"
echo " ---> Done."

View File

@ -0,0 +1,24 @@
{
"apiVersion": "v1beta1",
"kind": "ReplicationController",
"id": "guestbook-controller",
"desiredState": {
"replicas": 3,
"replicaSelector": { "name": "guestbook" },
"podTemplate": {
"desiredState": {
"manifest": {
"version": "v1beta1",
"id": "guestbook-controller",
"containers": [{
"image": "kubernetes/guestbook",
"name": "guestbook",
"ports": [{ "name": "http-server", "containerPort": 3000 }]
}],
}
},
"labels": { "name": "guestbook" }
},
},
"labels": { "name": "guestbook" }
}

View File

@ -0,0 +1,8 @@
{
"apiVersion": "v1beta1",
"kind": "Service",
"id": "guestbook",
"port": 3000,
"containerPort": "http-server",
"selector": { "name": "guestbook" }
}

View File

@ -0,0 +1,17 @@
{
"apiVersion": "v1beta1",
"kind": "Pod",
"id": "redis-master-pod",
"desiredState": {
"manifest": {
"version": "v1beta1",
"id": "redis-master-pod",
"containers": [{
"name": "redis-master",
"image": "gurpartap/redis",
"ports": [{ "name": "redis-server", "containerPort": 6379 }]
}]
}
},
"labels": { "name": "redis", "role": "master" }
}

View File

@ -0,0 +1,8 @@
{
"apiVersion": "v1beta1",
"kind": "Service",
"id": "redis-master",
"port": 6379,
"containerPort": "redis-server",
"selector": { "name": "redis", "role": "master" }
}

View File

@ -0,0 +1,25 @@
{
"apiVersion": "v1beta1",
"kind": "ReplicationController",
"id": "redis-slave-controller",
"desiredState": {
"replicas": 2,
"replicaSelector": { "name": "redis", "role": "slave" },
"podTemplate": {
"desiredState": {
"manifest": {
"version": "v1beta1",
"id": "redis-slave-controller",
"containers": [{
"name": "redis-slave",
"image": "gurpartap/redis",
"command": ["sh", "-c", "redis-server /etc/redis/redis.conf --slaveof $SERVICE_HOST $REDIS_MASTER_SERVICE_PORT"],
"ports": [{ "name": "redis-server", "containerPort": 6379 }]
}]
}
},
"labels": { "name": "redis", "role": "slave" }
}
},
"labels": { "name": "redis", "role": "slave" }
}

View File

@ -0,0 +1,9 @@
{
"apiVersion": "v1beta1",
"kind": "Service",
"id": "redis-slave",
"port": 6379,
"containerPort": "redis-server",
"labels": { "name": "redis", "role": "slave" },
"selector": { "name": "redis", "role": "slave" }
}