Fix some document errors.

README.md

@@ -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:
 
 ```

dm/dm.go

@@ -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")

docs/templates/registry.md

@@ -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.