github.com/smintz/nomad@v0.8.3/website/source/docs/agent/configuration/vault.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "vault Stanza - Agent Configuration" 4 sidebar_current: "docs-agent-configuration-vault" 5 description: |- 6 The "vault" stanza configures Nomad's integration with HashiCorp's Vault. 7 When configured, Nomad can create and distribute Vault tokens to tasks 8 automatically. 9 --- 10 11 # `vault` Stanza 12 13 <table class="table table-bordered table-striped"> 14 <tr> 15 <th width="120">Placement</th> 16 <td> 17 <code>**vault**</code> 18 </td> 19 </tr> 20 </table> 21 22 23 The `vault` stanza configures Nomad's integration with [HashiCorp's 24 Vault][vault]. When configured, Nomad can create and distribute Vault tokens to 25 tasks automatically. For more information on the architecture and setup, please 26 see the [Nomad and Vault integration documentation][nomad-vault]. 27 28 ```hcl 29 vault { 30 enabled = true 31 address = "https://vault.company.internal:8200" 32 } 33 ``` 34 35 ## `vault` Parameters 36 37 - `address` - `(string: "https://vault.service.consul:8200")` - Specifies the 38 address to the Vault server. This must include the protocol, host/ip, and port 39 given in the format `protocol://host:port`. If your Vault installation is 40 behind a load balancer, this should be the address of the load balancer. 41 42 - `allow_unauthenticated` `(bool: true)` - Specifies if users submitting jobs to 43 the Nomad server should be required to provide their own Vault token, proving 44 they have access to the policies listed in the job. This option should be 45 disabled in an untrusted environment. 46 47 - `enabled` `(bool: false)` - Specifies if the Vault integration should be 48 activated. 49 50 - `create_from_role` `(string: "")` - Specifies the role to create tokens from. 51 The token given to Nomad does not have to be created from this role but must 52 have "update" capability on "auth/token/create/<create_from_role>" path in 53 Vault. If this value is unset and the token is created from a role, the value 54 is defaulted to the role the token is from. This is largely for backwards 55 compatibility. It is recommended to set the `create_from_role` field if Nomad 56 is deriving child tokens from a role. 57 58 - `task_token_ttl` `(string: "")` - Specifies the TTL of created tokens when 59 using a root token. This is specified using a label suffix like "30s" or "1h". 60 61 - `ca_file` `(string: "")` - Specifies an optional path to the CA 62 certificate used for Vault communication. If unspecified, this will fallback 63 to the default system CA bundle, which varies by OS and version. 64 65 - `ca_path` `(string: "")` - Specifies an optional path to a folder 66 containing CA certificates to be used for Vault communication. If unspecified, 67 this will fallback to the default system CA bundle, which varies by OS and 68 version. 69 70 - `cert_file` `(string: "")` - Specifies the path to the certificate used 71 for Vault communication. If this is set then you need to also set 72 `tls_key_file`. 73 74 - `key_file` `(string: "")` - Specifies the path to the private key used for 75 Vault communication. If this is set then you need to also set `cert_file`. 76 77 - `tls_server_name` `(string: "")` - Specifies an optional string used to set 78 the SNI host when connecting to Vault via TLS. 79 80 - `tls_skip_verify` `(bool: false)` - Specifies if SSL peer validation should be 81 enforced. 82 83 !> It is **strongly discouraged** to disable SSL verification. Instead, you 84 should install a custom CA bundle and validate against it. Disabling SSL 85 verification can allow an attacker to easily compromise your cluster. 86 87 - `token` `(string: "")` - Specifies the parent Vault token to use to derive child tokens for jobs 88 requesting tokens. 89 Visit the [Vault Integration](/docs/vault-integration/index.html) 90 documentation to see how to generate an appropriate token in Vault. 91 92 !> It is **strongly discouraged** to place the token as a configuration 93 parameter like this, since the token could be checked into source control 94 accidentally. Users should set the `VAULT_TOKEN` environment variable when 95 starting the agent instead. 96 97 98 ## `vault` Examples 99 100 The following examples only show the `vault` stanzas. Remember that the 101 `vault` stanza is only valid in the placements listed above. 102 103 ### Nomad Server 104 105 This example shows an example Vault configuration for a Nomad server: 106 107 ```hcl 108 vault { 109 enabled = true 110 ca_path = "/etc/certs/ca" 111 cert_file = "/var/certs/vault.crt" 112 key_file = "/var/certs/vault.key" 113 114 # Address to communicate with Vault. The below is the default address if 115 # unspecified. 116 address = "https://vault.service.consul:8200" 117 118 # Embedding the token in the configuration is discouraged. Instead users 119 # should set the VAULT_TOKEN environment variable when starting the Nomad 120 # agent 121 token = "debecfdc-9ed7-ea22-c6ee-948f22cdd474" 122 123 # Setting the create_from_role option causes Nomad to create tokens for tasks 124 # via the provided role. This allows the role to manage what policies are 125 # allowed and disallowed for use by tasks. 126 create_from_role = "nomad-cluster" 127 } 128 ``` 129 130 ### Nomad Client 131 132 This example shows an example Vault configuration for a Nomad client: 133 134 ```hcl 135 vault { 136 enabled = true 137 address = "https://vault.service.consul:8200" 138 ca_path = "/etc/certs/ca" 139 cert_file = "/var/certs/vault.crt" 140 key_file = "/var/certs/vault.key" 141 } 142 ``` 143 144 The key difference is that the token is not necessary on the client. 145 146 ## `vault` Configuration Reloads 147 148 The Vault configuration can be reloaded on servers. This can be useful if a new 149 token needs to be given to the servers without having to restart them. A reload 150 can be accomplished by sending the process a `SIGHUP` signal. 151 152 [vault]: https://www.vaultproject.io/ "Vault by HashiCorp" 153 [nomad-vault]: /docs/vault-integration/index.html "Nomad Vault Integration"