helm/examples/guestbook/README.md

# Guestbook Example

Welcome to the Guestbook example. It shows you how to build and reuse
parameterized templates.

## Prerequisites

First, make sure DM is installed in your Kubernetes cluster and that the
Guestbook example is deployed by following the instructions in the top level
[README.md](../../README.md).

## Understanding the Guestbook example template

Let's take a closer look at the template used by the Guestbook example.

### Replicated services

The typical design pattern for microservices in Kubernetes is to create a
replication controller and a service with the same selector, so that the service
exposes ports from the pods managed by the replication controller.

We have created a parameterized type for this kind of replicated service called
[Replicated Service](../../types/replicatedservice/v1), and we use it three times in this
example.

Note that the type is defined by a
[python script](../../types/replicatedservice/v1/replicatedservice.py). It also has a
[schema](../../types/replicatedservice/v1/replicatedservice.py.schema). Schemas are
optional. If present in the type definition, they are used to validate uses of the
type that appear in DM templates.

For more information about types and templates, see the [design document](../../docs/design/design.md).

### The Guestbook application
The Guestbook application consists of 2 microservices: a front end and a Redis cluster.

#### The front end

The front end is a replicated service with 3 replicas:

```
- name: frontend
  type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/types/replicatedservice/v1/replicatedservice.py
  properties:
    service_port: 80
    container_port: 80
    external_service: true
    replicas: 3
    image: gcr.io/google_containers/example-guestbook-php-redis:v3
```

(Note that we use the URL for the type replicatedservice.py, not just the type name.)

#### The Redis cluster

The Redis cluster consists of two replicated services: a master with a single replica
and the slaves with 2 replicas. It's defined by [this composite type](../../types/redis/v1/redis.jinja),
which is a [Jinja](http://jinja.pocoo.org/) template with a [schema](../../types/redis/v1/redis.jinja.schema).

```
{% set REDIS_PORT = 6379 %}
{% set WORKERS = properties['workers'] or 2 %}

resources:
- name: redis-master
  type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/types/replicatedservice/v1/replicatedservice.py
  properties:
    # This has to be overwritten since service names are hard coded in the code
    service_name: redis-master
    service_port: {{ REDIS_PORT }}
    target_port: {{ REDIS_PORT }}
    container_port: {{ REDIS_PORT }}
    replicas: 1
    container_name: master
    image: redis

- name: redis-slave
  type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/types/replicatedservice/v1/replicatedservice.py
  properties:
    # This has to be overwritten since service names are hard coded in the code
    service_name: redis-slave
    service_port: {{ REDIS_PORT }}
    container_port: {{ REDIS_PORT }}
    replicas: {{ WORKERS }}
    container_name: worker
    image: kubernetes/redis-slave:v2
    # An example of how to specify env variables.
    env:
    - name: GET_HOSTS_FROM
      value: env
    - name: REDIS_MASTER_SERVICE_HOST
      value: redis-master
```

### Displaying types

You can see the types you deployed to the cluster using the `deployed-types` command:

```
dm deployed-types 

["Service","ReplicationController","redis.jinja","https://raw.githubusercontent.com/kubernetes/deployment-manager/master/types/replicatedservice/v1/replicatedservice.py"]
```

This output shows 2 primitive types (Service and ReplicationController), and 2
composite types (redis.jinja and one imported from github (replicatedservice.py)).

You can also see where a specific type is being used with the `deployed-instances` command:

```
dm deployed-instances Service
[{"name":"frontend-service","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[0].resources[0]"},{"name":"redis-master","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[1].resources[0].resources[0]"},{"name":"redis-slave","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[1].resources[1].resources[0]"}]
```

This output describes the deployment and manifest, as well as the JSON paths to
the instances of the type within the layout.

For more information about deployments, manifests and layouts, see the [design document](../../docs/design/design.md).