Skip to content

H
helm3
Commit 09588677 authored by Brendan Melville's avatar Brendan Melville
Browse files
Options

Merge pull request #76 from jackgr/doc-updates 

Update documentation to rationalize the terminology
parents 11f5996c e9abaf53
Expand all Show whitespace changes
Inline Side-by-side
Showing with 275 additions and 145 deletions
README.md
View file @ 09588677
......@@ -2,27 +2,28 @@
[![Go Report Card](http://goreportcard.com/badge/kubernetes/deployment-manager)](http://goreportcard.com/report/kubernetes/deployment-manager)
Deployment Manager (DM) provides parameterized templates for Kubernetes clusters.
Deployment Manager (DM) provides parameterized templates for Kubernetes resources,
such as:
You can use it deploy ready-to-use types, such as:
* [Replicated Service](types/replicatedservice/v1)
* [Redis](types/redis/v1)
* [Replicated Service](templates/replicatedservice/v1)
* [Redis](templates/redis/v1)
Types live in ordinary Github repositories. This repository contains the DM
code, but also acts as a DM type registry.
Templates live in ordinary Github repositories called template registries. This
Github repository contains a template registry, as well as the DM source code.
You can also use DM to deploy simple templates that use types, such as:
You can use DM to deploy simple configurations that use templates, such as:
* [Guestbook](examples/guestbook/guestbook.yaml)
* [Deployment Manager](examples/bootstrap/bootstrap.yaml)
A template is just a `YAML` file that supplies parameters. (Yes, you're reading
that second example correctly. It uses DM to deploy itself.
See [examples/bootstrap/README.md](examples/bootstrap/README.md) for more information.)
A configuration is just a `YAML` file that supplies parameters. (Yes,
you're reading that second example correctly. It uses DM to deploy itself. See
[examples/bootstrap/README.md](examples/bootstrap/README.md) for more information.)
DM runs server side, in your Kubernetes cluster, so it can tell you what types
you've instantiated there, what instances you've created of a given type, and even
how the instances are organized. So, you can ask questions like:
you've instantiated there, including both primitive types and templates, what
instances you've created of a given type, and even how the instances are organized.
So, you can ask questions like:
* What Redis instances are running in this cluster?
* What Redis master and slave services are part of this Redis instance?
......@@ -31,10 +32,12 @@ how the instances are organized. So, you can ask questions like:
Because DM stores its state in the cluster, not on your workstation, you can ask
those questions from any client at any time.
For more information about types, including both primitive types and templates,
see the [design document](../design/design.md#types).
Please hang out with us in
[the Slack chat room](https://kubernetes.slack.com/messages/sig-configuration/)
and/or
[the Google Group](https://groups.google.com/forum/#!forum/kubernetes-sig-config)
and/or [the Google Group](https://groups.google.com/forum/#!forum/kubernetes-sig-config)
for the Kubernetes configuration SIG. Your feedback and contributions are welcome.
## Installing Deployment Manager
......@@ -44,8 +47,8 @@ Follow these 3 steps to install DM:
1. Make sure your Kubernetes cluster is up and running, and that you can run
`kubectl` commands against it.
1. Clone this repository into the src folder of your GOPATH, if you haven't already.
See the [Kubernetes docs](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/development.md)
for how to setup Go and the repos.
See the [Kubernetes developer documentation](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/development.md)
for information on how to setup Go and use the repository.
1. Use `kubectl` to install DM into your cluster `kubectl create -f
install.yaml`
......@@ -64,9 +67,9 @@ is up and running!
### Setting up the client
The easiest way to interact with Deployment Manager is through the `dm` tool
hitting a`kubectl` proxy. To set that up:
hitting a `kubectl` proxy. To set that up:
1. Build the tool by running `make` from the deployment-manager repo.
1. Build the tool by running `make` in the deployment-manager repository.
1. Run `kubectl proxy --port=8001 &` to start a proxy that lets you interact
with the Kubernetes API server through port 8001 on localhost. `dm` uses
`http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager`
......@@ -74,85 +77,81 @@ as the default service address for DM.
### Using the client
#### Deploying from a type registry
The DM client, `dm`, can deploy configurations from the command line. It can also
pull templates from a template registry, generate configurations from them using
parameters supplied on the command line, and deploy the resulting configurations.
#### Deploying a configuration
This command deploys a redis cluster with two workers from the type definition
in this repository:
`dm` can deploy a configuration from a file, or read one from `stdin`. This
command deploys the canonical Guestbook example from the examples directory:
```
dm deploy redis:v1
dm deploy examples/guestbook/guestbook.yaml
```
When you deploy a type, you can optionally supply values for input parameters,
like this:
You can now use `kubectl` to see Guestbook running:
```
dm --properties workers=3 deploy redis:v1
kubectl get service
```
When you deploy a type, `dm` generates a template from the type and input
parameters, and then deploys it.
Look for frontend-service. If your cluster supports external load balancing, it
will have an external IP assigned to it, and you can navigate to it in your browser
to see the guestbook in action.
#### Deploying from a template
For more information about this example, see [examples/guestbook/README.md](examples/guestbook/README.md)
#### Deploying a template directly
You can also deploy an existing template, or read one from `stdin`. This command
deploys the canonical Guestbook example from the examples directory:
You can also deploy a template directly, without a configuration. This command
deploys a redis cluster with two workers from the redis template in this repository:
```
dm deploy examples/guestbook/guestbook.yaml
dm deploy redis:v1
```
You can now use `kubectl` to see Guestbook running:
You can optionally supply values for template parameters on the command line,
like this:
```
kubectl get service
dm --properties workers=3 deploy redis:v1
```
Look for frontend-service. If your cluster supports external load balancing, it
will have an external IP assigned to it, and you can navigate to it in your browser
to see the guestbook in action.
When you deploy a template directly, without a configuration, `dm` generates a
configuration from the template and any supplied parameters, and then deploys the
generated configuration.
For more information about this example, see [examples/guestbook/README.md](examples/guestbook/README.md)
For more information about deploying templates from a template registry or adding
types to a template registry, see [the template registry documentation](docs/templates/registry.md).
### Additional commands
The command line tool makes it easy to configure a cluster from a set of predefined
types. Here's a list of available commands:
`dm` makes it easy to configure a cluster from a set of predefined templates.
Here's a list of available `dm` commands:
```
expand Expands the supplied template(s)
deploy Deploys the supplied type or template(s)
expand Expands the supplied configuration(s)
deploy Deploys the named template or the supplied configuration(s)
list Lists the deployments in the cluster
get Retrieves the supplied deployment
delete Deletes the supplied deployment
update Updates a deployment using the supplied template(s)
get Retrieves the named deployment
delete Deletes the named deployment
update Updates a deployment using the supplied configuration(s)
deployed-types Lists the types deployed in the cluster
deployed-instances Lists the instances of the supplied type deployed in the cluster
types Lists the types in the current registry
describe Describes the supplied type in the current registry
deployed-instances Lists the instances of the named type deployed in the cluster
templates Lists the templates in a given template registry
describe Describes the named template in a given template registry
```
## Uninstalling Deployment Manager
You can uninstall Deployment Manager using the same configuration file:
You can uninstall Deployment Manager using the same configuration:
```
kubectl delete -f install.yaml
```
## Creating a type registry
All you need to create a type registry is a Github repository with top level file
named `registry.yaml`, and a top level folder named `types` that contains type definitions.
A type definition is just a folder that contains one or more versions, like `/v1`,
`/v2`, etc.
A version is just a folder that contains a type definition. As you can see from the
examples above, a type definition is just a Python or [Jinja](http://jinja.pocoo.org/)
file plus an optional schema.
## Building the container images
## Building the Container Images
This project runs Deployment Manager on Kubernetes as three replicated services.
By default, install.yaml uses prebuilt images stored in Google Container Registry
......@@ -167,7 +166,7 @@ GCloud.
There is a more detailed [design document](docs/design/design.md) available.
## Status of the project
## Status of the Project
This project is still under active development, so you might run into issues. If
you do, please don't be shy about letting us know, or better yet, contribute a
......
docs/design/design.md
View file @ 09588677
This diff is collapsed.
docs/types/registry.md
View file @ 09588677
# Type Registry
# Template Registries
The Deployment Manager client allows you to deploy
[template types](https://github.com/kubernetes/deployment-manager/blob/master/docs/design/design.md#templates)
directly from a Github repository. You can use types from existing repositories
or integrate with your own repository.
DM lets configurations instantiate [templates](../design/design.md#templates)
using both [imports](../design/design.md#template-imports) and
[references](../design/design.md#template-references).
In order for a Github repository to integrate with Deployment Manager, it must
store Deployment Manager templates in a manner that conforms to the required
**Type Registry** structure detailed in this document.
Because template references can use any public HTTP endpoint, they provide
a way to share templates. While you can store templates anywhere you want and
organize them any way you want, you may not be able to share them effectively
without some organizing principles. This document defines conventions for
template registries that store templates in Github and organize them by name
and by version to make sharing easier.
## File structure
The repository must use the following file structure to store Deployment
Manager template types:
## Template Versions
Since templates referenced by configurations and by other templates may change
over time, we need a versioning scheme, so that template references can be reliably
resolved to specific template versions.
Every template must therefore carry a version based on the
[Semantic Versioning](http://semver.org/) specification. A template version
consists of a MAJOR version, a MINOR version and a PATCH version, and can
be represented as a three part string starting with the letter `v` and using
dot delimiters between the parts. For example `v1.1.0`.
Parts may be omitted from left to right, up to but not include the MAJOR
version. All omitted parts default to zero. So, for example:
* `v1.1` is equivalent to `v1.1.0`, and
* `v2` is equivalent to `v2.0.0`
As required by Semantic Versioning:
* The MAJOR version must be incremented for incompatible changes
* The MINOR version must be incremented functionality is added in a backwards-compatible
manner, and
* The PATCH version must be incremented for backwards-compatible bug fixes.
When resolving a template reference, DM will attempt to fetch the template with
the highest available PATCH version that has the same MAJOR and MINOR versions as
the referenced version.
## Template Validation
Every template version should include a configuration named `example.yaml`
that can be used to deploy an instance of the template. This file may be used,
along with any supporting files it requires, to validate the template.
## Template Organization
Technically, all you need to reference a template is a directory at a public
HTTP endpoint that contains a template file named either `<template-name>.py`
or `<template-name>.jinja`, depending on the implementation language, along
with any supporting files it might require, such as an optional schema file
named `<template-name>.py.schema` or `<template-name>.jinja.schema`, respectively,
helper files used by the implementation, files imported by the schema, and so on.
These constraints impose a basic level of organization on the template definition
by ensuring that the template and all of its supporting files at least live in the
same directory, and that the template and schema files follow well-defined naming
conventions.
They do not, however, provide any encapsulation. Without additional constraints,
there is nothing to prevent template publishers from putting multiple templates,
or multiple versions of the same template, in the same directory. While there
might be some benefits in allowing templates to share a directory, such as avoiding
the duplication of helper files, the cost of discovering and maintaining templates
would quickly outweigh them as the number of templates in the directory increased.
Every template version must therefore live in its own directory, and that
directory must contain one and only one top-level template file and supporting
files for one and only template version.
Since it may reduce management overhead to store many different templates,
and/or many versions of the same template, in a single repository, we need a way
to organize templates within a repository.
A template repository must therefore place all of the versions of a given
template in directories named for the template versions under a directory named
for the template.
For example:
```
templateA/
v1/
example.yaml
templateA.py
templateA.py.schema
v1.0.1/
example.yaml
templateA.py
templateA.py.schema
v1.1/
example.yaml
templateA.py
templateA.py.schema
helper.py
```
<repository-root>/
types/
<type-1>/
<version-1>/
<type-files>
<version-2>/
The template directories may be organized in any way that makes sense to the
repository maintainers.
For example, this flat list of template directories is valid:
```
templates/
templateA/
v1/
...
templateB/
v2/
...
```
This example, where template directories are organized by category, is also valid:
```
templates/
big-data/
templateA/
v1/
...
templateB/
v2/
...
signals
templateC/
v1/
...
<type-2>/
templateD/
v1.1/
...
```
## Versions
Types are versioned based on [Semantic Versioning](http://semver.org/), for
example, *v1.1.0*. A type may have any number of versions.
## Template Registries
## Types
Each type version must contain a top-level Deployment Manager template
[Deployment Manager template](https://github.com/kubernetes/deployment-manager/blob/master/docs/design/design.md#templates)
named either `<type-name>.py` or `<type-name>.jinja`, depending on the
templating language used for the type.
Github is a convenient place to store and manage templates. A template registry
is a Github repository that conforms to the requirements detailed in this document.
A
[template schema](https://github.com/kubernetes/deployment-manager/blob/master/docs/design/design.md#template-schemas)
must also be present, named `<template>.schema` (e.g., `my-template.py.schema`).
Other files may exist as part of the type and imported through the schema,
including sub-templates, data files, or other metadata used by the template.
For a working example of a template registry, please see the
[Kubernetes Template Registry](https://github.com/kubernetes/deployment-manager/tree/master/templates).
## Test Configuration
Each type version should include an example YAML configuration called
`example.yaml` to be used for deploying an instance of the type. This is useful
for development purposes.
### Accessing a template registry
## Sample Registry
An example of a valid type registry repository looks like:
The Deployment Manager client, `dm`, can deploy templates directly from a registry
using the following command:
```
/
types/
redis/
v1/
example.yaml
redis.jinja
redis.jinja.schema
replicatedservice/
v3/
example.yaml
replicatedservice.py
replicatedservice.py.schema
$ dm deploy <template-name>:<version>
```
For a working example of a type registry, please see the
[kubernetes/deployment-manager registry](https://github.com/kubernetes/deployment-manager/tree/master/types).
To resolve the template reference, `dm` looks for a template version directory
with the given version in the template directory with the given template name.
## Using Types
The Deployment Manager client can deploy types directly from a registry with
the following command:
By default, it uses the Kubernetes Template Registry. However, you can set a
different default using the `--registry` flag:
```
$ dm deploy <type-name>:<version>
$ dm --registry my-org/my-repo/my-root-directory deploy <template-name>:<version>
```
This will default to the type registry in the kubernetes/deployment-manager
Github repository. You can change this to another repository that contains a
registry with the `--registry` flag:
Alternatively, you can qualify the template name with the path to the template
directory within the registry, like this:
```
$ dm --registry my-repo/registry deploy <type-name>:<version>
$ dm deploy my-org/my-repo/my-root-directory/<template-name>:<version>
```
For types that require properties:
Specifying the path to the template directory this way doesn't change the default.
For templates that require properties, you can provide them on the command line:
```
$ dm --properties prop1=value1,prop2=value2 deploy <type-name>:<version>
$ dm --properties prop1=value1,prop2=value2 deploy <template-name>:<version>
```
### Changing a template registry
DM relies on Github to provide the tools and processes needed to add, modify or
delete the contents of a template registry. Conventions for changing a template
registry are defined by the registry maintainers, and should be published in the
top level README.md or a file it references, following usual Github practices.
The [Kubernetes Template Registry](https://github.com/kubernetes/deployment-manager/tree/master/templates)
follows the [git setup](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/development.md#git-setup)
used by Kubernetes.
examples/guestbook/README.md
View file @ 09588677
......@@ -9,9 +9,9 @@ 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
## Understanding the Guestbook example
Let's take a closer look at the template used by the Guestbook example.
Let's take a closer look at the configuration used by the Guestbook example.
### Replicated services
......@@ -19,20 +19,22 @@ 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.
We have created a parameterized template for this kind of replicated service
called [Replicated Service](../../templates/replicatedservice/v1), and we use it
three times in the Guestbook 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.
The template is defined by a
[Python script](../../templates/replicatedservice/v1/replicatedservice.py). It
also has a [schema](../../templates/replicatedservice/v1/replicatedservice.py.schema).
Schemas are optional. If provided, they are used to validate template invocations
that appear in configurations.
For more information about types and templates, see the [design document](../../docs/design/design.md).
For more information about templates and schemas, see the
[design document](../../docs/design/design.md#templates).
### The Guestbook application
The Guestbook application consists of 2 microservices: a front end and a Redis cluster.
The Guestbook application consists of 2 microservices: a front end and a Redis
cluster.
#### The front end
......@@ -40,7 +42,7 @@ 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
type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/templates/replicatedservice/v1/replicatedservice.py
properties:
service_port: 80
container_port: 80
......@@ -49,13 +51,14 @@ The front end is a replicated service with 3 replicas:
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.)
(Note that we use the URL for a specific version of the template replicatedservice.py,
not just the template 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).
and the slaves with 2 replicas. It's defined by [this template](../../templates/redis/v1/redis.jinja),
which is a [Jinja](http://jinja.pocoo.org/) file with a [schema](../../templates/redis/v1/redis.jinja.schema).
```
{% set REDIS_PORT = 6379 %}
......@@ -63,7 +66,7 @@ which is a [Jinja](http://jinja.pocoo.org/) template with a [schema](../../types
resources:
- name: redis-master
type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/types/replicatedservice/v1/replicatedservice.py
type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/templates/replicatedservice/v1/replicatedservice.py
properties:
# This has to be overwritten since service names are hard coded in the code
service_name: redis-master
......@@ -75,7 +78,7 @@ resources:
image: redis
- name: redis-slave
type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/types/replicatedservice/v1/replicatedservice.py
type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/templates/replicatedservice/v1/replicatedservice.py
properties:
# This has to be overwritten since service names are hard coded in the code
service_name: redis-slave
......@@ -94,16 +97,17 @@ resources:
### Displaying types
You can see the types you deployed to the cluster using the `deployed-types` command:
You can see both the both primitive types and the templates 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"]
["Service","ReplicationController","redis.jinja","https://raw.githubusercontent.com/kubernetes/deployment-manager/master/templates/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)).
templates (redis.jinja and one imported from github named replicatedservice.py).
You can also see where a specific type is being used with the `deployed-instances` command:
......@@ -115,6 +119,7 @@ dm deployed-instances Service
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).
For more information about deployments, manifests and layouts, see the
[design document](../../docs/design/design.md#api-model).
types/README.md 0 → 100644
View file @ 09588677
# Kubernetes Template Registry
Welcome to the Kubernetes Template Registry!
This registry holds Deployment Manager
[templates](https://github.com/kubernetes/deployment-manager/tree/master/docs/design/design.md#templates)
that you can use to deploy Kubernetes resources.
For more information about installing and using Deployment Manager, see its
[README.md](https://github.com/kubernetes/deployment-manager/tree/master/README.md).
## Organization
The Kubernetes Template Registry is organized as a flat list of template
directories. Templates are versioned. The versions of a template live in version
directories under its template directory.
For more information about Deployment Manager template registries, including
directory structure and template versions, see the
[template registry documentation](https://github.com/kubernetes/deployment-manager/tree/master/docs/templates/registry.md)
## Contributing
The Kubernetes Template Registry follows the
[git setup](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/development.md#git-setup)
used by Kubernetes.
You will also need to have a Contributor License Agreement on file, as described
in [CONTRIBUTING.md](../CONTRIBUTING.md).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment