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) [![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, Deployment Manager (DM) `dm` makes it easy to create, describe, update and
such as: 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) For example, this simple configuration deploys the Guestbook example:
* [Redis](templates/redis/v1)
Templates live in ordinary Github repositories called template registries. This ```
Github repository contains a template registry, as well as the DM source code. resources:
- name: frontend
You can use DM to deploy simple configurations that use templates, such as: 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) It uses two templates. The front end is a
* [Deployment Manager](examples/bootstrap/bootstrap.yaml) [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, Templates can use other templates, making it easy to create larger structures
you're reading that second example correctly. It uses DM to deploy itself. See from smaller building blocks. For example, the Redis template uses the replicated
[examples/bootstrap/README.md](examples/bootstrap/README.md) for more information.) 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 DM runs server side, in your Kubernetes cluster, so it can tell you what templates
you've instantiated there, including both primitive types and templates, what you've instantiated there, what resources they created, and even how the resources
instances you've created of a given type, and even how the instances are organized. are organized. So, for example, you can ask questions like:
So, you can ask questions like:
* What Redis instances are running in this cluster? * What Redis instances are running in this cluster?
* What Redis master and slave services are part of this Redis instance? * 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 Because DM stores its state in the cluster, not on your workstation, you can ask
those questions from any client at any time. those questions from any client at any time.
For more information about types, including both primitive types and templates, Templates live in ordinary Github repositories called template registries. See
see the [design document](docs/design/design.md#types). 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 Please hang out with us in
[the Slack chat room](https://kubernetes.slack.com/messages/sig-configuration/) [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. for the Kubernetes configuration SIG.
## Installing Deployment Manager ## Installing Deployment Manager
@ -84,7 +104,8 @@ parameters supplied on the command line, and deploy the resulting configurations
#### Deploying a configuration #### Deploying a configuration
`dm` can deploy a configuration from a file, or read one from `stdin`. This `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 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 #### Deploying a template directly
You can also deploy a template directly, without a configuration. This command 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, You can optionally supply values for template parameters on the command line,
like this: 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 When you deploy a template directly, without a configuration, `dm` generates a
configuration from the template and any supplied parameters, and then deploys the configuration from the template and the supplied parameters, and then deploys the
generated configuration. configuration.
For more information about deploying templates from a template registry or adding 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). types to a template registry, see [the template registry documentation](docs/templates/registry.md).
### Additional commands ### Additional commands
`dm` makes it easy to configure a cluster from a set of predefined templates.
Here's a list of available `dm` commands: 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)") 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") 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)") 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") 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") 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") 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 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 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 ## Template Validation
Every template version should include a configuration named `example.yaml` 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, that can be used to deploy an instance of the template. This file, along with
along with any supporting files it requires, to validate the template. 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 ## Template Organization
@ -79,10 +85,10 @@ to organize templates within a repository.
Therefore: Therefore:
* Every template version must live in its own directory named for the version. * 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 * The version directory must contain exactly one top-level template file and
and supporting files for one and only template version. supporting files for exactly one template version.
* All of the version directories for a given template must live under a single * All of the versions of a given template must live under a directory named for
directory named for the template without extensions. the template without extensions.
For example: For example:
@ -128,6 +134,14 @@ you can simply write
github.com/ownerA/repository2/templateA:v1 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 ### Grouping templates
Of course, a flat list of templates won't scale, and it's unlikely that any 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 A collection is a directory that contains a flat list of templates. Deployment
manager will only discover templates at the root of a collection. manager will only discover templates at the root of a collection.
So for example, in the section above, `templateA` and `templateB` live in the So for example, `templateA` and `templateB` live in the `templates` collection
`templates` collection in the first example, and in the `big-data` collection in in the first example above, and in the `big-data` collection in the second example.
the second example.
A registry may contain any number of collections. A single, unnamed collection 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 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 #### Mapping
Currently, deployment manager maps collection names to directories. This means Currently, deployment manager maps collection names to top level directory names.
that registries can be at most one level deep. Soon, however, we plan to introduce This mapping implies that registries can be at most one level deep. Soon, however,
a metadata file at the top level that maps collection names to paths. This will we plan to introduce a metadata file at the top level that maps collection names
allow registries to have arbitrary organizations, by making it possible to place to paths. This feature will allow registries to have arbitrary organizations, by
collections anywhere in the directory tree. making it possible to place collections anywhere in the directory tree.
When the metadata file is introduced, the current behavior will be the default. 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 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 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 it to a top level directory name by default. This approach allows us to define
at the top level now, and then move them to new locations later without breaking collections at the top level now, and then move them to new locations later without
existing template references. breaking existing template references.
## Using Template Registries ## Using Template Registries
@ -241,25 +254,24 @@ $ dm deploy <template-name>:<version>
``` ```
To resolve the template reference, `dm` looks for a template version directory 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 The default is the [Kubernetes Template Registry](https://github.com/kubernetes/application-dm-templates),
different default using the `--registry` flag: 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 Alternatively, you can specify a complete template reference using the pattern
directory within the registry, like this: 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. If a template requires properties, you can provide them on the command line:
For templates that require properties, you can provide them on the command line:
``` ```
$ dm --properties prop1=value1,prop2=value2 deploy <template-name>:<version> $ 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 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. 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) follows the [workflow](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/development.md#git-setup)
used by Kubernetes. used by Kubernetes.

Write Preview
Loading…
Cancel
Save