====================
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