msb-public
/
helm
mirror of https://github.com/helm/helm
1
0
Code Issues Projects Releases Wiki Activity

Merge pull request #134 from jackgr/doc-fix

Browse Source 
Fix some document errors
pull/142/head
vaikas-google 10 years ago
parent f07cf32d4b 538b34d820
commit d3d57fdaee
3 changed files with 90 additions and 57 deletions
Show Stats Download Patch File Download Diff File

75
README.md
Unescape View File

@ -2,28 +2,44 @@
[![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 resources,
such as:
Deployment Manager (DM) `dm` makes it easy to create, describe, update and
delete Kubernetes resources using declarative configuration. A configuration is
just a `YAML` file that configures Kubernetes resources or supplies parameters
to templates. Templates are just YAML files with [Jinja](http://jinja.pocoo.org/)
mark up or Python scripts.
* [Replicated Service](templates/replicatedservice/v1)
* [Redis](templates/redis/v1)
For example, this simple configuration deploys the Guestbook example:
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 use DM to deploy simple configurations that use templates, such as:
```
resources:
- name: frontend
type: github.com/kubernetes/application-dm-templates/common/replicatedservice:v1
properties:
service_port: 80
container_port: 80
external_service: true
replicas: 3
image: gcr.io/google_containers/example-guestbook-php-redis:v3
- name: redis
type: github.com/kubernetes/application-dm-templates/storage/redis:v1
properties: null
```
* [Guestbook](examples/guestbook/guestbook.yaml)
* [Deployment Manager](examples/bootstrap/bootstrap.yaml)
It uses two templates. The front end is a
[replicated service](https://github.com/kubernetes/application-dm-templates/common/replicatedservice/v1),
which creates a service and replication controller with matching selectors, and
the back end is a
[Redis cluster](https://github.com/kubernetes/application-dm-templates/storage/redis/v1),
which creates a Redis master and two Redis slaves.
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.)
Templates can use other templates, making it easy to create larger structures
from smaller building blocks. For example, the Redis template uses the replicated
service template to create the Redis master, and then again to create each Redis
slave.
DM runs server side, in your Kubernetes cluster, so it can tell you what types
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:
DM runs server side, in your Kubernetes cluster, so it can tell you what templates
you've instantiated there, what resources they created, and even how the resources
are organized. So, for example, 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?
@ -32,13 +48,17 @@ 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](docs/design/design.md#types).
Templates live in ordinary Github repositories called template registries. See
the [Kubernetes Template Registry](https://github.com/kubernetes/application-dm-templates)
for curated Kubernetes applications using Deployment Manager templates.
For more information about configurations and templates, see the
[design document](docs/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)
for the Kubernetes configuration SIG. Your feedback and contributions are welcome.
for the Kubernetes configuration SIG.
## Installing Deployment Manager
@ -84,7 +104,8 @@ parameters supplied on the command line, and deploy the resulting configurations
#### Deploying a configuration
`dm` can deploy a configuration from a file, or read one from `stdin`. This
command deploys the canonical Guestbook example from the examples directory:
command deploys the Guestbook example using the configuration shown above from
the examples directory in this project:
```
dm deploy examples/guestbook/guestbook.yaml
@ -105,29 +126,29 @@ For more information about this example, see [examples/guestbook/README.md](exam
#### Deploying a template directly
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:
deploys a redis cluster with two slaves from the redis template in the [Kubernetes
Template Registry](https://github.com/kubernetes/application-dm-templates):
```
dm deploy redis:v1
dm deploy storage/redis:v1
```
You can optionally supply values for template parameters on the command line,
like this:
```
dm --properties workers=3 deploy redis:v1
dm --properties workers=3 deploy storage/redis:v1
```
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.
configuration from the template and the supplied parameters, and then deploys the
configuration.
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
`dm` makes it easy to configure a cluster from a set of predefined templates.
Here's a list of available `dm` commands:
```

2
dm/dm.go
Unescape View File

@ -40,7 +40,7 @@ var (
deployment_name = flag.String("name", "", "Name of deployment, used for deploy and update commands (defaults to template name)")
stdin = flag.Bool("stdin", false, "Reads a configuration from the standard input")
properties = flag.String("properties", "", "Properties to use when deploying a template (e.g., --properties k1=v1,k2=v2)")
template_registry = flag.String("registry", "kubernetes/deployment-manager/templates", "Github based template registry (owner/repo[/path])")
template_registry = flag.String("registry", "kubernetes/application-dm-templates", "Github based template registry (owner/repo[/path])")
service = flag.String("service", "http://localhost:8001/api/v1/proxy/namespaces/dm/services/manager-service:manager", "URL for deployment manager")
binary = flag.String("binary", "../expandybird/expansion/expansion.py", "Path to template expansion binary")
timeout = flag.Int("timeout", 10, "Time in seconds to wait for response")

70
docs/templates/registry.md vendored
Unescape View File

@ -41,13 +41,19 @@ manner, and
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.
the referenced version. However, it will not automatically substitute a higher
MINOR version for a requested MINOR version with the same MAJOR version, since
although it would be backward compatible, it would not have the same feature set.
You must therefore explicitly request the higher MINOR version in this situation
to obtain the additional features.
## 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.
that can be used to deploy an instance of the template. This file, along with
any supporting files it requires, may be used automatically in the future by
a template testing framework to validate the template, and should therefore be
well formed.
## Template Organization
@ -79,10 +85,10 @@ to organize templates within a repository.
Therefore:
* Every template version must live in its own directory named for the version.
* The version directory must contain one and only one top-level template file
and supporting files for one and only template version.
* All of the version directories for a given template must live under a single
directory named for the template without extensions.
* The version directory must contain exactly one top-level template file and
supporting files for exactly one template version.
* All of the versions of a given template must live under a directory named for
the template without extensions.
For example:
@ -128,6 +134,14 @@ you can simply write
github.com/ownerA/repository2/templateA:v1
```
The general pattern for a registry based template reference is as follows:
```
github.com/<owner>/<repository>/<collection>/<template>:<version>
```
The `collection` segment, described below, is optional, and may be omitted.
### Grouping templates
Of course, a flat list of templates won't scale, and it's unlikely that any
@ -181,9 +195,8 @@ collections.
A collection is a directory that contains a flat list of templates. Deployment
manager will only discover templates at the root of a collection.
So for example, in the section above, `templateA` and `templateB` live in the
`templates` collection in the first example, and in the `big-data` collection in
the second example.
So for example, `templateA` and `templateB` live in the `templates` collection
in the first example above, and in the `big-data` collection in the second example.
A registry may contain any number of collections. A single, unnamed collection
is implied at the root of every registry, but additional named collections may
@ -216,18 +229,18 @@ github.com/ownerA/repository2/dot.delimited.strings.are.allowed/templateA:v1
#### Mapping
Currently, deployment manager maps collection names to directories. This means
that registries can be at most one level deep. Soon, however, we plan to introduce
a metadata file at the top level that maps collection names to paths. This will
allow registries to have arbitrary organizations, by making it possible to place
collections anywhere in the directory tree.
Currently, deployment manager maps collection names to top level directory names.
This mapping implies that registries can be at most one level deep. Soon, however,
we plan to introduce a metadata file at the top level that maps collection names
to paths. This feature will allow registries to have arbitrary organizations, by
making it possible to place collections anywhere in the directory tree.
When the metadata file is introduced, the current behavior will be the default.
So, if the metadata file is not found in a given registry, or if a given collection
name is not found in the metadata file, then deployment manager will simply map
it to a directory name by default. This approach allows us to define collections
at the top level now, and then move them to new locations later without breaking
existing template references.
it to a top level directory name by default. This approach allows us to define
collections at the top level now, and then move them to new locations later without
breaking existing template references.
## Using Template Registries
@ -241,25 +254,24 @@ $ dm deploy <template-name>:<version>
```
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.
with the given version in the template directory with the given template name in
the default template registry.
By default, it uses the Kubernetes Template Registry. However, you can set a
different default using the `--registry` flag:
The default is the [Kubernetes Template Registry](https://github.com/kubernetes/application-dm-templates),
but you can set a different default using the `--registry` flag:
```
$ dm --registry my-org/my-repo/my-root-directory deploy <template-name>:<version>
$ dm --registry my-org/my-repo/my-collection deploy <template-name>:<version>
```
Alternatively, you can qualify the template name with the path to the template
directory within the registry, like this:
Alternatively, you can specify a complete template reference using the pattern
described above, like this:
```
$ dm deploy my-org/my-repo/my-root-directory/<template-name>:<version>
$ dm deploy github.com/my-org/my-repo/my-collection/<template-name>:<version>
```
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:
If a template requires properties, you can provide them on the command line:
```
$ dm --properties prop1=value1,prop2=value2 deploy <template-name>:<version>
@ -272,6 +284,6 @@ 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 standard Github practices.
The [Kubernetes Template Registry](https://github.com/kubernetes/deployment-manager/tree/master/templates)
The [Kubernetes Template Registry](https://github.com/kubernetes/application-dm-templates)
follows the [workflow](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/development.md#git-setup)
used by Kubernetes.

Write Preview
Loading…
Cancel
Save