kubernetes
/
examples
mirror of https://github.com/kubernetes/examples.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Guestbook revisions + Minikube Default Frontend Service (#46) 

* Update frontend-service.yaml

* Update README.md

* Update README.md

* Edits for formatting

* Less cluttered formatting syntax

* fix typo

* [draft] adding more depth / concepts to tasks

* Update README.md

* Addressing Ahmet's comments

* Fixed formatting and links
This commit is contained in:
Cody Clark 2017-08-04 14:15:44 -07:00 committed by Ahmet Alp Balkan
parent fc184e0003
commit 00005dfb21
2 changed files with 219 additions and 619 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

836
guestbook/README.md
View File

@ -4,704 +4,302 @@
> https://kubernetes.io/docs/tutorials/stateless-application/guestbook/.
> Otherwise some of the URLs will not work properly.
## Guestbook Example
## Creating a Guestbook
<!-- EXCLUDE_FROM_DOCS END -->
This example shows how to build a simple, multi-tier web application using Kubernetes and [Docker](https://www.docker.com/).
{% capture overview %}
This tutorial shows you how to build and deploy a simple, multi-tier web application using Kubernetes and [Docker](https://www.docker.com/). This example consists of the following components:
**Table of Contents**
<!-- BEGIN MUNGE: GENERATED_TOC -->
* A single-instance [Redis](https://redis.io/) master to store guestbook entries
* Multiple replicated Redis instances to serve reads
* Multiple web frontend instances
- [Guestbook Example](#guestbook-example)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Step One: Start up the redis master](#step-one-start-up-the-redis-master)
- [Define a Deployment](#define-a-deployment)
- [Define a Service](#define-a-service)
- [Create a Service](#create-a-service)
- [Finding a Service](#finding-a-service)
- [Environment variables](#environment-variables)
- [DNS service](#dns-service)
- [Create a Deployment](#create-a-deployment)
- [Optional Interlude](#optional-interlude)
- [Step Two: Start up the redis slave](#step-two-start-up-the-redis-slave)
- [Step Three: Start up the guestbook frontend](#step-three-start-up-the-guestbook-frontend)
- [Using 'type: LoadBalancer' for the frontend service (cloud-provider-specific)](#using-type-loadbalancer-for-the-frontend-service-cloud-provider-specific)
- [Step Four: Cleanup](#step-four-cleanup)
- [Troubleshooting](#troubleshooting)
- [Appendix: Accessing the guestbook site externally](#appendix-accessing-the-guestbook-site-externally)
- [Google Compute Engine External Load Balancer Specifics](#google-compute-engine-external-load-balancer-specifics)
{% endcapture %}
<!-- END MUNGE: GENERATED_TOC -->
{% capture objectives %}
* Start up a Redis master.
* Start up Redis slaves.
* Start up the guestbook frontend.
* Expose and view the Frontend Service.
* Clean up.
{% endcapture %}
The example consists of:
{% capture prerequisites %}
- A web frontend
- A [redis](http://redis.io/) master (for storage), and a replicated set of redis 'slaves'.
{% include task-tutorial-prereqs.md %}
Download the following configuration files:
The web frontend interacts with the redis master via javascript redis API calls.
1. [redis-master-deployment.yaml](https://kubernetes.io/docs/tutorials/docs/tutorials/stateless-application/redis-master-deployment.yaml)
1. [redis-master-service.yaml](https://kubernetes.io/docs/tutorials/docs/tutorials/stateless-application/redis-master-service.yaml)
1. [redis-slave-deployment.yaml](https://kubernetes.io/docs/tutorials/docs/tutorials/stateless-application/redis-slave-deployment.yaml)
1. [redis-slave-service.yaml](https://kubernetes.io/docs/tutorials/docs/tutorials/stateless-application/redis-slave-service.yaml)
1. [frontend-deployment.yaml](https://kubernetes.io/docs/tutorials/docs/tutorials/stateless-application/frontend-deployment.yaml)
1. [frontend-service.yaml](https://kubernetes.io/docs/tutorials/docs/tutorials/stateless-application/frontend-service.yaml)
**Note**: If you are running this example on a [Google Container Engine](https://cloud.google.com/container-engine/) installation, see [this Google Container Engine guestbook walkthrough](https://cloud.google.com/container-engine/docs/tutorials/guestbook) instead. The basic concepts are the same, but the walkthrough is tailored to a Container Engine setup.
{% endcapture %}
### Prerequisites
{% capture lessoncontent %}
This example requires a running Kubernetes cluster. First, check that kubectl is properly configured by getting the cluster state:
```console
$ kubectl cluster-info
```
If you see a url response, you are ready to go. If not, read the [Getting Started guides](http://kubernetes.io/docs/getting-started-guides/) for how to get started, and follow the [prerequisites](http://kubernetes.io/docs/user-guide/prereqs/) to install and configure `kubectl`. As noted above, if you have a Google Container Engine cluster set up, read [this example](https://cloud.google.com/container-engine/docs/tutorials/guestbook) instead.
All the files referenced in this example can be downloaded [from GitHub](https://git.k8s.io/examples/guestbook).
### Quick Start
This section shows the simplest way to get the example work. If you want to know the details, you should skip this and read [the rest of the example](#step-one-start-up-the-redis-master).
Start the guestbook with one command:
```console
$ kubectl create -f guestbook/all-in-one/guestbook-all-in-one.yaml
service "redis-master" created
deployment "redis-master" created
service "redis-slave" created
deployment "redis-slave" created
service "frontend" created
deployment "frontend" created
```
## Start up the Redis Master
Alternatively, you can start the guestbook by running:
The guestbook application uses Redis to store its data. It writes its data to a Redis master instance and reads data from multiple Redis slave instances.
```console
$ kubectl create -f guestbook/
```
Then, list all your Services:
```console
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
frontend 10.0.0.117 <none> 80/TCP 20s
redis-master 10.0.0.170 <none> 6379/TCP 20s
redis-slave 10.0.0.201 <none> 6379/TCP 20s
```
Now you can access the guestbook on each node with frontend Service's `<Cluster-IP>:<PORT>`, e.g. `10.0.0.117:80` in this guide. `<Cluster-IP>` is a cluster-internal IP. If you want to access the guestbook from outside of the cluster, add `type: NodePort` to the frontend Service `spec` field. Then you can access the guestbook with `<NodeIP>:NodePort` from outside of the cluster. On cloud providers which support external load balancers, adding `type: LoadBalancer` to the frontend Service `spec` field will provision a load balancer for your Service. There are several ways for you to access the guestbook. You may learn from [Accessing services running on the cluster](https://kubernetes.io/docs/concepts/cluster-administration/access-cluster/#accessing-services-running-on-the-cluster).
Clean up the guestbook:
```console
$ kubectl delete -f guestbook/all-in-one/guestbook-all-in-one.yaml
```
or
```console
$ kubectl delete -f guestbook/
```
### Step One: Start up the redis master
Before continuing to the gory details, we also recommend you to read Kubernetes [concepts and user guide](http://kubernetes.io/docs/user-guide/).
**Note**: The redis master in this example is *not* highly available. Making it highly available would be an interesting, but intricate exercise — redis doesn't actually support multi-master Deployments at this point in time, so high availability would be a somewhat tricky thing to implement, and might involve periodic serialization to disk, and so on.
#### Define a Deployment
To start the redis master, use the file [redis-master-deployment.yaml](https://git.k8s.io/examples/guestbook/redis-master-deployment.yaml), which describes a single [pod](http://kubernetes.io/docs/user-guide/pods/) running a redis key-value server in a container.
Although we have a single instance of our redis master, we are using a [Deployment](http://kubernetes.io/docs/user-guide/deployments/) to enforce that exactly one pod keeps running. E.g., if the node were to go down, the Deployment will ensure that the redis master gets restarted on a healthy node. (In our simplified example, this could result in data loss.)
The file [redis-master-deployment.yaml](https://git.k8s.io/examples/guestbook/redis-master-deployment.yaml) defines the redis master Deployment:
<!-- BEGIN MUNGE: EXAMPLE redis-master-deployment.yaml -->
```yaml
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: redis-master
# these labels can be applied automatically
# from the labels in the pod template if not set
# labels:
# app: redis
# role: master
# tier: backend
spec:
# this replicas value is default
# modify it according to your case
replicas: 1
# selector can be applied automatically
# from the labels in the pod template if not set
# selector:
# matchLabels:
# app: guestbook
# role: master
# tier: backend
template:
metadata:
labels:
app: redis
role: master
tier: backend
spec:
containers:
- name: master
image: gcr.io/google_containers/redis:e2e
resources:
requests:
cpu: 100m
memory: 100Mi
ports:
- containerPort: 6379
```
### Creating the Redis Master Deployment
[Download example](https://raw.githubusercontent.com/kubernetes/examples/master/guestbook/redis-master-deployment.yaml)
<!-- END MUNGE: EXAMPLE redis-master-deployment.yaml -->
The manifest file, included below, specifies a Deployment controller that runs a single replica Redis master Pod.
#### Define a Service
1. Launch a terminal window in the directory you downloaded the manifest files.
2. Apply the Redis Master Deployment from the `redis-master-deployment.yaml` file:
A Kubernetes [Service](http://kubernetes.io/docs/user-guide/services/) is a named load balancer that proxies traffic to one or more containers. This is done using the [labels](http://kubernetes.io/docs/user-guide/labels/) metadata that we defined in the `redis-master` pod above. As mentioned, we have only one redis master, but we nevertheless want to create a Service for it. Why? Because it gives us a deterministic way to route to the single master using an elastic IP.
kubectl apply -f redis-master-deployment.yaml
{% include code.html language="yaml" file="redis-master-deployment.yaml" ghlink="/docs/tutorials/stateless-application/guestbook/redis-master-deployment.yaml" %}
Services find the pods to load balance based on the pods' labels.
The selector field of the Service description determines which pods will receive the traffic sent to the Service, and the `port` and `targetPort` information defines what port the Service proxy will run at.
3. Query the list of Pods to verify that the Redis Master Pod is running:
The file [redis-master-service.yaml](https://git.k8s.io/examples/guestbook/redis-master-service.yaml) defines the redis master Service:
kubectl get pods
<!-- BEGIN MUNGE: EXAMPLE redis-master-service.yaml -->
The response should be similar to this:
```yaml
apiVersion: v1
kind: Service
metadata:
name: redis-master
labels:
app: redis
role: master
tier: backend
spec:
ports:
# the port that this service should serve on
- port: 6379
targetPort: 6379
selector:
app: redis
role: master
tier: backend
```
NAME READY STATUS RESTARTS AGE
redis-master-1068406935-3lswp 1/1 Running 0 28s
[Download example](https://raw.githubusercontent.com/kubernetes/examples/master/guestbook/redis-master-service.yaml)
<!-- END MUNGE: EXAMPLE redis-master-service.yaml -->
4. Run the following command to view the logs from the Redis Master Pod:
#### Create a Service
kubectl logs -f POD-NAME
According to the [config best practices](http://kubernetes.io/docs/user-guide/config-best-practices/), create a Service before corresponding Deployments so that the scheduler can spread the pods comprising the Service. So we first create the Service by running:
**Note:** Replace POD-NAME with the name of your Pod.
{: .note}
```console
$ kubectl create -f guestbook/redis-master-service.yaml
service "redis-master" created
```
### Creating the Redis Master Service
Then check the list of services, which should include the redis-master:
```console
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
redis-master 10.0.76.248 <none> 6379/TCP 1s
```
This will cause all pods to see the redis master apparently running on `<CLUSTER-IP>:<PORT>`. A Service can map an incoming port to any `targetPort` in the backend pod. Once created, the Service proxy on each node is configured to set up a proxy on the specified port (in this case port `6379`).
`targetPort` will default to `port` if it is omitted in the configuration. `targetPort` is the port the container accepts traffic on, and `port` is the abstracted Service port, which can be any port other pods use to access the Service. For simplicity's sake, we omit it in the following configurations.
The traffic flow from slaves to masters can be described in two steps:
- A *redis slave* will connect to `port` on the *redis master Service*
- Traffic will be forwarded from the Service `port` (on the Service node) to the `targetPort` on the pod that the Service listens to.
For more details, please see [Connecting applications](http://kubernetes.io/docs/user-guide/connecting-applications/).
#### Finding a Service
Kubernetes supports two primary modes of finding a Service — environment variables and DNS.
The guestbook applications needs to communicate to the Redis master to write its data. You need to apply a [Service](https://kubernetes.io/docs/concepts/services-networking/service/) to proxy the traffic to the Redis master Pod. A Service defines a policy to access the Pods.
1. Apply the Redis Master Service from the following `redis-master-service.yaml` file:
##### Environment variables
kubectl apply -f redis-master-service.yaml
The services in a Kubernetes cluster are discoverable inside other containers via [environment variables](https://kubernetes.io/docs/concepts/services-networking/service/#environment-variables).
{% include code.html language="yaml" file="redis-master-service.yaml" ghlink="/docs/tutorials/stateless-application/guestbook/redis-master-service.yaml" %}
##### DNS service
**Note:** This manifest file creates a Service named `redis-master` with a set of labels that match the labels previously defined, so the Service routes network traffic to the Redis master Pod.
{: .note}
An alternative is to use the [cluster's DNS service](https://kubernetes.io/docs/concepts/services-networking/service/#dns), if it has been enabled for the cluster. This lets all pods do name resolution of services automatically, based on the Service name.
2. Query the list of Services to verify that the Redis Master Service is running:
This example has been configured to use the DNS service by default.
kubectl get service
If your cluster does not have the DNS service enabled, then you can use environment variables by setting the
`GET_HOSTS_FROM` env value in both
[redis-slave-deployment.yaml](https://git.k8s.io/examples/guestbook/redis-slave-deployment.yaml) and [frontend-deployment.yaml](https://git.k8s.io/examples/guestbook/frontend-deployment.yaml)
from `dns` to `env` before you start up the app.
(However, this is unlikely to be necessary. You can check for the DNS service in the list of the cluster's services by
running `kubectl --namespace=kube-system get rc -l k8s-app=kube-dns`.)
Note that switching to env causes creation-order dependencies, since Services need to be created before their clients that require env vars.
The response should be similar to this:
#### Create a Deployment
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes 10.0.0.1 <none> 443/TCP 1m
redis-master 10.0.0.151 <none> 6379/TCP 8s
Second, create the redis master pod in your Kubernetes cluster by running:
## Start up the Redis Slaves
```console
$ kubectl create -f guestbook/redis-master-deployment.yaml
deployment "redis-master" created
```
Although the Redis master is a single pod, you can make it highly available to meet traffic demands by adding replica Redis slaves.
You can see the Deployment for your cluster by running:
### Creating the Redis Slave Deployment
```console
$ kubectl get deployments
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
redis-master 1 1 1 1 27s
```
Deployments scale based off of the configurations set in the manifest file. In this case, the Deployment object specifies two replicas.
Then, you can list the pods in the cluster, to verify that the master is running:
If there are not any replicas running, this Deployment would start the two replicas on your container cluster. Conversely, if there are more than two replicas are running, it would scale down until two replicas are running.
```console
$ kubectl get pods
```
1. Apply the Redis Slave Deployment from the `redis-slave-deployment.yaml` file:
You'll see all pods in the cluster, including the redis master pod, and the status of each pod.
The name of the redis master will look similar to that in the following list:
kubectl apply -f redis-slave-deployment.yaml
```console
NAME READY STATUS RESTARTS AGE
redis-master-2353460263-1ecey 1/1 Running 0 1m
...
```
{% include code.html language="yaml" file="redis-slave-deployment.yaml" ghlink="/docs/tutorials/stateless-application/guestbook/redis-slave-deployment.yaml" %}
(Note that an initial `docker pull` to grab a container image may take a few minutes, depending on network conditions. A pod will be reported as `Pending` while its image is being downloaded.)
2. Query the list of Pods to verify that the Redis Slave Pods are running:
`kubectl get pods` will show only the pods in the default [namespace](http://kubernetes.io/docs/user-guide/namespaces/). To see pods in all namespaces, run:
kubectl get pods
```
kubectl get pods --all-namespaces
```
The response should be similar to this:
For more details, please see [Configuring containers](http://kubernetes.io/docs/user-guide/configuring-containers/) and [Deploying applications](http://kubernetes.io/docs/user-guide/deploying-applications/).
NAME READY STATUS RESTARTS AGE
redis-master-1068406935-3lswp 1/1 Running 0 1m
redis-slave-2005841000-fpvqc 0/1 ContainerCreating 0 6s
redis-slave-2005841000-phfv9 0/1 ContainerCreating 0 6s
### Creating the Redis Slave Service
#### Optional Interlude
The guestbook application needs to communicate to Redis slaves to read data. To make the Redis slaves discoverable, you need to set up a Service. A Service provides transparent load balancing to a set of Pods.
You can get information about a pod, including the machine that it is running on, via `kubectl describe pods/<POD-NAME>`. E.g., for the redis master, you should see something like the following (your pod name will be different):
1. Apply the Redis Slave Service from the following `redis-slave-service.yaml` file:
```console
$ kubectl describe pods redis-master-2353460263-1ecey
Name: redis-master-2353460263-1ecey
Node: kubernetes-node-m0k7/10.240.0.5
...
Labels: app=redis,pod-template-hash=2353460263,role=master,tier=backend
Status: Running
IP: 10.244.2.3
Controllers: ReplicaSet/redis-master-2353460263
Containers:
master:
Container ID: docker://76cf8115485966131587958ea3cbe363e2e1dcce129e2e624883f393ce256f6c
Image: gcr.io/google_containers/redis:e2e
Image ID: docker://e5f6c5a2b5646828f51e8e0d30a2987df7e8183ab2c3ed0ca19eaa03cc5db08c
Port: 6379/TCP
...
```
The `Node` is the name and IP of the machine, e.g. `kubernetes-node-m0k7` in the example above. You can find more details about this node with `kubectl describe nodes kubernetes-node-m0k7`.
If you want to view the container logs for a given pod, you can run:
```console
$ kubectl logs <POD-NAME>
```
These logs will usually give you enough information to troubleshoot.
However, if you should want to SSH to the listed host machine, you can inspect various logs there directly as well. For example, with Google Compute Engine, using `gcloud`, you can SSH like this:
```console
me@workstation$ gcloud compute ssh <NODE-NAME>
```
Then, you can look at the Docker containers on the remote machine. You should see something like this (the specifics of the IDs will be different):
```console
me@kubernetes-node-krxw:~$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
...
0ffef9649265 redis:latest "/entrypoint.sh redi" About a minute ago Up About a minute k8s_master.869d22f3_redis-master-dz33o_default_1449a58a-5ead-11e5-a104-688f84ef8ef6_d74cb2b5
```
If you want to see the logs for a given container, you can run:
```console
$ docker logs <container_id>
```
### Step Two: Start up the redis slave
Now that the redis master is running, we can start up its 'read slaves'.
We'll define these as replicated pods as well, though this time — unlike for the redis master — we'll define the number of replicas to be 2.
In Kubernetes, a Deployment is responsible for managing multiple instances of a replicated pod. The Deployment will automatically launch new pods if the number of replicas falls below the specified number.
(This particular replicated pod is a great one to test this with -- you can try killing the Docker processes for your pods directly, then watch them come back online on a new node shortly thereafter.)
Just like the master, we want to have a Service to proxy connections to the redis slaves. In this case, in addition to discovery, the slave Service will provide transparent load balancing to web app clients.
This time we put the Service and Deployment into one [file](http://kubernetes.io/docs/user-guide/managing-deployments/#organizing-resource-configurations). Grouping related objects together in a single file is often better than having separate files.
The specification for the slaves is in [all-in-one/redis-slave.yaml](https://git.k8s.io/examples/guestbook/all-in-one/redis-slave.yaml):
<!-- BEGIN MUNGE: EXAMPLE all-in-one/redis-slave.yaml -->
```yaml
apiVersion: v1
kind: Service
metadata:
name: redis-slave
labels:
app: redis
role: slave
tier: backend
spec:
ports:
# the port that this service should serve on
- port: 6379
selector:
app: redis
role: slave
tier: backend
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: redis-slave
# these labels can be applied automatically
# from the labels in the pod template if not set
# labels:
# app: redis
# role: slave
# tier: backend
spec:
# this replicas value is default
# modify it according to your case
replicas: 2
# selector can be applied automatically
# from the labels in the pod template if not set
# selector:
# matchLabels:
# app: guestbook
# role: slave
# tier: backend
template:
metadata:
labels:
app: redis
role: slave
tier: backend
spec:
containers:
- name: slave
image: gcr.io/google_samples/gb-redisslave:v1
resources:
requests:
cpu: 100m
memory: 100Mi
env:
- name: GET_HOSTS_FROM
value: dns
# If your cluster config does not include a dns service, then to
# instead access an environment variable to find the master
# service's host, comment out the 'value: dns' line above, and
# uncomment the line below.
# value: env
ports:
- containerPort: 6379
```
[Download example](https://raw.githubusercontent.com/kubernetes/examples/master/guestbook/all-in-one/redis-slave.yaml)
<!-- END MUNGE: EXAMPLE all-in-one/redis-slave.yaml -->
This time the selector for the Service is `app=redis,role=slave,tier=backend`, because that identifies the pods running redis slaves. It is generally helpful to set labels on your Service itself as we've done here to make it easy to locate them with the `kubectl get services -l "app=redis,role=slave,tier=backend"` command. For more information on the usage of labels, see [using-labels-effectively](http://kubernetes.io/docs/user-guide/managing-deployments/#using-labels-effectively).
Now that you have created the specification, create the Service in your cluster by running:
```console
$ kubectl create -f guestbook/all-in-one/redis-slave.yaml
service "redis-slave" created
deployment "redis-slave" created
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
redis-master 10.0.76.248 <none> 6379/TCP 20m
redis-slave 10.0.112.188 <none> 6379/TCP 16s
$ kubectl get deployments
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
redis-master 1 1 1 1 22m
redis-slave 2 2 2 2 2m
```
Once the Deployment is up, you can list the pods in the cluster, to verify that the master and slaves are running. You should see a list that includes something like the following:
```console
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
redis-master-2353460263-1ecey 1/1 Running 0 35m
redis-slave-1691881626-dlf5f 1/1 Running 0 15m
redis-slave-1691881626-sfn8t 1/1 Running 0 15m
```
You should see a single redis master pod and two redis slave pods. As mentioned above, you can get more information about any pod with: `kubectl describe pods/<POD_NAME>`. And also can view the resources on [kube-ui](http://kubernetes.io/docs/user-guide/ui/).
### Step Three: Start up the guestbook frontend
A frontend pod is a simple PHP server that is configured to talk to either the slave or master services, depending on whether the client request is a read or a write. It exposes a simple AJAX interface, and serves an Angular-based UX.
Again we'll create a set of replicated frontend pods instantiated by a Deployment — this time, with three replicas.
As with the other pods, we now want to create a Service to group the frontend pods.
The Deployment and Service are described in the file [all-in-one/frontend.yaml](https://git.k8s.io/examples/guestbook/all-in-one/frontend.yaml):
<!-- BEGIN MUNGE: EXAMPLE all-in-one/frontend.yaml -->
```yaml
apiVersion: v1
kind: Service
metadata:
name: frontend
labels:
app: guestbook
tier: frontend
spec:
# if your cluster supports it, uncomment the following to automatically create
# an external load-balanced IP for the frontend service.
# type: LoadBalancer
ports:
# the port that this service should serve on
- port: 80
selector:
app: guestbook
tier: frontend
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: frontend
# these labels can be applied automatically
# from the labels in the pod template if not set
# labels:
# app: guestbook
# tier: frontend
spec:
# this replicas value is default
# modify it according to your case
replicas: 3
# selector can be applied automatically
# from the labels in the pod template if not set
# selector:
# matchLabels:
# app: guestbook
# tier: frontend
template:
metadata:
labels:
app: guestbook
tier: frontend
spec:
containers:
- name: php-redis
image: gcr.io/google-samples/gb-frontend:v4
resources:
requests:
cpu: 100m
memory: 100Mi
env:
- name: GET_HOSTS_FROM
value: dns
# If your cluster config does not include a dns service, then to
# instead access environment variables to find service host
# info, comment out the 'value: dns' line above, and uncomment the
# line below.
# value: env
ports:
- containerPort: 80
```
[Download example](https://raw.githubusercontent.com/kubernetes/examples/master/guestbook/all-in-one/frontend.yaml)
<!-- END MUNGE: EXAMPLE all-in-one/frontend.yaml -->
#### Using 'type: LoadBalancer' for the frontend service (cloud-provider-specific)
For supported cloud providers, such as Google Compute Engine or Google Container Engine, you can specify to use an external load balancer
in the service `spec`, to expose the service onto an external load balancer IP.
To do this, uncomment the `type: LoadBalancer` line in the [all-in-one/frontend.yaml](https://git.k8s.io/examples/guestbook/all-in-one/frontend.yaml) file before you start the service.
[See the appendix below](#appendix-accessing-the-guestbook-site-externally) on accessing the guestbook site externally for more details.
Create the service and Deployment like this:
```console
$ kubectl create -f guestbook/all-in-one/frontend.yaml
service "frontend" created
deployment "frontend" created
```
Then, list all your services again:
```console
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
frontend 10.0.63.63 <none> 80/TCP 1m
redis-master 10.0.76.248 <none> 6379/TCP 39m
redis-slave 10.0.112.188 <none> 6379/TCP 19m
```
Also list all your Deployments:
```console
$ kubectl get deployments
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
frontend 3 3 3 3 2m
redis-master 1 1 1 1 39m
redis-slave 2 2 2 2 20m
```
Once it's up, i.e. when desired replicas match current replicas (again, it may take up to thirty seconds to create the pods), you can list the pods with specified labels in the cluster, to verify that the master, slaves and frontends are all running. You should see a list containing pods with label 'tier' like the following:
```console
$ kubectl get pods -L tier
NAME READY STATUS RESTARTS AGE TIER
frontend-1211764471-4e1j2 1/1 Running 0 4m frontend
frontend-1211764471-gkbkv 1/1 Running 0 4m frontend
frontend-1211764471-rk1cf 1/1 Running 0 4m frontend
redis-master-2353460263-1ecey 1/1 Running 0 42m backend
redis-slave-1691881626-dlf5f 1/1 Running 0 22m backend
redis-slave-1691881626-sfn8t 1/1 Running 0 22m backend
```
You should see a single redis master pod, two redis slaves, and three frontend pods.
The code for the PHP server that the frontends are running is in `examples/guestbook/php-redis/guestbook.php`. It looks like this:
```php
<?
set_include_path('.:/usr/local/lib/php');
error_reporting(E_ALL);
ini_set('display_errors', 1);
require 'Predis/Autoloader.php';
Predis\Autoloader::register();
if (isset($_GET['cmd']) === true) {
$host = 'redis-master';
if (getenv('GET_HOSTS_FROM') == 'env') {
$host = getenv('REDIS_MASTER_SERVICE_HOST');
}
header('Content-Type: application/json');
if ($_GET['cmd'] == 'set') {
$client = new Predis\Client([
'scheme' => 'tcp',
'host' => $host,
'port' => 6379,
]);
kubectl apply -f redis-slave-service.yaml
$client->set($_GET['key'], $_GET['value']);
print('{"message": "Updated"}');
} else {
$host = 'redis-slave';
if (getenv('GET_HOSTS_FROM') == 'env') {
$host = getenv('REDIS_SLAVE_SERVICE_HOST');
}
$client = new Predis\Client([
'scheme' => 'tcp',
'host' => $host,
'port' => 6379,
]);
{% include code.html language="yaml" file="redis-slave-service.yaml" ghlink="/docs/tutorials/stateless-application/guestbook/redis-slave-service.yaml" %}
$value = $client->get($_GET['key']);
print('{"data": "' . $value . '"}');
}
} else {
phpinfo();
} ?>
```
2. Query the list of Services to verify that the Redis Slave Service is running:
Note the use of the `redis-master` and `redis-slave` host names -- we're finding those Services via the Kubernetes cluster's DNS service, as discussed above. All the frontend replicas will write to the load-balancing redis-slaves service, which can be highly replicated as well.
kubectl get services
### Step Four: Cleanup
The response should be similar to this:
If you are in a live Kubernetes cluster, you can just kill the pods by deleting the Deployments and Services. Using labels to select the resources to delete is an easy way to do this in one command.
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes 10.0.0.1 <none> 443/TCP 2m
redis-master 10.0.0.151 <none> 6379/TCP 1m
redis-slave 10.0.0.223 <none> 6379/TCP 6s
```console
$ kubectl delete deployments,services -l "app in (redis, guestbook)"
```
## Set up and Expose the Guestbook Frontend
To completely tear down a Kubernetes cluster, if you ran this from source, you can use:
The guestbook application has a web frontend serving the HTTP requests written in PHP. It is configured to connect to the `redis-master` Service for write requests and the `redis-slave` service for Read requests.
```console
$ <kubernetes>/cluster/kube-down.sh
```
### Creating the Guestbook Frontend Deployment
### Troubleshooting
1. Apply the frontend Deployment from the following `frontend-deployment.yaml` file:
If you are having trouble bringing up your guestbook app, double check that your external IP is properly defined for your frontend Service, and that the firewall for your cluster nodes is open to port 80.
kubectl apply -f frontend-deployment.yaml
Then, see the [troubleshooting documentation](http://kubernetes.io/docs/troubleshooting/) for a further list of common issues and how you can diagnose them.
{% include code.html language="yaml" file="frontend-deployment.yaml" ghlink="/docs/tutorials/stateless-application/guestbook/frontend-deployment.yaml" %}
2. Query the list of Pods to verify that the three frontend replicas are running:
kubectl get pods -l app=guestbook -l tier=frontend
### Appendix: Accessing the guestbook site externally
The response should be similar to this:
You'll want to set up your guestbook Service so that it can be accessed from outside of the internal Kubernetes network. Above, we introduced one way to do that, by setting `type: LoadBalancer` to Service `spec`.
NAME READY STATUS RESTARTS AGE
frontend-3823415956-dsvc5 1/1 Running 0 54s
frontend-3823415956-k22zn 1/1 Running 0 54s
frontend-3823415956-w9gbt 1/1 Running 0 54s
More generally, Kubernetes supports two ways of exposing a Service onto an external IP address: `NodePort`s and `LoadBalancer`s , as described [here](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types).
### Creating the Frontend Service
If the `LoadBalancer` specification is used, it can take a short period for an external IP to show up in `kubectl get services` output, but you should then see it listed as well, e.g. like this:
The `redis-slave` and `redis-master` Services you applied are only accessible within the container cluster because the default type for a Service is [ClusterIP](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types). `ClusterIP` provides a single IP address for the set of Pods the Service is pointing to. This IP address is accessible only within the cluster.
```console
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
frontend 10.0.63.63 23.236.59.54 80/TCP 1m
redis-master 10.0.76.248 <none> 6379/TCP 39m
redis-slave 10.0.112.188 <none> 6379/TCP 19m
```
If you want guests to be able to access your guestbook, you must configure the frontend Service to be externally visible, so a client can request the Service from outside the container cluster. Minikube can only expose Services through `NodePort`.
Once you've exposed the service to an external IP, visit the IP to see your guestbook in action, i.e. `http://<EXTERNAL-IP>:<PORT>`.
**Note:** Some cloud providers, like Google Compute Engine or Google Container Engine, support external load balancers. If your cloud provider supports load balancers and you want to use it, simply delete or comment out `type: NodePort`, and uncomment `type: LoadBalancer`.
{: .note}
You should see a web page that looks something like this (without the messages). Try adding some entries to it!
1. Apply the frontend Service from the following `frontend-service.yaml` file:
<img width="50%" src="http://amy-jo.storage.googleapis.com/images/gb_k8s_ex1.png">
kubectl apply -f frontend-service.yaml
{% include code.html language="yaml" file="frontend-service.yaml" ghlink="/docs/tutorials/stateless-application/guestbook/frontend-service.yaml" %}
If you are more advanced in the ops arena, you can also manually get the service IP from looking at the output of `kubectl get pods,services`, and modify your firewall using standard tools and services (firewalld, iptables, selinux) which you are already familiar with.
2. Query the list of Services to verify that the frontend Service is running:
#### Google Compute Engine External Load Balancer Specifics
kubectl get services
In Google Compute Engine, Kubernetes automatically creates forwarding rules for services with `LoadBalancer`.
The response should be similar to this:
You can list the forwarding rules like this (the forwarding rule also indicates the external IP):
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
frontend 10.0.0.112 <nodes> 80:31323/TCP 6s
kubernetes 10.0.0.1 <none> 443/TCP 4m
redis-master 10.0.0.151 <none> 6379/TCP 2m
redis-slave 10.0.0.223 <none> 6379/TCP 1m
```console
$ gcloud compute forwarding-rules list
NAME REGION IP_ADDRESS IP_PROTOCOL TARGET
frontend us-central1 130.211.188.51 TCP us-central1/targetPools/frontend
```
### Viewing the Frontend Service via `NodePort`
In Google Compute Engine, you also may need to open the firewall for port 80 using the [console][cloud-console] or the `gcloud` tool. The following command will allow traffic from any source to instances tagged `kubernetes-node` (replace with your tags as appropriate):
If you deployed this application to Minikube or a local cluster, you need to find the IP address to view your Guestbook.
```console
$ gcloud compute firewall-rules create --allow=tcp:80 --target-tags=kubernetes-node kubernetes-node-80
```
1. Run the following command to get the IP address for the frontend Service.
For GCE Kubernetes startup details, see the [Getting started on Google Compute Engine](http://kubernetes.io/docs/getting-started-guides/gce/)
minikube service frontend --url
For Google Compute Engine details about limiting traffic to specific sources, see the [Google Compute Engine firewall documentation][gce-firewall-docs].
The response should be similar to this:
[cloud-console]: https://console.developer.google.com
[gce-firewall-docs]: https://cloud.google.com/compute/docs/networking#firewalls
http://192.168.99.100:31323
2. Copy the IP address, and load the page in your browser to view your guestbook.
### Viewing the Frontend Service via `LoadBalancer`
If you deployed the `frontend-service.yaml` manifest with type: `LoadBalancer` you need to find the IP address to view your Guestbook.
1. Run the following command to get the IP address for the frontend Service.
kubectl get service frontend
The response should be similar to this:
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
frontend 10.51.242.136 109.197.92.229 80:32372/TCP 1m
2. Copy the External IP address, and load the page in your browser to view your guestbook.
## Scale the Web Frontend
Scaling up or down is easy because your servers are defined as a Service that uses a Deployment controller.
1. Run the following command to scale up the number of frontend Pods:
kubectl scale deployment frontend --replicas=5
2. Query the list of Pods to verify the number of frontend Pods running:
kubectl get pods
The response should look similar to this:
NAME READY STATUS RESTARTS AGE
frontend-3823415956-70qj5 1/1 Running 0 5s
frontend-3823415956-dsvc5 1/1 Running 0 54m
frontend-3823415956-k22zn 1/1 Running 0 54m
frontend-3823415956-w9gbt 1/1 Running 0 54m
frontend-3823415956-x2pld 1/1 Running 0 5s
redis-master-1068406935-3lswp 1/1 Running 0 56m
redis-slave-2005841000-fpvqc 1/1 Running 0 55m
redis-slave-2005841000-phfv9 1/1 Running 0 55m
3. Run the following command to scale down the number of frontend Pods:
kubectl scale deployment frontend --replicas=2
4. Query the list of Pods to verify the number of frontend Pods running:
kubectl get pods
The response should look similar to this:
NAME READY STATUS RESTARTS AGE
frontend-3823415956-k22zn 1/1 Running 0 1h
frontend-3823415956-w9gbt 1/1 Running 0 1h
redis-master-1068406935-3lswp 1/1 Running 0 1h
redis-slave-2005841000-fpvqc 1/1 Running 0 1h
redis-slave-2005841000-phfv9 1/1 Running 0 1h
{% endcapture %}
{% capture cleanup %}
Deleting the Deployments and Services also deletes any running Pods. Use labels to delete multiple resources with one command.
1. Run the following commands to delete all Pods, Deployments, and Services.
kubectl delete deployment -l app=redis
kubectl delete service -l app=redis
kubectl delete deployment -l app=guestbook
kubectl delete service -l app=guestbook
The responses should be:
deployment "redis-master" deleted
deployment "redis-slave" deleted
service "redis-master" deleted
service "redis-slave" deleted
deployment "frontend" deleted
service "frontend" deleted
2. Query the list of Pods to verify that no Pods are running:
kubectl get pods
The response should be this:
No resources found.
{% endcapture %}
{% capture whatsnext %}
* Complete the [Kubernetes Basics](https://kubernetes.io//docs/tutorials/kubernetes-basics/) Interactive Tutorials
* Use Kubernetes to create a blog using [Persistant Volumes for MySQL and Wordpress](https://kubernetes.io/docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/#visit-your-new-wordpress-blog)
* Read more about [connecting applications](https://kubernetes.io/docs/concepts/services-networking/connect-applications-service/)
* Read more about [Managing Resources](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#using-labels-effectively)
{% endcapture %}
{% include templates/tutorial.md %}
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/guestbook/README.md?pixel)]()

2
guestbook/frontend-service.yaml
View File

@ -6,6 +6,8 @@ metadata:
app: guestbook
tier: frontend
spec:
# comment or delete the following line if you want to use a LoadBalancer
type: NodePort
# if your cluster supports it, uncomment the following to automatically create
# an external load-balanced IP for the frontend service.
# type: LoadBalancer