How to enable Vault

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

2) 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

3) 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

4) 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

5) 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.

NOTE: 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:

NOTE:
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: