status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

website: split out CA docs by provider type

This commit is contained in:
Mitchell Hashimoto 2018-06-24 16:55:26 -05:00 committed by Jack Pearkes
parent 3289b0d281
commit 93cd52024d
4 changed files with 286 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
website/source/docs/connect/ca.html.md
View File

@ -8,30 +8,53 @@ description: |-
# Connect Certificate Management # Connect Certificate Management
The certificate management in Connect is done centrally through the Consul Certificate management in Connect is done centrally through the Consul
servers using the configured CA (Certificate Authority) provider. A CA provider servers using the configured CA (Certificate Authority) provider. A CA provider
controls the active root certificate and performs leaf certificate signing for manages root and intermediate certificates and performs certificate signing
proxies to use for mutual TLS. Currently, the only supported provider is the operations. The Consul leader orchestrates CA provider operations as necessary,
built-in Consul CA, which generates and stores the root certificate and key on such as when a service needs a new certificate or during CA rotation events.
the Consul servers and can be configured with a custom key/certificate if needed.
The CA provider is initialized either on cluster bootstrapping, or (if Connect is The CA provider abstraction enables Consul to support multiple systems for
disabled initially) when a leader server is elected that has Connect enabled. storing and signing certificates. Consul ships with a
During the cluster's initial bootstrapping, the CA provider can be configured [built-in CA](/docs/connect/ca/consul.html) which generates and stores the
through the [Agent configuration](docs/agent/options.html#connect_ca_config) root certificate and private key on the Consul servers. Consul also also
and afterward can only be updated through the [Update CA Configuration endpoint] built-in support for
(/api/connect/ca.html#update-ca-configuration). [Vault as a CA](/docs/connect/ca/vault.html). With Vault, the root certificate
and private key material remain with the Vault cluster. A future version of
Consul will support pluggable CA systems using external binaries.
### Consul CA (Certificate Authority) Provider ## CA Bootstrapping
By default, if no provider is configured when Connect is enabled, the Consul CA initialization happens automatically when a new Consul leader is elected
provider will be used and a private key/root certificate will be generated as long as
and used as the active root certificate for the cluster. To see this in action, [Connect is enabled](/docs/connect/configuration.html#enable-connect-on-the-cluster)
start Consul in [dev mode](/docs/agent/options.html#_dev) and query the and the CA system hasn't already been initialized. This initialization process
[list CA Roots endpoint](/api/connect/ca.html#list-ca-root-certificates): will generate the initial root certificates and setup the internal Consul server
state.
For the initial bootstrap, the CA provider can be configured through the
[Agent configuration](docs/agent/options.html#connect_ca_config). After
initialization, the CA can only be updated through the
[Update CA Configuration API endpoint](/api/connect/ca.html#update-ca-configuration).
If a CA is already initialized, any changes to the CA configuration in the
agent configuration file (including removing the configuration completely)
will have no effect.
If no specific provider is configured when Connect is enabled, the built-in
Consul CA provider will be used and a private key and root certificate will
be generated automatically.
## Viewing Root Certificates
Root certificates can be queried with the
[list CA Roots endpoint](/api/connect/ca.html#list-ca-root-certificates).
With this endpoint, you can see the list of currently trusted root certificates.
When a cluster first initializes, this will only list one trusted root. Multiple
roots may appear as part of
[rotation](#).
```bash ```bash
$ curl localhost:8500/v1/connect/ca/roots $ curl http://localhost:8500/v1/connect/ca/roots
{ {
"ActiveRootID": "31:6c:06:fb:49:94:42:d5:e4:55:cc:2e:27:b3:b2:2e:96:67:3e:7e", "ActiveRootID": "31:6c:06:fb:49:94:42:d5:e4:55:cc:2e:27:b3:b2:2e:96:67:3e:7e",
"TrustDomain": "36cb52cd-4058-f811-0432-6798a240c5d3.consul", "TrustDomain": "36cb52cd-4058-f811-0432-6798a240c5d3.consul",
@ -53,17 +76,15 @@ $ curl localhost:8500/v1/connect/ca/roots
} }
``` ```
#### Specifying a Private Key and Root Certificate ## CA Configuration
The above root certificate has been automatically generated during the cluster's After initialization, the CA provider configuration can be viewed with the
bootstrap, but it is possible to configure the Consul CA provider to use a specific [Get CA Configuration API endpoint](/api/connect/ca.html#get-ca-configuration).
private key and root certificate. Consul will filter sensitive values from this endpoint depending on the
provider in use, so the configuration may not be complete.
To view the current CA configuration, use the [Get CA Configuration endpoint]
(/api/connect/ca.html#get-ca-configuration):
```bash ```bash
$ curl localhost:8500/v1/connect/ca/configuration $ curl http://localhost:8500/v1/connect/ca/configuration
{ {
"Provider": "consul", "Provider": "consul",
"Config": { "Config": {
@ -74,66 +95,23 @@ $ curl localhost:8500/v1/connect/ca/configuration
} }
``` ```
This is the default Connect CA configuration if nothing is explicitly set when The CA provider can be reconfigured using the
Connect is enabled - the PrivateKey and RootCert fields have not been set, so those have [Update CA Configuration API endpoint](/api/connect/ca.html#update-ca-configuration).
been generated (as seen above in the roots list). Specific options for reconfiguration can be found in the specific
CA provider documentation in the sidebar to the left.
There are two ways to have the Consul CA use a custom private key and root certificate: ## Root Certificate Rotation
either through the `ca_config` section of the [Agent configuration]
(docs/agent/options.html#connect_ca_config) (which can only be used during the cluster's
initial bootstrap) or through the [Update CA Configuration endpoint]
(/api/connect/ca.html#update-ca-configuration).
Currently consul requires that root certificates are valid [SPIFFE SVID Signing certificates]
(https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded
in the SAN is the cluster identifier created at bootstrap with the ".consul" TLD. In this
example, we will set the URI SAN to `spiffe://36cb52cd-4058-f811-0432-6798a240c5d3.consul`.
In order to use the Update CA Configuration HTTP endpoint, the private key and certificate
must be passed via JSON:
```bash
$ jq -n --arg key "$(cat root.key)" --arg cert "$(cat root.crt)" '
{
"Provider": "consul",
"Config": {
"PrivateKey": $key,
"RootCert": $cert,
"RotationPeriod": "2160h"
}
}' > ca_config.json
```
The resulting `ca_config.json` file can then be used to update the active root certificate:
```bash
$ cat ca_config.json
{
"Provider": "consul",
"Config": {
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEArqiy1c3pbT3cSkjdEM1APALUareU...",
"RootCert": "-----BEGIN CERTIFICATE-----\nMIIDijCCAnKgAwIBAgIJAOFZ66em1qC7MA0GCSqGSIb3...",
"RotationPeriod": "2160h"
}
}
$ curl --request PUT --data @ca_config.json localhost:8500/v1/connect/ca/configuration
...
[INFO] connect: CA rotated to new root under provider "consul"
```
The cluster is now using the new private key and root certificate. Updating the CA config
this way also triggered a certificate rotation, which will be covered in the next section.
#### Root Certificate Rotation
Whenever the CA's configuration is updated in a way that causes the root key to Whenever the CA's configuration is updated in a way that causes the root key to
change, a special rotation process will be triggered in order to smoothly transition to change, a special rotation process will be triggered in order to smoothly transition to
the new certificate. the new certificate. This rotation is automatically orchestrated by Consul.
First, an intermediate CA certificate is requested from the new root, which is then This also automatically occurs when a completely different CA provider is
configured (since this changes the root key). Therefore, this automatic rotation
process can also be used to cleanly transition between CA providers. For example,
updating Connect to use Vault instead of the built-in CA.
During rotation, an intermediate CA certificate is requested from the new root, which is then
cross-signed by the old root. This cross-signed certificate is then distributed cross-signed by the old root. This cross-signed certificate is then distributed
alongside any newly-generated leaf certificates used by the proxies once the new root alongside any newly-generated leaf certificates used by the proxies once the new root
becomes active, and provides a chain of trust back to the old root certificate in the becomes active, and provides a chain of trust back to the old root certificate in the
@ -145,7 +123,7 @@ certificate or CA provider has been set up, the new root becomes the active one
and is immediately used for signing any new incoming certificate requests. and is immediately used for signing any new incoming certificate requests.
If we check the [list CA roots endpoint](/api/connect/ca.html#list-ca-root-certificates) If we check the [list CA roots endpoint](/api/connect/ca.html#list-ca-root-certificates)
after the config update in the previous section, we can see both the old and new root after updating the configuration with a new root certificate, we can see both the old and new root
certificates are present, and the currently active root has an intermediate certificate certificates are present, and the currently active root has an intermediate certificate
which has been generated and cross-signed automatically by the old root during the which has been generated and cross-signed automatically by the old root during the
rotation process: rotation process:
@ -190,58 +168,3 @@ $ curl localhost:8500/v1/connect/ca/roots
The old root certificate will be automatically removed once enough time has elapsed The old root certificate will be automatically removed once enough time has elapsed
for any leaf certificates signed by it to expire. for any leaf certificates signed by it to expire.
### External CA (Certificate Authority) Providers
#### Vault
Currently, the only supported external CA (Certificate Authority) provider is Vault. The
Vault provider can be used by setting the `ca_provider = "vault"` field in the Connect
configuration:
```hcl
connect {
enabled = true
ca_provider = "vault"
ca_config {
address = "http://localhost:8200"
token = "..."
root_pki_path = "connect-root"
intermediate_pki_path = "connect-intermediate"
}
}
```
The `root_pki_path` can be set to either a new or existing PKI backend; if no CA has been
initialized at the path, a new root CA will be generated. From this root PKI, Connect will
generate an intermediate CA at `intermediate_pki_path`. This intermediate CA is used so that
Connect can manage its lifecycle/rotation - it will never touch or overwrite any existing data
at `root_pki_path`. The intermediate CA is used for signing leaf certificates used by the
services and proxies in Connect to verify identity.
To update the configuration for the Vault provider, the process is the same as for the Consul CA
provider above: use the [Update CA Configuration endpoint](/api/connect/ca.html#update-ca-configuration)
or the `consul connect ca set-config` command:
```bash
$ cat ca_config.json
{
"Provider": "vault",
"Config": {
"Address": "http://localhost:8200",
"Token": "...",
"RootPKIPath": "connect-root-2",
"IntermediatePKIPath": "connect-intermediate"
}
}
$ consul connect ca set-config -config-file=ca_config.json
...
[INFO] connect: CA rotated to new root under provider "vault"
```
If the PKI backend at `connect-root-2` in this case has a different root certificate (or if it's
unmounted and hasn't been initialized), the rotation process will be triggered, as described above
in the [Root Certificate Rotation](#root-certificate-rotation) section.

129
website/source/docs/connect/ca/consul.html.md Normal file
View File

@ -0,0 +1,129 @@
---
layout: "docs"
page_title: "Connect - Certificate Management"
sidebar_current: "docs-connect-ca-consul"
description: |-
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.
---
# Built-In CA
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.
If Connect is enabled and no CA provider is specified, the built-in
CA is the default provider used. The provider can be
[updated and rotated](/docs/connect/ca.html#root-certificate-rotation)
at any point to migrate to a new provider.
-> This page documents the specifics of the built-in CA provider.
Please read the [certificate management overview](/docs/connect/ca.html)
page first to understand how Consul manages certificates with configurable
CA providers.
## Configuration
The built-in CA provider has no required configuration. Enabling Connect
alone will configure the built-in CA provider and will automatically generate
a root certificate and private key:
```hcl
connect {
enabled = true
}
```
A number of optional configuration options are supported. The
first key is the value used in API calls while the second key (after the `/`)
is used if configuring in an agent configuration file.
* `PrivateKey` / `private_key` (`string: ""`) - A PEM-encoded private key
for signing operations. This must match the private key used for the root
certificate if it is manually specified. If this is blank, a private key
is automatically generated.
* `RootCert` / `root_cert` (`string: ""`) - A PEM-encoded root certificate
to use. If this is blank, a root certificate is automatically generated
using the private key specified. If this is specified, the certificate
must be a valid
[SPIFFE SVID signing certificate](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md)
and the URI in the SAN must match the cluster identifier created at
bootstrap with the ".consul" TLD.
## Specifying a Custom Private Key and Root Certificate
By default, a root certificate and private key will be automatically
generated during the cluster's bootstrap. It is possible to configure
the Consul CA provider to use a specific private key and root certificate.
This is particularly useful if you have an external PKI system that doesn't
currently integrate with Consul directly.
To view the current CA configuration, use the [Get CA Configuration endpoint]
(/api/connect/ca.html#get-ca-configuration):
```bash
$ curl localhost:8500/v1/connect/ca/configuration
{
"Provider": "consul",
"Config": {
"RotationPeriod": "2160h"
},
"CreateIndex": 5,
"ModifyIndex": 5
}
```
This is the default Connect CA configuration if nothing is explicitly set when
Connect is enabled - the PrivateKey and RootCert fields have not been set, so those have
been generated (as seen above in the roots list).
There are two ways to have the Consul CA use a custom private key and root certificate:
either through the `ca_config` section of the [Agent configuration]
(docs/agent/options.html#connect_ca_config) (which can only be used during the cluster's
initial bootstrap) or through the [Update CA Configuration endpoint]
(/api/connect/ca.html#update-ca-configuration).
Currently consul requires that root certificates are valid [SPIFFE SVID Signing certificates]
(https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded
in the SAN is the cluster identifier created at bootstrap with the ".consul" TLD. In this
example, we will set the URI SAN to `spiffe://36cb52cd-4058-f811-0432-6798a240c5d3.consul`.
In order to use the Update CA Configuration HTTP endpoint, the private key and certificate
must be passed via JSON:
```bash
$ jq -n --arg key "$(cat root.key)" --arg cert "$(cat root.crt)" '
{
"Provider": "consul",
"Config": {
"PrivateKey": $key,
"RootCert": $cert,
"RotationPeriod": "2160h"
}
}' > ca_config.json
```
The resulting `ca_config.json` file can then be used to update the active root certificate:
```bash
$ cat ca_config.json
{
"Provider": "consul",
"Config": {
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEArqiy1c3pbT3cSkjdEM1APALUareU...",
"RootCert": "-----BEGIN CERTIFICATE-----\nMIIDijCCAnKgAwIBAgIJAOFZ66em1qC7MA0GCSqGSIb3...",
"RotationPeriod": "2160h"
}
}
$ curl --request PUT --data @ca_config.json localhost:8500/v1/connect/ca/configuration
...
[INFO] connect: CA rotated to new root under provider "consul"
```
The cluster is now using the new private key and root certificate. Updating the CA config
this way also triggered a certificate rotation.

88
website/source/docs/connect/ca/vault.html.md Normal file
View File

@ -0,0 +1,88 @@
---
layout: "docs"
page_title: "Connect - Certificate Management"
sidebar_current: "docs-connect-ca-vault"
description: |-
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.
---
# Vault as a Connect CA
Consul can be used with [Vault](https://www.vaultproject.io) to
manage and sign certificates.
The Vault CA provider uses the
[Vault PKI secrets engine](https://www.vaultproject.io/docs/secrets/pki/index.html)
to generate and sign certificates.
-> This page documents the specifics of the built-in CA provider.
Please read the [certificate management overview](/docs/connect/ca.html)
page first to understand how Consul manages certificates with configurable
CA providers.
## Requirements
Prior to using Vault as a CA provider for Consul, the following requirements
must be met:
* **Vault 0.10.3 or later.** Consul uses URI SANs in the PKI engine which
were introduced in Vault 0.10.3. Prior versions of Vault are not
compatible with Connect.
## Configuration
The Vault CA is enabled by setting the `ca_provider` to `"vault"` and
setting the required configuration values. An example configuration
is shown below:
```hcl
connect {
enabled = true
ca_provider = "vault"
ca_config {
address = "http://localhost:8200"
token = "..."
root_pki_path = "connect-root"
intermediate_pki_path = "connect-intermediate"
}
}
```
The set of configuration options is listed below. The
first key is the value used in API calls while the second key (after the `/`)
is used if configuring in an agent configuration file.
* `Address` / `address` (`string: <required>`) - The address of the Vault
server.
* `Token` / `token` (`string: <required>`) - A token for accessing Vault.
This is write-only and will not be exposed when reading the CA configuration.
This token must have proper privileges for the PKI paths configured.
* `RootPKIPath` / `root_pki_path` (`string: <required>`) - The path to
a PKI secrets engine for the root certificate. If the path doesn't
exist, Consul will attempt to mount and configure this automatically.
* `IntermediatePKIPath` / `intermediate_pki_path` (`string: <required>`) -
The path to a PKI secrets engine for the generated intermediate certificate.
This certificate will be signed by the configured root PKI path. If this
path doesn't exist, Consul will attempt to mount and configure this
automatically.
## Root and Intermediate PKI Paths
The Vault CA provider uses two separately configured
[PKI secrets engines](https://www.vaultproject.io/docs/secrets/pki/index.html)
for managing Connect certificates.
The `RootPKIPath` is the PKI engine for the root certificate. Consul will
use this root certificate to sign the intermediate certificate. Consul will
never attempt to write or modify any data within the root PKI path.
The `IntermediatePKIPath` is the PKI engine used for storing the intermediate
signed with the root certificate. The intermediate is used to sign all leaf
certificates and Consul may periodically generate new intermediates for
automatic rotation. Therefore, Consul requires write access to this path.
If either path does not exist, then Consul will attempt to mount and
initialize it. This requires additional privileges by the Vault token in use.
If the paths already exist, Consul will use them as configured.

8
website/source/layouts/docs.erb
View File

@ -267,6 +267,14 @@
</li> </li>
<li<%= sidebar_current("docs-connect-ca") %>> <li<%= sidebar_current("docs-connect-ca") %>>
<a href="/docs/connect/ca.html">Certificate Management</a> <a href="/docs/connect/ca.html">Certificate Management</a>
<ul class="nav">
<li<%= sidebar_current("docs-connect-ca-consul") %>>
<a href="/docs/connect/ca/consul.html">Built-In CA</a>
</li>
<li<%= sidebar_current("docs-connect-ca-vault") %>>
<a href="/docs/connect/ca/vault.html">Vault</a>
</li>
</ul>
</li> </li>
<li<%= sidebar_current("docs-connect-native") %>> <li<%= sidebar_current("docs-connect-native") %>>
<a href="/docs/connect/native.html">Native App Integration</a> <a href="/docs/connect/native.html">Native App Integration</a>