github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Add common CA config options to provider doc pages (#10842) 

Add the list of common Connect CA configuration options to the
provider-specific CA docs.

Previously these options were only documented under the agent
configuration options. This change makes it so that all supported CA
provider configuration options are available from a single location.

Co-authored-by: Daniel Nephin <dnephin@hashicorp.com>
pull/10954/head^2
Blake Covarrubias 2021-08-19 11:18:55 -07:00 committed by hc-github-team-consul-core
parent 9e66894892
commit 95af6ff6f3
6 changed files with 233 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
website/content/docs/agent/options.mdx
View File

@ -1159,7 +1159,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
through mesh gateways. Defaults to false. This was added in Consul 1.8.0.
- `ca_provider` ((#connect_ca_provider)) Controls which CA provider to
use for Connect's CA. Currently only the `consul` and `vault` providers are supported.
use for Connect's CA. Currently only the `aws-pca`, `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#update-ca-configuration).
@ -1170,6 +1170,12 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
The following providers are supported:
#### AWS ACM Private CA Provider (`ca_provider = "aws-pca"`)
- `existing_arn` ((#aws_ca_existing_arn)) The Amazon Resource Name (ARN) of
an existing private CA in your ACM account. If specified, Consul will
attempt to use the existing CA to issue certificates.
#### Consul CA Provider (`ca_provider = "consul"`)
- `private_key` ((#consul_ca_private_key)) The PEM contents of the
@ -1206,34 +1212,33 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
There are also a number of common configuration options supported by all providers:
- `csr_max_concurrent` ((#ca_csr_max_concurrent)) Sets a limit on how
many Certificate Signing Requests will be processed concurrently. Defaults
to 0 (disabled). This is useful when you have more than one or two cores available
to the server. For example on an 8 core server, setting this to 1 will ensure
that even during a CA rotation no more than one server core on the leader will
be consumed at a time with generating new certificates. Setting this is recommended
**instead** of `csr_max_per_second` where you know there are multiple cores available
since it is simpler to reason about limiting CSR resources this way without
artificially slowing down rotations. Added in 1.4.1.
- `csr_max_concurrent` ((#ca_csr_max_concurrent)) Sets a limit on the number
of Certificate Signing Requests that can be processed concurrently. Defaults
to 0 (disabled). This is useful when you want to limit the number of CPU cores
available to the server for certificate signing operations. For example, on an
8 core server, setting this to 1 will ensure that no more than one CPU core
will be consumed when generating or rotating certificates. Setting this is
recommended **instead** of `csr_max_per_second` when you want to limit the
number of cores consumed since it is simpler to reason about limiting CSR
resources this way without artificially slowing down rotations. Added in 1.4.1.
- `csr_max_per_second` ((#ca_csr_max_per_second)) Sets a rate limit
on the maximum number of Certificate Signing Requests (CSRs) the servers will
accept. This is used to prevent CA rotation from causing unbounded CPU usage
on servers. It defaults to 50 which is conservative - a 2017 Macbook can process
about 100 per second using only ~40% of one CPU core - but sufficient for deployments
on servers. It defaults to 50 which is conservative – a 2017 Macbook can process
about 100 per second using only ~40% of one CPU core – but sufficient for deployments
up to ~1500 service instances before the time it takes to rotate is impacted.
For larger deployments we recommend increasing this based on the expected number
of server instances and server resources, or use `csr_max_concurrent` instead
if servers have more than one core. Setting this to zero disables rate limiting.
if servers have more than one CPU core. Setting this to zero disables rate limiting.
Added in 1.4.1.
- `leaf_cert_ttl` ((#ca_leaf_cert_ttl)) The upper bound on the lease
duration of a leaf certificate issued for a service. In most cases a new leaf
certificate will be requested by a proxy before this limit is reached. This
is also the effective limit on how long a server outage can last (with no leader)
before network connections will start being rejected, and as a result the defaults
is `72h` to last through a weekend without intervention. This value cannot
be lower than 1 hour or higher than 1 year.
before network connections will start being rejected. Defaults to `72h`.
This value cannot be lower than 1 hour or higher than 1 year.
This value is also used when rotating out old root certificates from
the cluster. When a root certificate has been inactive (rotated out)
@ -1246,9 +1251,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
PKI paths given for Vault then this will be ignored. Currently supported options
are `ec` or `rsa`. Default is `ec`.
It is required that all servers in a Datacenter have
It is required that all servers in a datacenter have
the same config for the CA. It is recommended that servers in
different Datacenters have the same CA config for key type and size
different datacenters use the same key type and size,
although the built-in CA and Vault provider will both allow mixed CA
key types.
@ -1735,7 +1740,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
failover if this is increased significantly as more logs will need to be
replayed. In Consul 1.1.0 and later this defaults to 16384, and in prior
versions it was set to 8192.
Since Consul 1.10.0 this can be reloaded using `consul reload` or sending the
server a `SIGHUP` to allow tuning snapshot activity without a rolling restart
in emergencies.
@ -1751,7 +1756,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
is increased significantly as more logs will need to be replayed. In Consul
1.1.0 and later this defaults to `30s`, and in prior versions it was set to
`5s`.
Since Consul 1.10.0 this can be reloaded using `consul reload` or sending the
server a `SIGHUP` to allow tuning snapshot activity without a rolling restart
in emergencies.
@ -1764,10 +1769,10 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
consider reducing write throughput or the amount of data stored on Consul as
it is likely under a load it is not designed to handle. The default value is
10000 which is suitable for all normal workloads. Added in Consul 1.5.3.
Since Consul 1.10.0 this can be reloaded using `consul reload` or sending the
server a `SIGHUP` to allow recovery without downtime when followers can't keep
up.
up.
- `reap` This controls Consul's automatic reaping of child processes,
which is useful if Consul is running as PID 1 in a Docker container. If this isn't

55
website/content/docs/connect/ca/aws.mdx
View File

@ -43,10 +43,19 @@ The IAM credential provided must have permission for the following actions:
## Configuration
The ACM Private CA provider is enabled by setting the `ca_provider` to
`"aws-pca"`. At this time there is only one, optional configuration value.
The ACM Private CA provider is enabled by setting the CA provider to
`"aws-pca"` in the agent's [`ca_provider`] configuration option, or via the
[`/connect/ca/configuration`] API endpoint. At this time there is only one,
optional configuration value.
Example configurations are shown below:
<CodeTabs heading="Connect CA configuration" tabs={["Agent configuration", "API"]}>
<CodeBlockConfig filename="/etc/consul.d/config.hcl" highlight="4,6">
```hcl
# ...
connect {
enabled = true
ca_provider = "aws-pca"
@ -56,14 +65,33 @@ connect {
}
```
~> Note that suitable AWS IAM credentials are necessary for the provider to
work, however these are not configured in the Consul config which is typically
on disk and rely on the [standard AWS SDK configuration
</CodeBlockConfig>
<CodeBlockConfig highlight="2,4">
```json
{
"Provider": "aws-pca",
"Config": {
"ExistingARN": "arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-123456789012"
}
}
```
</CodeBlockConfig>
</CodeTabs>
~> **Note**: Suitable AWS IAM credentials are necessary for the provider to
work. However, these are not configured in the Consul config which is typically
on disk, and instead rely on the [standard AWS SDK configuration
locations](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials).
The configuration options are listed below. Note, the
first key is the value used in API calls and the second key (after the `/`)
is used if you're adding configuring to the agent's configuration file.
The configuration options are listed below.
-> **Note**: The first key is the value used in API calls, and the second key
(after the `/`) is used if you are adding the configuration to the agent's
configuration file.
- `ExistingARN` / `existing_arn` (`string: <optional>`) - The Amazon Resource
Name (ARN) of an existing private CA in your ACM account. If specified,
@ -76,10 +104,12 @@ is used if you're adding configuring to the agent's configuration file.
root, Consul will automatically create a new subordinate signed by the
primary's root instead.
The default behavior with no `ExistingArn` specified is for Consul to
The default behavior with no `ExistingARN` specified is for Consul to
create a new root CA in the primary datacenter and a subordinate CA in
each secondary DC.
@include 'http_api_connect_ca_common_options.mdx'
## Limitations
ACM Private CA has several
@ -93,7 +123,7 @@ limitations described below.
### Unable to Cross-sign Other CAs
It's not possible to cross-sign other CA provider's root certificates during a
migration. ACM Private CA is capable of doing that through a different work flow
migration. ACM Private CA is capable of doing that through a different workflow
but is not able to blindly cross-sign another root certificate without a CSR
being generated. Both Consul's built-in CA and Vault can do this and the current
workflow for managing CAs relies on it.
@ -146,3 +176,8 @@ The number of certificates issued could be reduced by increasing
[`leaf_cert_ttl`](/docs/agent/options#ca_leaf_cert_ttl) in the CA Provider
configuration if the longer lived credentials are an acceptable risk tradeoff
against the cost.
<!-- Reference style links -->
[`ca_config`]: /docs/agent/options#connect_ca_config
[`ca_provider`]: /docs/agent/options#connect_ca_provider
[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration

20
website/content/docs/connect/ca/consul.mdx
View File

@ -28,18 +28,25 @@ 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
alone will configure the built-in CA provider, and will automatically generate
a root certificate and private key:
<CodeBlockConfig filename="/etc/consul.d/config.hcl">
```hcl
# ...
connect {
enabled = true
}
```
The configuration options are listed below. Note, the
first key is the value used in API calls and the second key (after the `/`)
is used if you're adding configuring to the agent's configuration file.
</CodeBlockConfig>
The configuration options are listed below.
-> **Note**: The first key is the value used in API calls, and the second key
(after the `/`) is used if you are adding the configuration to the agent's
configuration file.
- `PrivateKey` / `private_key` (`string: ""`) - A PEM-encoded private key
for signing operations. This must match the private key used for the root
@ -55,8 +62,7 @@ is used if you're adding configuring to the agent's configuration file.
bootstrap with the ".consul" TLD. The cluster identifier can be found
using the [CA List Roots endpoint](/api/connect/ca#list-ca-root-certificates).
There are also [common CA configuration options](/docs/agent/options#common-ca-config-options)
that are supported by all CA providers.
@include 'http_api_connect_ca_common_options.mdx'
## Specifying a Custom Private Key and Root Certificate
@ -89,7 +95,7 @@ There are two ways to have the Consul CA use a custom private key and root certi
either through the `ca_config` section of the [Agent configuration](/docs/agent/options#connect_ca_config) (which can only be used during the cluster's
initial bootstrap) or through the [Update CA Configuration endpoint](/api/connect/ca#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
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`.

6
website/content/docs/connect/ca/index.mdx
View File

@ -16,7 +16,7 @@ The CA provider abstraction enables Consul to support multiple systems for
storing and signing certificates. Consul ships with a
[built-in CA](/docs/connect/ca/consul) which generates and stores the
root certificate and private key on the Consul servers. Consul also has
built-in support for
support for using
[Vault as a CA](/docs/connect/ca/vault). With Vault, the root certificate
and private key material remain with the Vault cluster.
@ -24,8 +24,8 @@ and private key material remain with the Vault cluster.
CA initialization happens automatically when a new Consul leader is elected
as long as
[Connect is enabled](/docs/connect/configuration#agent-configuration)
and the CA system hasn't already been initialized. This initialization process
[Connect is enabled](/docs/connect/configuration#agent-configuration),
and the CA system has not already been initialized. This initialization process
will generate the initial root certificates and setup the internal Consul server
state.

98
website/content/docs/connect/ca/vault.mdx
View File

@ -30,45 +30,80 @@ must be met:
## 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:
The Vault CA is enabled by setting the CA provider to `"vault"` and
setting the required configuration values.
The configuration may either be provided in the agent's configuration file using
the [`ca_provider`] and [`ca_config`] options, or configured using the
[`/connect/ca/configuration`] API endpoint.
Example configurations are shown below:
<CodeTabs heading="Connect CA configuration" tabs={["Agent configuration", "API"]}>
<CodeBlockConfig filename="/etc/consul.d/config.hcl" highlight="4,6-9">
```hcl
# ...
connect {
enabled = true
ca_provider = "vault"
ca_config {
address = "http://localhost:8200"
token = "..."
root_pki_path = "connect-root"
intermediate_pki_path = "connect-intermediate"
}
enabled = true
ca_provider = "vault"
ca_config {
address = "http://localhost:8200"
token = "..."
root_pki_path = "connect-root"
intermediate_pki_path = "connect-intermediate"
}
}
```
The configuration options are listed below. Note, the
first key is the value used in API calls and the second key (after the `/`)
is used if you're adding configuring to the agent's configuration file.
</CodeBlockConfig>
<CodeBlockConfig highlight="2,4-7">
```json
{
"Provider": "vault",
"Config": {
"Address": "http://localhost:8200",
"Token": "<token>",
"RootPKIPath": "connect-root",
"IntermediatePKIPath": "connect-intermediate"
}
}
```
</CodeBlockConfig>
</CodeTabs>
The configuration options are listed below.
-> **Note**: The first key is the value used in API calls, and the second key
(after the `/`) is used if you are adding the configuration to the agent's
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. In Consul
1.8.5 and later, if the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable)
This token must have [proper privileges](#vault-acl-policies) for the PKI
paths configured. In Consul 1.8.5 and later, if the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable)
flag set, Consul will attempt to renew its lease periodically after half the
duration has expired.
- `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.
a PKI secrets engine for the root certificate. If the path does not
exist, Consul will mount a new PKI secrets engine at the specified path with
a [`max_lease_ttl`](https://www.vaultproject.io/api/system/mounts#max_lease_ttl)
of 8760 hours, or 1 year. This TTL value specifies the expiry period of the
root certificate and is currently not configurable.
- `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
path does not exist, Consul will attempt to mount and configure this
automatically.
- `CAFile` / `ca_file` (`string: ""`) - Specifies an optional path to the CA
@ -81,12 +116,12 @@ is used if you're adding configuring to the agent's configuration file.
varies by OS and version.
- `CertFile` / `cert_file` (`string: ""`) - Specifies the path to the
certificate used for Vault communication. If this is set then you need to
also set tls_key_file.
certificate used for Vault communication. If this is set, then you also need to
set `key_file`.
- `KeyFile` / `key_file` (`string: ""`) - Specifies the path to the private
key used for Vault communication. If this is set then you need to also set
cert_file.
key used for Vault communication. If this is set, then you also need to set
`cert_file`.
- `TLSServerName` / `tls_server_name` (`string: ""`) - Specifies an optional
string used to set the SNI host when connecting to Vault via TLS.
@ -94,6 +129,8 @@ is used if you're adding configuring to the agent's configuration file.
- `TLSSkipVerify` / `tls_skip_verify` (`bool: false`) - Specifies if SSL peer
validation should be enforced.
@include 'http_api_connect_ca_common_options.mdx'
## Root and Intermediate PKI Paths
The Vault CA provider uses two separately configured
@ -124,6 +161,8 @@ granted full control of the Intermediate or Leaf CA for Connect clients.
In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
is `connect_inter`. These values should be updated for your environment.
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
```hcl
# Existing PKI Mounts
path "/sys/mounts" {
@ -153,12 +192,14 @@ path "/connect_inter/*" {
path "auth/token/renew-self" {
capabilities = [ "update" ]
}
path "auth/token/lookup-self" {
capabilities = [ "read" ]
}
```
</CodeBlockConfig>
### Consul Managed PKI Paths
The following Vault policy allows Consul to create and manage the PKI paths in Vault.
@ -168,6 +209,8 @@ control of the Root and Intermediate or Leaf CA for Connect clients.
In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
is `connect_inter`. These values should be updated for your environment.
<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
```hcl
# Consul Managed PKI Mounts
path "/sys/mounts" {
@ -190,3 +233,10 @@ path "/connect_inter/*" {
capabilities = [ "create", "read", "update", "delete", "list" ]
}
```
</CodeBlockConfig>
<!-- Reference style links -->
[`ca_config`]: /docs/agent/options#connect_ca_config
[`ca_provider`]: /docs/agent/options#connect_ca_provider
[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration

71
website/content/partials/http_api_connect_ca_common_options.mdx Normal file
View File

@ -0,0 +1,71 @@
#### Common CA Config Options
The following configuration options are supported by all CA providers:
- `CSRMaxConcurrent` / `csr_max_concurrent` (`int: 0`) - Sets a limit on the
number of Certificate Signing Requests that can be processed concurrently. Defaults
to 0 (disabled). This is useful when you want to limit the number of CPU cores
available to the server for certificate signing operations. For example, on an
8 core server, setting this to 1 will ensure that no more than one CPU core
will be consumed when generating or rotating certificates. Setting this is
recommended **instead** of `csr_max_per_second` when you want to limit the
number of cores consumed since it is simpler to reason about limiting CSR
resources this way without artificially slowing down rotations. Added in 1.4.1.
- `CSRMaxPerSecond` / `csr_max_per_second` (`float: 50`) - Sets a rate limit
on the maximum number of Certificate Signing Requests (CSRs) the servers will
accept. This is used to prevent CA rotation from causing unbounded CPU usage
on servers. It defaults to 50 which is conservative – a 2017 MacBook can process
about 100 per second using only ~40% of one CPU core – but sufficient for deployments
up to ~1500 service instances before the time it takes to rotate is impacted.
For larger deployments we recommend increasing this based on the expected number
of server instances and server resources, or use `csr_max_concurrent` instead
if servers have more than one CPU core. Setting this to zero disables rate limiting.
Added in 1.4.1.
- `LeafCertTTL` / `leaf_cert_ttl` (`duration: "72h"`) - The upper bound on the lease
duration of a leaf certificate issued for a service. In most cases a new leaf
certificate will be requested by a proxy before this limit is reached. This
is also the effective limit on how long a server outage can last (with no leader)
before network connections will start being rejected. Defaults to `72h`. This
value cannot be lower than 1 hour or higher than 1 year.
This value is also used when rotating out old root certificates from
the cluster. When a root certificate has been inactive (rotated out)
for more than twice the _current_ `leaf_cert_ttl`, it will be removed
from the trusted list.
- `PrivateKeyType` / `private_key_type` (`string: "ec"`) - The type of key to generate
for this CA. This is only used when the provider is generating a new key. If
`private_key` is set for the Consul provider, or existing root or intermediate
PKI paths given for Vault then this will be ignored. Currently supported options
are `ec` or `rsa`. Default is `ec`.
It is required that all servers in a datacenter have
the same config for the CA. It is recommended that servers in
different datacenters use the same key type and size, although the built-in CA
and Vault provider will both allow mixed CA key types.
Some CA providers (currently Vault) will not allow cross-signing a
new CA certificate with a different key type. This means that if you
migrate from an RSA-keyed Vault CA to an EC-keyed CA from any
provider, you may have to proceed without cross-signing which risks
temporary connection issues for workloads during the new certificate
rollout. We highly recommend testing this outside of production to
understand the impact, and suggest sticking to same key type where
possible.
-> **Note**: This only affects _CA_ keys generated by the provider.
Leaf certificate keys are always EC 256 regardless of the CA
configuration.
- `PrivateKeyBits` / `private_key_bits` (`string: ""`) - The length of key to
generate for this CA. This is only used when the provider is generating a new
key. If `private_key` is set for the Consul provider, or existing root or intermediate
PKI paths given for Vault then this will be ignored.
Currently supported values are:
- `private_key_type = ec` (default): `224, 256, 384, 521`
corresponding to the NIST P-\* curves of the same name.
- `private_key_type = rsa`: `2048, 4096`