How to use HashiCorp Vault with 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

The 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 --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 --> Secret Storage.

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:

How to unseal Vault

There are two conditions that may cause Vault-protected 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.

Hashicorp Vault is integrated with MAAS version 3.3. To enable Vault for use with your MAAS, please upgrade to MAAS 3.3.

Might be a dumb question but, why would you need Vault for MAAS?