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.