Skip to content

Deployable XML

Jump to bottom Edit New page
danmacpherson edited this page Feb 5, 2013 · 1 revision

This page describes Deployable XML and the structure of a Deployable XML document.

Deployables

A deployable is an XML template that defines a deployment, which is the result of the Aeolus process. A deployment is an instance, or set of instances, lauched on a resource provider. Aeolus uses a deployable, which identifies built images and desired hardware profile, and launches the the deployable as a deployment into an appropriate provider.

Required elements

The following is a basic deployable that launches a single instance:

<deployable name="deployment-name">
  <assemblies>
    <assembly name="instance-1" hwp="hwp1">
      <image id="beedb0f9-ca05-46a1-bcbb-704887752d8e"/>
    </assembly>
  </assemblies>
</deployable>

The elements listed are required for each deployable.

deployable

The deployment element acts as a base container for your deployable template. It requires a name attribute to define the name of the deployment.

assemblies

The assemblies element acts as a container for your assembly collection. It contains one or more assembly elements.

assembly

An assembly defines the construction of an instance. It requires a name for the instance (name attribute), a hardware profile (hwp attribute) defined in Conductor, and a reference to an image (image element).

image

The image element defines an image used as a basis for an instance. It refers to the image using the Image UUID (id attribute).

Optional Elements

The following outlines optional elements in a deployable.

description

<deployable name="deployment-name">
  <description>An example deployable</description>
  ...
</deployable>

The description element specifies a user-defined description of the deployable.

Runtime Configuration Elements

An Aeolus user performs runtime configuration on an Audrey-enabled instance using a set of services. A single service defines a script and user-defined parameters to configure an instance upon boot.

Services

To define a service for an instance, add the services element for each instance (signified with an assembly element).

<deployable name="Application">
  <description>An example Application</description>
  <assemblies>
    <assembly name="instance-1" hwp="hwp1">
      <image id="beedb0f9-ca05-46a1-bcbb-704887752d8e"/>
      <services>
        <service name="my-service">
          <executable url="http://www.example.com/script.sh"/>
          <files>
            <file url="http://www.example.com/config.rb"/>
          </files>
          <parameters>
            <parameter name="param-1" type="scalar">
              <value>default_text</value>
            </parameter>
            <parameter name="param-2" type="scalar">
              <reference assembly="instance-2" parameter="hostname-2"/>
            </parameter>
          </parameters>
        </service>
        ...
      </services>
    </assembly>
  </assemblies>
</deployable>

In this example, the instance-1 assembly contains a service element with a name attribute called my-service. This service contains an executable, files and parameters.

The services element contains one or more service elements, which provides multiple services for an instance.

executable

      <services>
        <service name="my-service">
          <executable url="http://www.example.com/script.sh"/>
          ...
        </service>
      </services>

The executable element refers to a script that runs when the instance boots. It requires a url attribute to define the script and its location e.g. http://www.example.com/script.sh. A service only has one script.

files

      <services>
        <service name="my-service">
          ...
          <files>
            <file url="http://www.example.com/config.rb"/>
          </files>
          ...
        </service>
      </services>

The files element is a container for one or more file elements. Each file uses a url attribute to refers to an additional configuration file for the service e.g. http://www.example.com/config.rb.

parameters

      <services>
        <service name="my-service">
          ...
          <parameters>
            <parameter name="param-1" type="scalar">
              <value>default_text</value>
            </parameter>
            <parameter name="param-2" type="scalar">
              <reference assembly="instance-2" parameter="hostname"/>
            </parameter>
          </parameters>
          ...
        </service>
      </services>

The parameters element is a container for one or more parameter elements. A parameter requires a user-defined name (name attribute) and a type (type attribute), which is set to either scalar or password. A parameter element can contain additional value and reference elements.

The value element defines a default value for the parameter.

The reference element defines the value of a parameter using a return value from another assembly. Each reference contains an assembly reference (assembly attribute) and the return value name (param3ter attribute).

The example above contains two parameter elements:

  • param-1 is a user-defined parameter with a default value of default_text.
    • param-2 is a reference to the hostname Facter return value from another instance.

