Public | Automated Build

Last pushed: 2 years ago
Short Description
Automate server on boarding from new to deployed via MAAS
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.

Docker Pull Command
Source Repository