Offline docs (switch to live docs)                         UI-only          CLI-only 

How to spin up MAAS with Ansible

How to install a region controller with Ansible

As an operator, you want to install a MAAS region controller onto a given host using Ansible. To accomplish this, you must:

  1. Attach the maas_region_controller role to your region controller host by adding the following to the Inventory file. In the example below, we’ve attached the region controller role to a host running on 10.10.0.20 with the user ubuntu:

INI:

[maas_region_controller]
10.10.0.20 ansible_user=ubuntu

YAML:

all:
  maas_region_controller:
    hosts:
      10.10.0.20:
        ansible_user: ubuntu
  1. Set the following Ansible variables in the hosts file:

[maas_region_controller] variables:

maas_version: "latest"          # The version of MAAS to install on the host
maas_installation_type: "snap"  # The installation manager to use (snap or deb)
maas_snap_channel: "stable"     # The snap channel, if using snap
maas_url: $Ip_Address           # The url of the database for this MAAS
enable_tls: false               # Whether TLS should be enabled for this MAAS
o11y_enable: false              # Whether observability should be enabled for this MAAS

# Details for the administrative account
admin_username: "admin"
admin_password: "admin"
admin_email: "admin@email.com"
admin_id: "lp:admin"            # Either lp:user-id (Launchpad) or gh:user-id (Github)
  1. Run the playbook to install the region controller. A successful run of the playbook should give the operator an accessible and ready MAAS instance.

Some important notes on installation:

Finding the new region controller

You can find the newly-installed region controller at the specified MAAS host IP address, as though the controller had been installed manually.

How to install a rack controller with Ansible

As an operator, you want to install a MAAS rack controller to a given host, using Ansible. To accomplish this, you must:

  1. Assign a host to the maas_rack_controller role in the Ansible hosts file:

INI

[maas_rack_controller]
$Host_Ip_Address extra_variable=$Variable_Value
$Second_Host_Ip

YAML

all:
  maas_rack_controller:
    hosts:
      $Host_Ip_Address:
        extra_variable: $Variable_Value
      $Second_Host_Ip
  1. Set the following Ansible variables in the Hosts file:

[maas_rack_controller] Variables

maas_version: "latest"          # The version of MAAS to install on the host
maas_installation_type: "snap"  # The installation manager to use
maas_snap_channel: "stable"     # The snap channel, if using snap
maas_url: $Ip_Address           # The url of the region controller for this MAAS
maas_rack_secret:               # The secret used to enroll a MAAS rack
enable_tls: false               # Whether TLS should be enabled for this MAAS
o11y_enable: false              # Whether observability should be enabled for this MAAS
  1. Run the Ansible playbook to install the region controller.

Some notes about installation:

Finding the new rack controller

The rack controller should be accessible at the specified host IP address, just as if you had installed it there manually.

How to uninstall MAAS with Ansible

As an operator, you want to be able to revert the MAAS setup installed by this playbook, such that the machine is clean of all MAAS packages or snaps. In order to teardown a MAAS deployment, do the following:

  1. Find the entry-point within the playbook to teardown the installed MAAS packages or snaps.

  2. Back up the database and MAAS configuration, if desired. Note that the target machine is restored state prior to installation, with no MAAS, directories, or files present on the system.

  3. Run the playbook from this entry-point to remove the installation.

Running this playbook with the default configuration with perfectly undo the default installation.

How to configure MAAS HA with Ansible

As an operator, you want to install a reverse proxy and configure high-availability region controllers for a given host using Ansible. Note that HA region controllers require an HAProxy configuration.

You can accomplish this with the following steps:

  1. Set the following in the hosts file to set the maas_proxy role:
[maas_proxy]
my.host ansible_user=ssh_user
  1. Run the full playbook, or add --tags maas_proxy to run only the tasks for this role.

  2. Verify that the HAProxy is forwarding traffic by running the following if HAProxy is on a separate host from the region controller:

curl -L http://<haproxy host>:5240/MAAS`
  1. If HAProxy is not on a separate host, change the port number to 5050 when you run the command, like this:
curl -L http://<haproxy host>:5050/MAAS

Note that the playbook configures the HAProxy instance for optimal use, such that OS images can be uploaded (for example). An unresponsive Region Controller is taken out of the upstream pool quickly. The HAProxy instance does not interfere with Nginx/MAAS TLS configuration

How to install HA PostgreSQL

As an operator, you want to install a HA Postgresql database cluster to a given set of hosts using Ansible. You can accomplish this with the following steps:

  1. Set the following in the hosts file to set the maas_postgres and maas_corosync roles:
[maas_corosync]
my.db1 ansible_user=ssh_user
my.db2 ansible_user=ssh_user
my.db3 ansible_user=ssh_user

[maas_pacemaker:children]
maas_corosync

[maas_postgres]
my.db1 ansible_user=ssh_user
my.db2 ansible_user=ssh_user
my.db3 ansible_user=ssh_user
  1. Set the following Ansible variables in the Hosts file:

[maas_pacemaker] Variables

# Fencing configuration
maas_pacemaker_fencing_driver: $stonith_driver
maas_pacemaker_stonith_params: $stonith_parameters

[maas_postgres] HA-related variables

maas_postgres_floating_ip: $vIP
maas_postgres_floating_ip_prefix_len: $vIP_masklen
  1. Run the full playbook, or add --tags maas_ha_postgres to run only the tasks for this roles.

  2. Verify the primary by running sudo -u postgres psql and making sure you get a prompt.

Note that Ansible installs the latest supported version of PostgreSQL supported for the given MAAS version. If the playbook runs with other roles set on targeted hosts / groups, the tasks associated with the maas_postgresql role runs first. If the operator sets a variable for importing a backup, the backup is loaded into PostgreSQL.

How to enable Observability capabilities

As an operator, you want to export metrics and logs to your observability stack using Ansible. You can accomplish this with the following steps:

  1. Set the following Ansible variables in the Hosts file:

[all] Variables

o11y_enable: true
o11y_prometheus_url: http://$prometheus_ip:9090/api/v1/write
o11y_loki_url: http://$loki:3100/loki/api/v1/push

Optionally you can set o11y_enable only on hosts of interest.

  1. Run the playbook

This installs and configures the grafana-agent service on all roles that support it. You can disable either metrics or logs export by omitting the respective endpoint definition. You need to run the Prometheus server with the remote-write-receiver feature enabled in order to receive metrics pushed by the agents.

MAAS has a curated collection of alert rules for Prometheus and Loki. You can export these rules using the following command, where o11y_alertrules_dest is the directory where the files should me placed.

ansible-playbook --extra-vars="o11y_alertrules_dest=/tmp" ./alertrules.yaml

The resulting files (loki-alert-rules.yml and prometheus-alert-rules.yml) should be installed in the Loki and Prometheus servers respectively. See https://maas.io/docs/how-to-monitor-maas for a basic observability stack setup.