How to use Vault to protect your MAAS secrets

As a MAAS administrator, you do not want secrets associated with a MAAS instance to be stored in the database, since it often doesn’t comply with security regulations. Examples of the MAAS settings which contain secrets are the OMAPI key and the RPC secret. Beginning with version 3.3, MAAS secrets should instead be stored in HashiCorp Vault.

Examples of such secrets are

  • Database connection credentials
  • Shared RPC key
  • OMAPI key
  • BMC power credentials (password, keys and certificates) for machines
  • VMhost credentials
  • Macaroon keys

Configuring Vault for MAAS

For MAAS to be able to integrate with Vault, a few steps are required. Specifically, you must get a role_id and wrapped_token via Vault CLI (follow the instructions from Hashicorp Vault).

As an example only, MAAS can be configured by a Vault admin using the vault CLI.

  1. The approle engine must be enabled. This can be checked with:
$ vault auth list

You should verify that it’s mounted under approle/. If not, it can be enabled via:

$ vault auth enable approle
  1. The KV v2 engine is mounted under the desired path (secret/ by default, but can be configured as desired). A new KV engine can be mounted with:
$ vault secrets enable -path $SECRETS_MOUNT kv-v2
  1. An appropriate policy that can be assigned to approles configured in MAAS should be configured, providing read/write access to the secrets paths that MAAS will use. As an example, here is a minimal policy:
path "$SECRETS_MOUNT/metadata/$SECRETS_PATH/" {
	capabilities = ["list"]

path "$SECRETS_MOUNT/metadata/$SECRETS_PATH/*" {
	capabilities = ["read", "update", "delete", "list"]

path "$SECRETS_MOUNT/data/${SECRETS_PATH}/*" {
	capabilities = ["read", "create", "update", "delete"]

Here, $SECRETS_PATH is the desired path prefix under which MAAS will store secrets. This, together with $SECRETS_MOUNT, will be used when configuring MAAS later. Such a policy can be created in Vault as follows (assuming it was written to $POLICY_FILE):

$ vault policy write $MAAS_POLICY $POLICY_FILE
  1. For each MAAS region controller, create a role using the policy created above:
$ vault write auth/approle/role/$ROLE_NAME \
policies=$MAAS_POLICY token_ttl=5m

Tthe TTL for tokens can be tweaked as desired.

While it’s technically possible to use the same approle for all controllers, it’s suggested to use different ones for each. This increases security and reduces exposure in case credentials are leaked from one controller.

Fetch the role ID for the created role with the following command:

$ vault read auth/approle/role/$ROLE_NAME/role-id
  1. For each created role, create a secret ID, returned with a wrapping token. This, together with the role ID, will be provided to the MAAS controller:
$ vault write -wrap-ttl=5m auth/approle/role/$ROLE_NAME/secret-id

Integrating Vault with MAAS

Once MAAS is installed and configured, it’s possible to integrate it with Vault with a few steps, using the CLI:

sudo maas config-vault configure $URL $APPROLE_ID $WRAPPED_TOKEN $SECRETS_PATH --secrets-mount $SECRET_MOUNT

where the $APPROLE_ID and $WRAPPED_TOKEN are the ones obtained by Vault in the previous steps.

This operation must be performed on each region controller before the integration process can continue.

Once this operation has been performed on all region controllers, it’s possible to migrate secrets to Vault and complete the integration process, with the following command:

$ sudo maas config-vault migrate

During migration, MAAS might be offline for a few seconds, but it will refresh quickly. After this command, MAAS will be fully integrated and functional with Vault. You can confirm success in the UI by checking Settings → Configuration → Security:

If you try to migrate secrets before all region controllers are configured with Vault, the migrate command will fail with an error message.

If you’ve configured all region controllers with Vault, but haven’t yet migrated the secrets, the integration process will simply remain incomplete. The UI will remind you:


When the Vault is sealed

There are two conditions that may cause secrets to become unavailable: when the Vault is sealed (using vault operator seal – see the Vault documentation and when the Vault is unreachable through misconfiguration or other failure.

When the Vault is sealed, all queries involving secrets will fail with a user error mentioning that the Vault has been sealed. Unsealing the Vault requires operator intervention, via the vault operator unseal command (again, see the Vault documentation. MAAS will indicate when this is needed.

Vault may become unreachable due to a network failure, due to incorrect configuration of a region controller, or other unintentional situations. When the Vault is unreachable, MAAS will inform the users that interactions with Vault will fail.

MAAS will make every attempt to present a meaningful error if Vault is not functional. This includes related authentication errors when attempting to login to MAAS.

Updating secrets directly

Secrets related to MAAS stored in Vault could be changed outside of MAAS, directly in Vault. If this happens, MAAS automatically uses the new value, as MAAS elements do not cache secrets – they are fetched every time they’re needed.

MAAS deals with a number of secrets (user password, certificates and keys, API tokens, …). Those are currently stored in the database, which is not secure by default.

Hi all,

I have maas 3.3 installed

root@maas-ha-1:~# snap list
Name    Version                      Rev    Tracking       Publisher   Notes
core22  20221212                     469    latest/stable  canonical✓  base
maas    3.3.0~rc1-13127-g.e6737625f  25207  3.3/beta       canonical✓  -
snapd   2.58                         17950  latest/stable  canonical✓  snapd

I tried the following steps,

root@maas-ha-1:~# export APPROLE_ID=cd2b61f3-83ae-6cb9-532a-142c34e0547f
export SECRETS_PATH=maas
export URL=
export SECRET_MOUNT=secret
maas config-vault configure $URL $APPROLE_ID $WRAPPED_TOKEN $SECRETS_PATH --mount $SECRET_MOUNT

The output I keep getting is:

CommandError: no handler for route "secret/data/maas/test-cd2b61f3-83ae-6cb9-532a-142c34e0547f". route entry not found., on post --mount $SECRET_MOUNT

What did I do wrong in this case?

I have upgraded my maas 3.2 to 3.3 to integrate vault

i tried the following commands
export URL=
export APPROLE_ID= 93b4fff3-8885-ee7e-281e-95fa2be8416e
export SECRETS_PATH=maas
export SECRET_MOUNT=secrets
sudo maas config-vault configure $URL $APPROLE_ID $WRAPPED_TOKEN $SECRETS_PATH --secrets-mount $SECRET_MOUNT
i am getting following error:
No connection adapters were found for ‘url=’
any help is appreciated

putting it for others, the issue was solved when I ran vault as a systemctl service.

This topic was automatically closed 365 days after the last reply. New replies are no longer allowed.