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

     1  ---
     2  layout: "docs"
     3  page_title: "Connect - Certificate Management"
     4  sidebar_current: "docs-connect-ca-consul"
     5  description: |-
     6    Consul ships with a built-in CA system so that Connect can be easily enabled out of the box. The built-in CA generates and stores the root certificate and private key on Consul servers. It can also be configured with a custom certificate and private key if needed.
     7  ---
     8  
     9  # Built-In CA
    10  
    11  Consul ships with a built-in CA system so that Connect can be
    12  easily enabled out of the box. The built-in CA generates and stores the
    13  root certificate and private key on Consul servers. It can also be
    14  configured with a custom certificate and private key if needed.
    15  
    16  If Connect is enabled and no CA provider is specified, the built-in
    17  CA is the default provider used. The provider can be
    18  [updated and rotated](/docs/connect/ca.html#root-certificate-rotation)
    19  at any point to migrate to a new provider.
    20  
    21  -> This page documents the specifics of the built-in CA provider.
    22  Please read the [certificate management overview](/docs/connect/ca.html)
    23  page first to understand how Consul manages certificates with configurable
    24  CA providers.
    25  
    26  ## Configuration
    27  
    28  The built-in CA provider has no required configuration. Enabling Connect
    29  alone will configure the built-in CA provider and will automatically generate
    30  a root certificate and private key:
    31  
    32  ```hcl
    33  connect {
    34    enabled = true
    35  }
    36  ```
    37  
    38  A number of optional configuration options are supported. The
    39  first key is the value used in API calls while the second key (after the `/`)
    40  is used if configuring in an agent configuration file.
    41  
    42    * `PrivateKey` / `private_key` (`string: ""`) - A PEM-encoded private key
    43      for signing operations. This must match the private key used for the root
    44      certificate if it is manually specified. If this is blank, a private key
    45      is automatically generated.
    46  
    47    * `RootCert` / `root_cert` (`string: ""`) - A PEM-encoded root certificate
    48      to use. If this is blank, a root certificate is automatically generated
    49      using the private key specified. If this is specified, the certificate
    50      must be a valid
    51      [SPIFFE SVID signing certificate](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md)
    52      and the URI in the SAN must match the cluster identifier created at
    53      bootstrap with the ".consul" TLD. The cluster identifier can be found
    54      using the [CA List Roots endpoint](/api/connect/ca.html#list-ca-root-certificates).
    55  
    56  There are also [common CA configuration options](/docs/agent/options.html#common-ca-config-options)
    57  that are supported by all CA providers.
    58  
    59  ## Specifying a Custom Private Key and Root Certificate
    60  
    61  By default, a root certificate and private key will be automatically
    62  generated during the cluster's bootstrap. It is possible to configure
    63  the Consul CA provider to use a specific private key and root certificate.
    64  This is particularly useful if you have an external PKI system that doesn't
    65  currently integrate with Consul directly.
    66  
    67  To view the current CA configuration, use the [Get CA Configuration endpoint]
    68  (/api/connect/ca.html#get-ca-configuration):
    69  
    70  ```bash
    71  $ curl localhost:8500/v1/connect/ca/configuration
    72  {
    73      "Provider": "consul",
    74      "Config": {
    75          "LeafCertTTL": "72h",
    76          "RotationPeriod": "2160h"
    77      },
    78      "CreateIndex": 5,
    79      "ModifyIndex": 5
    80  }
    81  ```
    82  
    83  This is the default Connect CA configuration if nothing is explicitly set when
    84  Connect is enabled - the PrivateKey and RootCert fields have not been set, so those have
    85  been generated (as seen above in the roots list).
    86  
    87  There are two ways to have the Consul CA use a custom private key and root certificate:
    88  either through the `ca_config` section of the [Agent configuration]
    89  (/docs/agent/options.html#connect_ca_config) (which can only be used during the cluster's
    90  initial bootstrap) or through the [Update CA Configuration endpoint]
    91  (/api/connect/ca.html#update-ca-configuration).
    92  
    93  Currently consul requires that root certificates are valid [SPIFFE SVID Signing certificates]
    94  (https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded
    95  in the SAN is the cluster identifier created at bootstrap with the ".consul" TLD. In this
    96  example, we will set the URI SAN to `spiffe://36cb52cd-4058-f811-0432-6798a240c5d3.consul`.
    97  
    98  In order to use the Update CA Configuration HTTP endpoint, the private key and certificate
    99  must be passed via JSON:
   100  
   101  ```bash
   102  $ jq -n --arg key "$(cat root.key)"  --arg cert "$(cat root.crt)" '
   103  {
   104      "Provider": "consul",
   105      "Config": {
   106          "LeafCertTTL": "72h",
   107          "PrivateKey": $key,
   108          "RootCert": $cert,
   109          "RotationPeriod": "2160h"
   110      }
   111  }' > ca_config.json
   112  ```
   113  
   114  The resulting `ca_config.json` file can then be used to update the active root certificate:
   115  
   116  ```bash
   117  $ cat ca_config.json
   118  {
   119    "Provider": "consul",
   120    "Config": {
   121      "LeafCertTTL": "72h",
   122      "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEArqiy1c3pbT3cSkjdEM1APALUareU...",
   123      "RootCert": "-----BEGIN CERTIFICATE-----\nMIIDijCCAnKgAwIBAgIJAOFZ66em1qC7MA0GCSqGSIb3...",
   124      "RotationPeriod": "2160h"
   125    }
   126  }
   127  
   128  $ curl --request PUT --data @ca_config.json localhost:8500/v1/connect/ca/configuration
   129  
   130  ...
   131  
   132  [INFO] connect: CA rotated to new root under provider "consul"
   133  ```
   134  
   135  The cluster is now using the new private key and root certificate. Updating the CA config
   136  this way also triggered a certificate rotation.