magnum/contrib/templates/example
Andrew Melton 3a8ab855a8 Add Template Definitions
The idea here is to provide a way for magnum to discover and interact
with templates meant to build bays. Template definition discovery is
done through python entry_points, and each class lists the bay_types
it can provide. Each template definition contains a mapping of magnum
object attributes and heat template parameters/outputs.

This will be useful for not only allowing different CoEs, OSes, and
platforms. But can also provide the discovery mechanism for templates
once they are pulled into their own repository.

Partial-Implements: bp multiple-bay-templates

Change-Id: Ia596657856cd861c94e58dcd65acae0677a36d73
2015-04-09 08:47:15 -07:00
..
example_template Add Template Definitions 2015-04-09 08:47:15 -07:00
README.rst Add Template Definitions 2015-04-09 08:47:15 -07:00
setup.py Add Template Definitions 2015-04-09 08:47:15 -07:00

Example Bay Template

This project is an example to demonstrate the necessary pieces of a Bay template. There are three key pieces to a bay template:

  1. Heat template - The Heat template that Magnum will use to generate a Bay.
  2. Template definition - Magnum's interface for interacting with the Heat template.
  3. Definition Entry Point - Used to advertise the available template definitions.

The Heat Template

The heat template is where most of the real work happens. The result of the Heat template should be a full Container Orchestration Environment.

The Template Definition

Template definitions are a mapping of Magnum object attributes and Heat template parameters, along with Magnum consumable template outputs. Each definition also denotes which Bay Types it can provide. Bay Types are how Magnum determines which of the enabled Template Definitions it will use for a given Bay.

The Definition Entry Point

Entry points are a standard discovery and import mechanism for Python objects. Each Template Definition should have an Entry Point in the magnum.template_definitions group. This example exposes it's Template Definition as example_template = example_template:ExampleTemplate in the magnum.template_definitions group.

Installing Bay Templates

Because Bay Templates are basically Python projects, they can be worked with like any other Python project. They can be cloned from version control and installed or uploaded to a package index and installed via utilities such as pip.

Enabling a template is as simple as adding it's Entry Point to the enabled_definitions config option in magnum.conf.:

# Setup python environment and install Magnum

$ virtualenv .venv
$ source .venv/bin/active
(.venv)$ git clone https://github.com/openstack/magnum.git
(.venv)$ cd magnum
(.venv)$ python setup.py install

# List installed templates, notice default templates are enabled

(.venv)$ magnum-template-manage list-templates
Enabled Templates
  magnum_vm_atomic_k8s: /home/example/.venv/local/lib/python2.7/site-packages/magnum/templates/heat-kubernetes/kubecluster.yaml
  magnum_vm_coreos_k8s: /home/example/.venv/local/lib/python2.7/site-packages/magnum/templates/heat-kubernetes/kubecluster-coreos.yaml
Disabled Templates

# Install example template

(.venv)$ cd contrib/templates/example
(.venv)$ python setup.py install

# List installed templates, notice example template is disabled

(.venv)$ magnum-template-manage list-templates
Enabled Templates
  magnum_vm_atomic_k8s: /home/example/.venv/local/lib/python2.7/site-packages/magnum/templates/heat-kubernetes/kubecluster.yaml
  magnum_vm_coreos_k8s: /home/example/.venv/local/lib/python2.7/site-packages/magnum/templates/heat-kubernetes/kubecluster-coreos.yaml
Disabled Templates
  example_template: /home/example/.venv/local/lib/python2.7/site-packages/ExampleTemplate-0.1-py2.7.egg/example_template/example.yaml

# Enable example template by setting enabled_definitions in magnum.conf

(.venv)$ sudo mkdir /etc/magnum
(.venv)$ sudo bash -c "cat > /etc/magnum/magnum.conf << END_CONF
[bay]
enabled_definitions=magnum_vm_atomic_k8s,magnum_vm_coreos_k8s,example_template
END_CONF"

# List installed templates, notice example template is now enabled

(.venv)$ magnum-template-manage list-templates
Enabled Templates
  example_template: /home/example/.venv/local/lib/python2.7/site-packages/ExampleTemplate-0.1-py2.7.egg/example_template/example.yaml
  magnum_vm_atomic_k8s: /home/example/.venv/local/lib/python2.7/site-packages/magnum/templates/heat-kubernetes/kubecluster.yaml
  magnum_vm_coreos_k8s: /home/example/.venv/local/lib/python2.7/site-packages/magnum/templates/heat-kubernetes/kubecluster-coreos.yaml
Disabled Templates

# Use --details argument to get more details about each template

(.venv)$ magnum-template-manage list-templates --details
Enabled Templates
  example_template: /home/example/.venv/local/lib/python2.7/site-packages/ExampleTemplate-0.1-py2.7.egg/example_template/example.yaml
     Platform  OS       CoE
     vm        example  example_coe
  magnum_vm_atomic_k8s: /home/example/.venv/local/lib/python2.7/site-packages/magnum/templates/heat-kubernetes/kubecluster.yaml
     Platform  OS             CoE
     vm        fedora-atomic  kubernetes
  magnum_vm_coreos_k8s: /home/example/.venv/local/lib/python2.7/site-packages/magnum/templates/heat-kubernetes/kubecluster-coreos.yaml
     Platform  OS      CoE
     vm        coreos  kubernetes
Disabled Templates