Public | Automated Build

Last pushed: 2 years ago
Short Description
Provide automation around a MAAS deployment as part of a CORD POD
Full Description

Metal as a Service Automation (maas-flow)

This is a utility that works in conjunction with an Ubuntu Metal as a Service
(MAAS) deployment. By default, the MAAS system allows an
operator to manually control the lifecycle of a compute host as it comes on
line leveraging PXE, DHCP, DNS, etc.

The utility leverages the MAAS REST API to periodically monitor the status
of the hosts under control of MAAS and continuous attempts to move those hosts
into a deployed state. (Note: this will likely change in the future to
support additional target states.)

Filtering Hosts on which to Operate

Using a filter the operator can control on which hosts automation acts. The
filter is a basic JSON object and can either be specified as a string on
the command line or a file which contains the filter. When specifying a file
the value of the -filter command line option should be a @ followed by
the name of the file, i.e. @$HOME/some/file, and it may container environment

The structure of the filter object is:

    "hosts" : {
        "include" : [],
        "exclude" : []
    "zones" : {
        "include" : [],
        "exclude" : []

For hosts the include and exclude values are a list of regular
expressions which are mapped against the hostname of a device under control of

for zones the include and exclude values are a list of regular
expression which are mapped against the zone with which a host is associated.

When both include and exclude values are specified the include
is processed followed by the exclude.

The default filter, if none is specified, is depicted below. Essentially it
specifies that the automation will act on all hosts in only the default
zone. (NOTE: This default filter may change in the future.)

  "hosts" : {
    "include" : [],
    "exclude" : []
  "zones" : {
    "include" : ["default"],
    "exclude" : []

NOTE: only include is currently (January 26, 2016) supported.

Connecting to MAAS

The connection to MAAS is controlled by command line parameters, specifically:

  • -apiVersion - (default: 1.0) specifies the version of the MAAS API to use
  • -apiKey - (default: none) specifies the API key to use to authenticate to
    the MAAS server. For a given user this can be found on under their account
    settings in the MAAS UI. This value is important as the automation is acting
    on behalf of this user and the SSH keys that are pushed to hosts will be the
    SSH keys associated with this user.
  • -maas - (default: http://localhost/MAAS) specifies the base URL on which
    to contact the MAAS server.
  • -period - (default: 15s) specifies how often the automation queries the
    MAAS server to retrieve the state of the hosts. Automation must query the state
    of the hosts from MAAS as MAAS does not support an asynchronous change
    mechanism today. This value should be set such that the automation can fully
    process all the hosts within a period.

Docker Image

The project contains a Dockerfile that can be used to construct a docker
image from the repository. The docker image is also provided via Docker Hub at

State machine

The state machine on which the MAAS automation is based is depicted below.
Currently (January 26, 2016) the automation only supports a deployed target
state and will not act on hosts that are in a failed, broken, or error state.

Post Deployment Provisioning

All the states in the state machine are defined and maintained by
MAAS except the states Provisioning, ProvisionError, and Provisioned. These
states are used to track the post-deployment provisioning that is part of the

Post deployment provisioning can be accomplished either by the specification of
a script to execute or the specification of a URL to trigger.

Executing a Script

A script to execute to post deploy provision a node can be specified via the
environment as PROVISION_URL. After a node is deployed this script will be
executed with three (3) parameters:

  • node ID - the node ID that MAAS uses to track the node
  • name - the name of the node in MAAS
  • ip - the IP address assigned to the node

It is important to note that when executing a script that the script is run
within the docker container that is running the automation. Thus any script
must be mounted as a volume into the container.

Triggering a URL

Alternatively the automation can trigger a URL to POST deploy provision a node.
In this instance, automation will POST a JSON object to the specified URL
with the values:

  • "id" - the node ID that MAAS uses to track the node
  • "name" - the name of the node in MAAS
  • "ip" - the IP address assigned to the node

The provider specified should return "202 Accept" to acknowledge the acceptance
of the request. The automation controller will poll for status on the
provisioning so the provider should accept the request but not process it
while the client is blocked.

The automation controller will periodically poll for provisioning status for a
given node by doing a HTTP GET on the specified provisioning URL appended with
/ and the ID of the node. The provider should either return 202 Accept if
the node is still being provisioned, 200 OK if the provisioning is complete
and successful, or any other response which will be treated as an error.

Docker Pull Command
Source Repository