Local configuration¶

Each node needs credentials for the Vault server. By default, minions pull their configuration and credentials from the Salt master, so only the master itself needs to be configured with explicit credentials.

Minions can opt out of master-provided configuration by setting config_location to local. This guide describes how to set up a single node – master or minion – with explicit credentials.

Vault-side setup¶

Statically configured credentials can either be an AppRole or a token. Using AppRoles is generally recommended; see the section on static auth methods in the auth FAQ for details.

Important

The following shows basic examples of how to create the necessary resources to get you rolling quickly. It does not necessarily represent recommended practices, specifically regarding token/SecretID validity.

AppRole¶

If you chose to authenticate your node via an AppRole, follow these steps:

If not present yet, enable a mount of the AppRole auth backend:
```
vault auth enable -path=approle approle
```

Create an AppRole for the node with the appropriate policies:

vault write auth/approle/role/salt-master \
  token_policies=salt-master \
  secret_id_num_uses=0 \
  secret_id_ttl=720h \
  token_ttl=30m \
  token_max_ttl=0

Look up its RoleID and generate a SecretID:

# Show RoleID
vault read auth/approle/role/salt-master/role-id
# Generate new SecretID
vault write -f auth/approle/role/salt-master/secret-id

Token¶

Alternatively, if you chose to authenticate your node via a token, just create one with the appropriate policies:

vault token create -policy=salt-master

Note

These examples assume you are setting up a Salt master for credential orchestration, hence the association with a salt-master policy. The required contents of this policy depend on the type of issued credentials; see the Token issuance and AppRole issuance guides. For other nodes, substitute names and policies as appropriate.

Node configuration¶

All parameters for this extension should be put under the vault key inside the configuration.

Minions that should use their local configuration instead of requesting one from the master additionally need to set config_location to local, regardless of the authentication method:

/etc/salt/minion.d/vault.conf¶

vault:
  config_location: local

AppRole authentication¶

If you chose to authenticate your node via an AppRole, apply this configuration:

/etc/salt/{master,minion}.d/vault.conf¶

vault:
  auth:
    method: approle
    approle_mount: approle  # <-- mount the node authenticates at
    role_id: <your-role-id>
    secret_id: <your-secret-id>
  server:
    url: https://vault.example.org:8200

Token authentication¶

Alternatively, if you chose to authenticate your node via a token, apply this configuration:

/etc/salt/{master,minion}.d/vault.conf¶

vault:
  auth:
    token: <your-auth-token>
  server:
    url: https://vault.example.org:8200

Cache¶

For historical reasons, this extension currently defaults to not employing a persistent cache. This is a very inefficient setup and does not work with long-lived leases, so you should configure a persistent cache:

/etc/salt/{master,minion}.d/vault.conf¶

vault:
  cache:
    backend: disk  # synonyms: file, localfs

Advanced credential sources¶

The credential values (token, role_id and secret_id) do not need to be specified as plaintext.

They can be set to an sdb:// URI, e.g. to avoid persisting them in the configuration file by pulling them from environment variables:

/etc/salt/{master,minion}.d/vault.conf¶

vault:
  auth:
    method: token
    token: sdb://osenv/VAULT_TOKEN
  server:
    url: https://vault.example.org:8200

osenv:
  driver: env

In very specialized setups, they can furthermore be set to the complete return payload of a response wrapping request, which is unwrapped on first use. The payload must be embedded as a YAML mapping containing the wrap_info key, not as its raw string representation. For wrapped role_id/secret_id values, ensure auth:approle_mount and auth:approle_name match the AppRole the response was created for, since the wrapping token’s creation path is validated against them to detect tampering.

Complete config examples¶

Master¶

AppRole¶

/etc/salt/master.d/vault.conf¶

vault:
  auth:
    method: approle
    approle_mount: approle
    role_id: e5a7b66e-5d08-da9c-7075-71984634b882
    secret_id: 841771dc-11c9-bbc7-bcac-6a3945a69cd9

  cache:
    backend: disk

  server:
    url: https://vault.example.com:8200

Token¶

/etc/salt/master.d/vault.conf¶

vault:
  auth:
    token: hvs.CAESIK41QQzo5O0HNj4AZQhW_S7suut

  cache:
    backend: disk

  server:
    url: https://vault.example.com:8200

Minion¶

AppRole¶

/etc/salt/minion.d/vault.conf¶

vault:
  config_location: local

  auth:
    method: approle
    approle_mount: approle
    role_id: e5a7b66e-5d08-da9c-7075-71984634b882
    secret_id: 841771dc-11c9-bbc7-bcac-6a3945a69cd9

  cache:
    backend: disk

  server:
    url: https://vault.example.com:8200

Token¶

/etc/salt/minion.d/vault.conf¶

vault:
  config_location: local

  auth:
    token: hvs.CAESIK41QQzo5O0HNj4AZQhW_S7suut

  cache:
    backend: disk

  server:
    url: https://vault.example.com:8200