Enroling MAAS with MAAS Site Manager

Enroling MAAS with a MAAS Site Manager instance

Below, we detail how to enrol a MAAS region with a MAAS Site Manager instance. This process uses the Site Manager UI, but can be scripted as well.

Enrolment Tokens

In order for MAAS to enrol with Site Manager, it needs an enrolment JWT token. Encoded in the enrolment token is the URL that MAAS will use to enrol with Site Manager. To set this via the UI, (todo: how?).

Setting the enrolment URL via bash

First, retrieve a user token from Site Manager:

USER_TOKEN=curl -X POST https://${MSM_HOST}/api/v1/login -H "Content-Type: application/x-www-form-urlencoded" -d "username=${USERNAME}&password=${PASSWORD} | jq -r .access_token"

To set the enrolment URL:

curl -X PATCH http://${MSM_HOST}/api/v1/settings -H "Authorization: bearer ${USER_TOKEN}" -H "Content-Type: application/json" -d "{\"enrolment_url\":\"https://${MSM_HOST}/site/v1/enrol\"}"

Note: the protocol (http vs https) and hostname (MSM_HOST) can change based on your setup, but make sure to keep the /site/v1/enrol API path.

Generating an enrolment token

To generate an enrolment token via the Site Manager UI, head to the settings page and click “Tokens” on the left-hand side. Then, click “Generate tokens” and enter the number of tokens you’d like to generate and how long they should be accepted for. You only need one token per MAAS enrolment. Keep the expiration time relatively low (less than 1 hour), as tokens that have lengthy expiration times are a security risk.

Generating an enrolment token via bash

First, retrieve a user token from Site Manager. If you did this above when setting the enrolment URL, you can skip this step.

USER_TOKEN=curl -X POST https://${MSM_HOST}/api/v1/login -H "Content-Type: application/x-www-form-urlencoded" -d "username=${USERNAME}&password=${PASSWORD} | jq -r .access_token"

Next, generate an enrolment token:

curl -X POST https://${MSM_HOST}/api/v1/tokens -H "Authorization: bearer ${USER_TOKEN}" -H "Content-Type: application/json" -d "{\"count\":1,\"duration\":1800}" | jq -r .items[0].value

Make sure to copy this token somewhere temporary, as we will need it later.

Issuing the enrolment request

To issue the enrolment request, we will use the MAAS CLI. From the region controller machine, execute the following command:

sudo maas msm enrol ${ENROLMENT_TOKEN}

You can also supply a YAML file that includes metadata about the site you are enroling. An example is below:

  latitude: 40.05275079137782
  longitude: -107.17401328725524
  note: super awesome site
  country: US # Two-letter country code
  city: Town
  state: AK
  address: 123 Fake St.
  postal_code: '80205' # this is expected to be a string, use quotes
  timezone: US/Mountain # Must be a valid tz database timezone

To include this file in the enrolment command, include the full path to this file after the enrolment token, as such:

sudo maas msm enrol ${ENROLMENT_TOKEN} /path/to/yaml/config.yaml

If you have installed MAAS via snap, place the yaml file in the /var/snap/maas/current/ directory.

Accepting the enrolment request

In the Site Manager UI, click “Requests” from the left-hand side of the Settings page. To accept enrolment of your MAAS instance, check the box to the left of its name, then click “Accept” in the top-right corner.

Accepting the enrolment request via bash

First, retrieve the ID of the pending site. The command below assumes the site you are enroling is the last (most recent) pending site.

PENDING_ID=$(curl https://${MSM_HOST}/api/v1/sites/pending -H "Authorization: bearer ${USER_TOKEN}" | jq -r .items[-1].id)

Next, accept the pending site:

curl -X POST https://${MSM_HOST}/api/v1/sites/pending -H "Authorization: bearer ${USER_TOKEN}" -H "Content-Type: application/json" -d "{\"ids\": [${PENDING_ID}], \"accept\": true}"