github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/configuration/vault.mdx (about)

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