Parameters are used in the executable script as variables that take on the following format:

AUDREY_VAR_[service]_[parameter]

For example:

AUDREY_VAR_my-service_param-1

Aeolus replaces variables that match this format with their parameter values.

Returns Values

Each assembly can contain a set of return values. Define these return values using the returns element as a container for one or more return elements.

<deployable name="Application">
  <description>An example application</description>
  <assemblies>
    <assembly name="instance-1" hwp="hwp1">
      <image id="beedb0f9-ca05-46a1-bcbb-704887752d8e"/>
      <services>
        ...
      </services>
      <returns>
        <return name="hostname-1"/>
      </returns>
    </assembly>
    ...
  </assemblies>
</deployable>

This example contains a single return value called hostname-1. The deployable uses return values for service parameters in other instances.

Element Reference Table

Read the full specification for Deployable XML here .

Element Description Attributes Parents Children Required
assemblies A container for one or more assembly elements deployable assembly Yes
assembly Defines the construction of an instance in a deployment name=“instance-name” hwp=“hardware-profile” assemblies image, services, returns At least one
contents (executable) Contents of an executable script defined in the deployable itself executable
contents (file) Contents of a files defined in the deployable itself file
deployable A container for a deployable. name=“deployable-name” description, assemblies Yes
description (deployable) A user-defined description for the deployable deployable
description (service) A user-defined description for a service service
executable A reference to a executable script for a runtime configuration service url service contents
file A reference to a configuration file for a runtime configuration service url files contents
files A container for one or more file elements service files
image A reference to the image used for the instance id=“UUID”" assembly At least one
parameter A parameter used for in a runtime configuration service name=“param-name” type=“scalar&\#124;password” service value, reference
parameters A container for one or more parameter elements service parameter
reference A reference to a return value from another assembly assembly=“assembly-name” parameter=“return-name” parameter
return Defines a return value for an instance name=“param-name” returns
returns A container for one or more return values assembly return
service Defines a service for runtime configuration of an instance services description, executable, files, parameters
services A container for one or more services name=“service-name” assembly service
value The default value for a parameter parameter

Example Deployables

Basic deployable

<deployable version="1.0" name="simple-single-instance">
  <description>A very simple single instance deployable with no post-launch configuration.</description>
  <assemblies>
    <assembly name="Instance-1" hwp="large">
      <image id="INSERT IMAGE ID"/>
    </assembly>
  </assemblies>
</deployable>

Deployable with runtime configuration

<deployable version="1.0" name="single-instance-multi-service">
  <description>Deploys a single instance with multiple services</description>
  <assemblies>
    <assembly name="Instance-1" hwp="large">
      <image id="INSERT IMAGE ID"/>
      <services>
        <service name="service1">
          <executable url="https://www.aeolusproject.org/redmine/attachments/download/169/start_simple"/>
          <files>
            <file url="https://www.aeolusproject.org/redmine/attachments/download/169/start_simple"/>
            <file url="https://www.aeolusproject.org/redmine/attachments/download/169/start_simple"/>
          </files>
          <parameters>
            <parameter name="service_1_param_1" type="scalar">
              <value><![CDATA[value 1]]></value>
            </parameter>
            <parameter name="service_1_param_2" type="scalar"/>
          </parameters>
        </service>
        <service name="service2">
          <executable url="https://www.aeolusproject.org/redmine/attachments/download/169/start_simple"/>
          <parameters>
            <parameter name="service_2_param_1" type="scalar">
              <value><![CDATA[value 1]]></value>
            </parameter>
            <parameter name="service_2_param_2" type="scalar">
              <value><![CDATA[value 2]]></value>
            </parameter>
          </parameters>
        </service>
      </services>
      <returns>
        <return name="hostname"/>
      </returns>
    </assembly>
  </assemblies>
</deployable>

References

http://aeolusproject.github.com/imagefactory/deployable/

https://github.com/aeolusproject/audrey/tree/master/examples/deployables

Add a custom footer
Add a custom sidebar
Clone this wiki locally