transit keyring
The Vault transit keyring configures Nomad to use Vault's Transit Secret Engine to wrap its keyring. This example shows configuring Vault Transit through the Nomad configuration file by providing all the required values:
keyring "transit" {
active = true
name = "example"
# fields specific to transit
address = "https://vault:8200"
token = "s.Qf1s5zigZ4OX6akYjQXJC1jY"
disable_renewal = "false"
// Key configuration
key_name = "transit_key_name"
mount_path = "transit/"
namespace = "ns1/"
// TLS Configuration
tls_ca_cert = "/etc/vault/ca_cert.pem"
tls_client_cert = "/etc/vault/client_cert.pem"
tls_client_key = "/etc/vault/ca_cert.pem"
tls_server_name = "vault"
tls_skip_verify = "false"
}
transit
parameters
These parameters apply to the keyring
stanza in the Nomad configuration file:
key_name
(string: <required>)
: The transit key to use for encryption and decryption.key_id_prefix
(string: "")
: An optional string to add to the key id of values wrapped by this transit keyring. This can help disambiguate between two transit keyring.mount_path
(string: <required>)
: The mount path to the transit secret engine.disable_renewal
(string: "false")
: Disables the automatic renewal of the token in case the lifecycle of the token is managed with some other mechanism outside of Vault, such as Vault Agent.
The following parameters can be set in the keyring
block but will fallback to
the values set in the server's vault
block if not set
here. Fields indicated as required must be set either here or the vault
block.
address
(string: <required>)
: The full address to the Vault cluster. This may also be specified by theVAULT_ADDR
environment variable.token
(string: <required>)
: The Vault token to use. This may also be specified by theVAULT_TOKEN
environment variable.namespace
(string: "")
: The namespace path to the transit secret engine. This may also be supplied using theVAULT_NAMESPACE
environment variable.tls_ca_cert
(string: "")
: Specifies the path to the CA certificate file used for communication with the Vault server. This may also be specified using theVAULT_CACERT
environment variable.tls_client_cert
(string: "")
: Specifies the path to the client certificate for communication with the Vault server. This may also be specified using theVAULT_CLIENT_CERT
environment variable.tls_client_key
(string: "")
: Specifies the path to the private key for communication with the Vault server. This may also be specified using theVAULT_CLIENT_KEY
environment variable.tls_server_name
(string: "")
: Name to use as the SNI host when connecting to the Vault server via TLS. This may also be specified via theVAULT_TLS_SERVER_NAME
environment variable.tls_skip_verify
(bool: "false")
: Disable verification of TLS certificates. Using this option is highly discouraged and decreases the security of data transmissions to and from the Vault server. This may also be specified using theVAULT_SKIP_VERIFY
environment variable.
Authentication
Authentication-related values must be provided, either as environment variables or as configuration parameters.
Note: Although the configuration file allows you to pass in VAULT_TOKEN
as part of the keyring's parameters, it is strongly recommended to set these
values via environment variables.
The Vault token used to authenticate needs the following permissions on the transit key:
path "<mount path>/encrypt/<key name>" {
capabilities = ["update"]
}
path "<mount path>/decrypt/<key name>" {
capabilities = ["update"]
}
Other considerations for the token used:
- It should probably be an orphan token, otherwise when the parent token expires or gets revoked the keyring will break.
- Consider making it a periodic token and not setting an explicit max TTL, otherwise at some point it will cease to be renewable.
Key rotation
This keyring supports key rotation using the Transit Secret Engine's key rotation endpoints. See doc. Old keys must not be disabled or deleted and are used to decrypt older data.