mirror of https://github.com/helm/helm
jackgr
9 years ago
parent
f90e59ee5f
commit
e9abaf5304
@ -1,90 +1,187 @@
|
|||||||
# Type Registry
|
# Template Registries
|
||||||
|
|
||||||
The Deployment Manager client allows you to deploy
|
DM lets configurations instantiate [templates](../design/design.md#templates)
|
||||||
[template types](https://github.com/kubernetes/deployment-manager/blob/master/docs/design/design.md#templates)
|
using both [imports](../design/design.md#template-imports) and
|
||||||
directly from a Github repository. You can use types from existing repositories
|
[references](../design/design.md#template-references).
|
||||||
or integrate with your own repository.
|
|
||||||
|
|
||||||
In order for a Github repository to integrate with Deployment Manager, it must
|
Because template references can use any public HTTP endpoint, they provide
|
||||||
store Deployment Manager templates in a manner that conforms to the required
|
a way to share templates. While you can store templates anywhere you want and
|
||||||
**Type Registry** structure detailed in this document.
|
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
|
## Template Versions
|
||||||
The repository must use the following file structure to store Deployment
|
|
||||||
Manager template types:
|
|
||||||
|
|
||||||
|
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/
|
The template directories may be organized in any way that makes sense to the
|
||||||
<type-1>/
|
repository maintainers.
|
||||||
<version-1>/
|
|
||||||
<type-files>
|
For example, this flat list of template directories is valid:
|
||||||
<version-2>/
|
|
||||||
|
```
|
||||||
|
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
|
## Template Registries
|
||||||
Types are versioned based on [Semantic Versioning](http://semver.org/), for
|
|
||||||
example, *v1.1.0*. A type may have any number of versions.
|
|
||||||
|
|
||||||
## Types
|
Github is a convenient place to store and manage templates. A template registry
|
||||||
Each type version must contain a top-level Deployment Manager template
|
is a Github repository that conforms to the requirements detailed in this document.
|
||||||
[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.
|
|
||||||
|
|
||||||
A
|
For a working example of a template registry, please see the
|
||||||
[template schema](https://github.com/kubernetes/deployment-manager/blob/master/docs/design/design.md#template-schemas)
|
[Kubernetes Template Registry](https://github.com/kubernetes/deployment-manager/tree/master/templates).
|
||||||
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.
|
|
||||||
|
|
||||||
## Test Configuration
|
### Accessing a template registry
|
||||||
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.
|
|
||||||
|
|
||||||
## Sample Registry
|
The Deployment Manager client, `dm`, can deploy templates directly from a registry
|
||||||
An example of a valid type registry repository looks like:
|
using the following command:
|
||||||
|
|
||||||
```
|
```
|
||||||
/
|
$ dm deploy <template-name>:<version>
|
||||||
types/
|
|
||||||
redis/
|
|
||||||
v1/
|
|
||||||
example.yaml
|
|
||||||
redis.jinja
|
|
||||||
redis.jinja.schema
|
|
||||||
replicatedservice/
|
|
||||||
v3/
|
|
||||||
example.yaml
|
|
||||||
replicatedservice.py
|
|
||||||
replicatedservice.py.schema
|
|
||||||
```
|
```
|
||||||
|
|
||||||
For a working example of a type registry, please see the
|
To resolve the template reference, `dm` looks for a template version directory
|
||||||
[kubernetes/deployment-manager registry](https://github.com/kubernetes/deployment-manager/tree/master/types).
|
with the given version in the template directory with the given template name.
|
||||||
|
|
||||||
## Using Types
|
By default, it uses the Kubernetes Template Registry. However, you can set a
|
||||||
The Deployment Manager client can deploy types directly from a registry with
|
different default using the `--registry` flag:
|
||||||
the following command:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
$ 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
|
Alternatively, you can qualify the template name with the path to the template
|
||||||
Github repository. You can change this to another repository that contains a
|
directory within the registry, like this:
|
||||||
registry with the `--registry` flag:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
$ 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.
|
||||||
|
|||||||
@ -0,0 +1,29 @@
|
|||||||
|
# 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).
|
||||||
Loading…
Reference in new issue