mirror of
https://github.com/kemko/nomad.git
synced 2026-01-04 17:35:43 +03:00
0abe5a6c79
After a more detailed analysis of this feature, the approach taken in PR #12449 was found to be not ideal due to poor UX (users are responsible for setting the entity alias they would like to use) and issues around jobs potentially masquerading itself as another Vault entity.
153 lines
6.0 KiB
Plaintext
153 lines
6.0 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: vault Stanza - Agent Configuration
|
|
description: |-
|
|
The "vault" stanza configures Nomad's integration with HashiCorp's Vault.
|
|
When configured, Nomad can create and distribute Vault tokens to tasks
|
|
automatically.
|
|
---
|
|
|
|
# `vault` Stanza
|
|
|
|
<Placement groups={['vault']} />
|
|
|
|
The `vault` stanza configures Nomad's integration with [HashiCorp's
|
|
Vault][vault]. When configured, Nomad can create and distribute Vault tokens to
|
|
tasks automatically. For more information on the architecture and setup, please
|
|
see the [Nomad and Vault integration documentation][nomad-vault].
|
|
|
|
```hcl
|
|
vault {
|
|
enabled = true
|
|
address = "https://vault.company.internal:8200"
|
|
}
|
|
```
|
|
|
|
## `vault` Parameters
|
|
|
|
- `address` - `(string: "https://vault.service.consul:8200")` - Specifies the
|
|
address to the Vault server. This must include the protocol, host/ip, and port
|
|
given in the format `protocol://host:port`. If your Vault installation is
|
|
behind a load balancer, this should be the address of the load balancer.
|
|
|
|
- `allow_unauthenticated` `(bool: true)` - Specifies if users submitting jobs to
|
|
the Nomad server should be required to provide their own Vault token, proving
|
|
they have access to the policies listed in the job. This option should be
|
|
disabled in an untrusted environment.
|
|
|
|
- `enabled` `(bool: false)` - Specifies if the Vault integration should be
|
|
activated.
|
|
|
|
- `create_from_role` `(string: "")` - Specifies the role to create tokens from.
|
|
The token given to Nomad does not have to be created from this role but must
|
|
have "`update`" capability on "`auth/token/create/<create_from_role>`" path in
|
|
Vault. If this value is unset and the token is created from a role, the value
|
|
is defaulted to the role the token is from. This is largely for backwards
|
|
compatibility. It is recommended to set the `create_from_role` field if Nomad
|
|
is deriving child tokens from a role.
|
|
|
|
- `task_token_ttl` `(string: "72h")` - Specifies the TTL of created tokens when
|
|
using a root token. This is specified using a label suffix like "30s" or "1h".
|
|
|
|
- `ca_file` `(string: "")` - Specifies an optional path to the CA
|
|
certificate used for Vault communication. If unspecified, this will fallback
|
|
to the default system CA bundle, which varies by OS and version.
|
|
|
|
- `ca_path` `(string: "")` - Specifies an optional path to a folder
|
|
containing CA certificates to be used for Vault communication. If unspecified,
|
|
this will fallback to the default system CA bundle, which varies by OS and
|
|
version.
|
|
|
|
- `cert_file` `(string: "")` - Specifies the path to the certificate used for
|
|
Vault communication. This must be set if
|
|
[tls_require_and_verify_client_cert](https://www.vaultproject.io/docs/configuration/listener/tcp#tls_require_and_verify_client_cert)
|
|
is enabled in Vault.
|
|
|
|
- `key_file` `(string: "")` - Specifies the path to the private key used for
|
|
Vault communication. If this is set then you need to also set
|
|
`cert_file`. This must be set if
|
|
[tls_require_and_verify_client_cert](https://www.vaultproject.io/docs/configuration/listener/tcp#tls_require_and_verify_client_cert)
|
|
is enabled in Vault.
|
|
|
|
- `namespace` `(string: "")` - Specifies the [Vault namespace](https://www.vaultproject.io/docs/enterprise/namespaces)
|
|
used by the Vault integration. If non-empty, this namespace will be used on
|
|
all Vault API calls.
|
|
|
|
- `tls_server_name` `(string: "")` - Specifies an optional string used to set
|
|
the SNI host when connecting to Vault via TLS.
|
|
|
|
- `tls_skip_verify` `(bool: false)` - Specifies if SSL peer validation should be
|
|
enforced.
|
|
|
|
!> It is **strongly discouraged** to disable SSL verification. Instead, you
|
|
should install a custom CA bundle and validate against it. Disabling SSL
|
|
verification can allow an attacker to easily compromise your cluster.
|
|
|
|
- `token` `(string: "")` - Specifies the parent Vault token to use to derive
|
|
child tokens for jobs requesting tokens. Only required on Nomad servers.
|
|
Nomad client agents use the allocation's token when contacting Vault.
|
|
Visit the [Vault Integration Guide](/docs/vault-integration)
|
|
to see how to generate an appropriate token in Vault.
|
|
|
|
!> It is **strongly discouraged** to place the token as a configuration
|
|
parameter like this, since the token could be checked into source control
|
|
accidentally. Users should set the `VAULT_TOKEN` environment variable when
|
|
starting the agent instead.
|
|
|
|
## `vault` Examples
|
|
|
|
The following examples only show the `vault` stanzas. Remember that the
|
|
`vault` stanza is only valid in the placements listed above.
|
|
|
|
### Nomad Server
|
|
|
|
This example shows an example Vault configuration for a Nomad server:
|
|
|
|
```hcl
|
|
vault {
|
|
enabled = true
|
|
ca_path = "/etc/certs/ca"
|
|
cert_file = "/var/certs/vault.crt"
|
|
key_file = "/var/certs/vault.key"
|
|
|
|
# Address to communicate with Vault. The below is the default address if
|
|
# unspecified.
|
|
address = "https://vault.service.consul:8200"
|
|
|
|
# Embedding the token in the configuration is discouraged. Instead users
|
|
# should set the VAULT_TOKEN environment variable when starting the Nomad
|
|
# agent
|
|
token = "debecfdc-9ed7-ea22-c6ee-948f22cdd474"
|
|
|
|
# Setting the create_from_role option causes Nomad to create tokens for tasks
|
|
# via the provided role. This allows the role to manage what policies are
|
|
# allowed and disallowed for use by tasks.
|
|
create_from_role = "nomad-cluster"
|
|
}
|
|
```
|
|
|
|
### Nomad Client
|
|
|
|
This example shows an example Vault configuration for a Nomad client:
|
|
|
|
```hcl
|
|
vault {
|
|
enabled = true
|
|
address = "https://vault.service.consul:8200"
|
|
ca_path = "/etc/certs/ca"
|
|
cert_file = "/var/certs/vault.crt"
|
|
key_file = "/var/certs/vault.key"
|
|
}
|
|
```
|
|
|
|
The key difference is that the token is not necessary on the client.
|
|
|
|
## `vault` Configuration Reloads
|
|
|
|
The Vault configuration can be reloaded on servers. This can be useful if a new
|
|
token needs to be given to the servers without having to restart them. A reload
|
|
can be accomplished by sending the process a `SIGHUP` signal.
|
|
|
|
[vault]: https://www.vaultproject.io/ 'Vault by HashiCorp'
|
|
[nomad-vault]: /docs/vault-integration 'Nomad Vault Integration'
|