github.com/outbrain/consul@v1.4.5/website/source/docs/connect/ca/vault.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Connect - Certificate Management"
     4  sidebar_current: "docs-connect-ca-vault"
     5  description: |-
     6    Consul can be used with Vault to manage and sign certificates. The Vault CA provider uses the Vault PKI secrets engine to generate and sign certificates.
     7  ---
     8  
     9  # Vault as a Connect CA
    10  
    11  Consul can be used with [Vault](https://www.vaultproject.io) to
    12  manage and sign certificates.
    13  The Vault CA provider uses the
    14  [Vault PKI secrets engine](https://www.vaultproject.io/docs/secrets/pki/index.html)
    15  to generate and sign certificates.
    16  
    17  -> This page documents the specifics of the built-in CA provider.
    18  Please read the [certificate management overview](/docs/connect/ca.html)
    19  page first to understand how Consul manages certificates with configurable
    20  CA providers.
    21  
    22  ## Requirements
    23  
    24  Prior to using Vault as a CA provider for Consul, the following requirements
    25  must be met:
    26  
    27    * **Vault 0.10.3 or later.** Consul uses URI SANs in the PKI engine which
    28      were introduced in Vault 0.10.3. Prior versions of Vault are not
    29      compatible with Connect.
    30  
    31  ## Configuration
    32  
    33  The Vault CA is enabled by setting the `ca_provider` to `"vault"` and
    34  setting the required configuration values. An example configuration
    35  is shown below:
    36  
    37  ```hcl
    38  connect {
    39      enabled = true
    40      ca_provider = "vault"
    41      ca_config {
    42          address = "http://localhost:8200"
    43          token = "..."
    44          root_pki_path = "connect-root"
    45          intermediate_pki_path = "connect-intermediate"
    46      }
    47  }
    48  ```
    49  
    50  The set of configuration options is listed below. The
    51  first key is the value used in API calls while the second key (after the `/`)
    52  is used if configuring in an agent configuration file.
    53  
    54    * `Address` / `address` (`string: <required>`) - The address of the Vault
    55      server.
    56  
    57    * `Token` / `token` (`string: <required>`) - A token for accessing Vault.
    58      This is write-only and will not be exposed when reading the CA configuration.
    59      This token must have proper privileges for the PKI paths configured.
    60  
    61    * `RootPKIPath` / `root_pki_path` (`string: <required>`) - The path to
    62      a PKI secrets engine for the root certificate. If the path doesn't
    63      exist, Consul will attempt to mount and configure this automatically.
    64  
    65    * `IntermediatePKIPath` / `intermediate_pki_path` (`string: <required>`) -
    66      The path to a PKI secrets engine for the generated intermediate certificate.
    67      This certificate will be signed by the configured root PKI path. If this
    68      path doesn't exist, Consul will attempt to mount and configure this
    69      automatically.
    70  
    71    * `CAFile` / `ca_file` (`string: ""`) - Specifies an optional path to the CA
    72      certificate used for Vault communication. If unspecified, this will fallback
    73      to the default system CA bundle, which varies by OS and version.
    74  
    75    * `CAPath` / `ca_path` (`string: ""`) - Specifies an optional path to a folder
    76      containing CA certificates to be used for Vault communication. If
    77      unspecified, this will fallback to the default system CA bundle, which
    78      varies by OS and version.
    79  
    80    * `CertFile` / `cert_file` (`string: ""`) - Specifies the path to the
    81      certificate used for Vault communication. If this is set then you need to
    82      also set tls_key_file.
    83  
    84    * `KeyFile` / `key_file` (`string: ""`) - Specifies the path to the private
    85      key used for Vault communication. If this is set then you need to also set
    86      cert_file.
    87  
    88    * `TLSServerName` / `tls_server_name` (`string: ""`) - Specifies an optional
    89      string used to set the SNI host when connecting to Vault via TLS.
    90  
    91    * `TLSSkipVerify` / `tls_skip_verify` (`bool: false`) - Specifies if SSL peer
    92      validation should be enforced.
    93  
    94  ## Root and Intermediate PKI Paths
    95  
    96  The Vault CA provider uses two separately configured
    97  [PKI secrets engines](https://www.vaultproject.io/docs/secrets/pki/index.html)
    98  for managing Connect certificates.
    99  
   100  The `RootPKIPath` is the PKI engine for the root certificate. Consul will
   101  use this root certificate to sign the intermediate certificate. Consul will
   102  never attempt to write or modify any data within the root PKI path.
   103  
   104  The `IntermediatePKIPath` is the PKI engine used for storing the intermediate
   105  signed with the root certificate. The intermediate is used to sign all leaf
   106  certificates and Consul may periodically generate new intermediates for
   107  automatic rotation. Therefore, Consul requires write access to this path.
   108  
   109  If either path does not exist, then Consul will attempt to mount and
   110  initialize it. This requires additional privileges by the Vault token in use.
   111  If the paths already exist, Consul will use them as configured.