From 8e028b7dc64a79ae401d64f62a519519c39c9e9c Mon Sep 17 00:00:00 2001 From: Kyle Havlovitz Date: Tue, 19 Jun 2018 17:51:21 -0700 Subject: [PATCH] website: add Vault CA provider doc sections --- website/source/docs/agent/options.html.md | 27 +++++++++-- website/source/docs/connect/ca.html.md | 55 ++++++++++++++++++++++- 2 files changed, 76 insertions(+), 6 deletions(-) diff --git a/website/source/docs/agent/options.html.md b/website/source/docs/agent/options.html.md index 2ff49d3f64..cd16f90f37 100644 --- a/website/source/docs/agent/options.html.md +++ b/website/source/docs/agent/options.html.md @@ -679,9 +679,9 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass servers in the cluster in order for Connect to function properly. Defaults to false. * `ca_provider` Controls - which CA provider to use for Connect's CA. Currently only `consul` is supported. This is only - used when initially bootstrapping the cluster. For an existing cluster, use the [Update CA - Configuration Endpoint](/api/connect/ca.html#update-ca-configuration). + which CA provider to use for Connect's CA. Currently only the `consul` and `vault` providers + are supported. This is only used when initially bootstrapping the cluster. For an existing + cluster, use the [Update CA Configuration Endpoint](/api/connect/ca.html#update-ca-configuration). * `ca_config` An object which allows setting different config options based on the CA provider chosen. This is only @@ -690,7 +690,7 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass The following providers are supported: - ### Consul CA Provider + #### Consul CA Provider (`ca_provider = "consul"`) * `private_key` The PEM contents of the private key to use for the CA. @@ -703,6 +703,25 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass duration value such as `720h`. Only applies in the case where the private key or root certificate are left blank. Defaults to `2160h` (90 days). + #### Vault CA Provider (`ca_provider = "vault"`) + + * `address` The address of the Vault + server to connect to. + + * `token` The Vault token to use. + + * `root_pki_path` The + path to use for the root CA pki backend in Vault. This can be an existing backend with a CA already + configured, or a blank/unmounted backend in which case Connect will automatically mount/generate the CA. + The Vault token given above must have `sudo` access to this backend, as well as permission to mount + the backend at this path if it is not already mounted. + + * `intermediate_pki_path` + The path to use for the temporary intermediate CA pki backend in Vault. *Connect will overwrite any data + at this path in order to generate a temporary intermediate CA*. The Vault token given above must have + `write` access to this backend, as well as permission to mount the backend at this path if it is not + already mounted. + * `proxy` This object allows setting options for the Connect proxies. The following sub-keys are available: * `allow_managed_api_registration` Allows managed proxies to be configured with services that are registered via the Agent HTTP API. Enabling this would allow anyone with permission to register a service to define a command to execute for the proxy. By default, this is false to protect against arbitrary process execution. diff --git a/website/source/docs/connect/ca.html.md b/website/source/docs/connect/ca.html.md index b38eda585b..544263ca81 100644 --- a/website/source/docs/connect/ca.html.md +++ b/website/source/docs/connect/ca.html.md @@ -193,6 +193,57 @@ $ curl localhost:8500/v1/connect/ca/roots The old root certificate will be automatically removed once enough time has elapsed for any leaf certificates signed by it to expire. -### External CA (Certificate Authority) Providers (Vault) +### External CA (Certificate Authority) Providers -TODO \ No newline at end of file +#### 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 = "..." + root_pki_path = "connect-root-2" + intermediate_pki_path = "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.