status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
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>
This commit is contained in:
Blake Covarrubias 2021-08-19 11:18:55 -07:00 committed by GitHub
parent 39b3c3e2bd
commit e62b1d05d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
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

@ -1165,7 +1165,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. through mesh gateways. Defaults to false. This was added in Consul 1.8.0.
- `ca_provider` ((#connect_ca_provider)) Controls which CA provider to - `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, 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). use the [Update CA Configuration Endpoint](/api/connect/ca#update-ca-configuration).
@ -1176,6 +1176,12 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
The following providers are supported: 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"`) #### Consul CA Provider (`ca_provider = "consul"`)
- `private_key` ((#consul_ca_private_key)) The PEM contents of the - `private_key` ((#consul_ca_private_key)) The PEM contents of the
@ -1212,34 +1218,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: 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 - `csr_max_concurrent` ((#ca_csr_max_concurrent)) Sets a limit on the number
many Certificate Signing Requests will be processed concurrently. Defaults of Certificate Signing Requests that can be processed concurrently. Defaults
to 0 (disabled). This is useful when you have more than one or two cores available to 0 (disabled). This is useful when you want to limit the number of CPU cores
to the server. For example on an 8 core server, setting this to 1 will ensure available to the server for certificate signing operations. For example, on an
that even during a CA rotation no more than one server core on the leader will 8 core server, setting this to 1 will ensure that no more than one CPU core
be consumed at a time with generating new certificates. Setting this is recommended will be consumed when generating or rotating certificates. Setting this is
**instead** of `csr_max_per_second` where you know there are multiple cores available recommended **instead** of `csr_max_per_second` when you want to limit the
since it is simpler to reason about limiting CSR resources this way without number of cores consumed since it is simpler to reason about limiting CSR
artificially slowing down rotations. Added in 1.4.1. 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 - `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 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 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 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 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. 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 For larger deployments we recommend increasing this based on the expected number
of server instances and server resources, or use `csr_max_concurrent` instead 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. Added in 1.4.1.
- `leaf_cert_ttl` ((#ca_leaf_cert_ttl)) The upper bound on the lease - `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 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 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) 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 before network connections will start being rejected. Defaults to `72h`.
is `72h` to last through a weekend without intervention. This value cannot This value cannot be lower than 1 hour or higher than 1 year.
be lower than 1 hour or higher than 1 year.
This value is also used when rotating out old root certificates from This value is also used when rotating out old root certificates from
the cluster. When a root certificate has been inactive (rotated out) the cluster. When a root certificate has been inactive (rotated out)
@ -1252,9 +1257,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 PKI paths given for Vault then this will be ignored. Currently supported options
are `ec` or `rsa`. Default is `ec`. 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 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 although the built-in CA and Vault provider will both allow mixed CA
key types. key types.
@ -1752,7 +1757,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 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 replayed. In Consul 1.1.0 and later this defaults to 16384, and in prior
versions it was set to 8192. versions it was set to 8192.
Since Consul 1.10.0 this can be reloaded using `consul reload` or sending the 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 server a `SIGHUP` to allow tuning snapshot activity without a rolling restart
in emergencies. in emergencies.
@ -1768,7 +1773,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 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 1.1.0 and later this defaults to `30s`, and in prior versions it was set to
`5s`. `5s`.
Since Consul 1.10.0 this can be reloaded using `consul reload` or sending the 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 server a `SIGHUP` to allow tuning snapshot activity without a rolling restart
in emergencies. in emergencies.
@ -1781,10 +1786,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 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 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. 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 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 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, - `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 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 ## Configuration
The ACM Private CA provider is enabled by setting the `ca_provider` to 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. `"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 ```hcl
# ...
connect { connect {
enabled = true enabled = true
ca_provider = "aws-pca" ca_provider = "aws-pca"
@ -56,14 +65,33 @@ connect {
} }
``` ```
~> Note that suitable AWS IAM credentials are necessary for the provider to </CodeBlockConfig>
work, however these are not configured in the Consul config which is typically
on disk and rely on the [standard AWS SDK configuration <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). 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 The configuration options are listed below.
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. -> **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 - `ExistingARN` / `existing_arn` (`string: <optional>`) - The Amazon Resource
Name (ARN) of an existing private CA in your ACM account. If specified, 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 root, Consul will automatically create a new subordinate signed by the
primary's root instead. 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 create a new root CA in the primary datacenter and a subordinate CA in
each secondary DC. each secondary DC.
@include 'http_api_connect_ca_common_options.mdx'
## Limitations ## Limitations
ACM Private CA has several ACM Private CA has several
@ -93,7 +123,7 @@ limitations described below.
### Unable to Cross-sign Other CAs ### Unable to Cross-sign Other CAs
It's not possible to cross-sign other CA provider's root certificates during a 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 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 being generated. Both Consul's built-in CA and Vault can do this and the current
workflow for managing CAs relies on it. 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 [`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 configuration if the longer lived credentials are an acceptable risk tradeoff
against the cost. 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 ## Configuration
The built-in CA provider has no required configuration. Enabling Connect 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: a root certificate and private key:
<CodeBlockConfig filename="/etc/consul.d/config.hcl">
```hcl ```hcl
# ...
connect { connect {
enabled = true enabled = true
} }
``` ```
The configuration options are listed below. Note, the </CodeBlockConfig>
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.
- `PrivateKey` / `private_key` (`string: ""`) - A PEM-encoded private key - `PrivateKey` / `private_key` (`string: ""`) - A PEM-encoded private key
for signing operations. This must match the private key used for the root 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 bootstrap with the ".consul" TLD. The cluster identifier can be found
using the [CA List Roots endpoint](/api/connect/ca#list-ca-root-certificates). 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) @include 'http_api_connect_ca_common_options.mdx'
that are supported by all CA providers.
## Specifying a Custom Private Key and Root Certificate ## 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 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). 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 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`. 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 storing and signing certificates. Consul ships with a
[built-in CA](/docs/connect/ca/consul) which generates and stores the [built-in CA](/docs/connect/ca/consul) which generates and stores the
root certificate and private key on the Consul servers. Consul also has 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 [Vault as a CA](/docs/connect/ca/vault). With Vault, the root certificate
and private key material remain with the Vault cluster. 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 CA initialization happens automatically when a new Consul leader is elected
as long as as long as
[Connect is enabled](/docs/connect/configuration#agent-configuration) [Connect is enabled](/docs/connect/configuration#agent-configuration),
and the CA system hasn't already been initialized. This initialization process and the CA system has not already been initialized. This initialization process
will generate the initial root certificates and setup the internal Consul server will generate the initial root certificates and setup the internal Consul server
state. state.

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

@ -30,45 +30,80 @@ must be met:
## Configuration ## Configuration
The Vault CA is enabled by setting the `ca_provider` to `"vault"` and The Vault CA is enabled by setting the CA provider to `"vault"` and
setting the required configuration values. An example configuration setting the required configuration values.
is shown below:
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 ```hcl
# ...
connect { connect {
enabled = true enabled = true
ca_provider = "vault" ca_provider = "vault"
ca_config { ca_config {
address = "http://localhost:8200" address = "http://localhost:8200"
token = "..." token = "..."
root_pki_path = "connect-root" root_pki_path = "connect-root"
intermediate_pki_path = "connect-intermediate" intermediate_pki_path = "connect-intermediate"
} }
} }
``` ```
The configuration options are listed below. Note, the </CodeBlockConfig>
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 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 - `Address` / `address` (`string: <required>`) - The address of the Vault
server. server.
- `Token` / `token` (`string: <required>`) - A token for accessing Vault. - `Token` / `token` (`string: <required>`) - A token for accessing Vault.
This is write-only and will not be exposed when reading the CA configuration. 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 This token must have [proper privileges](#vault-acl-policies) for the PKI
1.8.5 and later, if the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable) 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 flag set, Consul will attempt to renew its lease periodically after half the
duration has expired. duration has expired.
- `RootPKIPath` / `root_pki_path` (`string: <required>`) - The path to - `RootPKIPath` / `root_pki_path` (`string: <required>`) - The path to
a PKI secrets engine for the root certificate. If the path doesn't a PKI secrets engine for the root certificate. If the path does not
exist, Consul will attempt to mount and configure this automatically. 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>`) - - `IntermediatePKIPath` / `intermediate_pki_path` (`string: <required>`) -
The path to a PKI secrets engine for the generated intermediate certificate. 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 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. automatically.
- `CAFile` / `ca_file` (`string: ""`) - Specifies an optional path to the CA - `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. varies by OS and version.
- `CertFile` / `cert_file` (`string: ""`) - Specifies the path to the - `CertFile` / `cert_file` (`string: ""`) - Specifies the path to the
certificate used for Vault communication. If this is set then you need to certificate used for Vault communication. If this is set, then you also need to
also set tls_key_file. set `key_file`.
- `KeyFile` / `key_file` (`string: ""`) - Specifies the path to the private - `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 key used for Vault communication. If this is set, then you also need to set
cert_file. `cert_file`.
- `TLSServerName` / `tls_server_name` (`string: ""`) - Specifies an optional - `TLSServerName` / `tls_server_name` (`string: ""`) - Specifies an optional
string used to set the SNI host when connecting to Vault via TLS. 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 - `TLSSkipVerify` / `tls_skip_verify` (`bool: false`) - Specifies if SSL peer
validation should be enforced. validation should be enforced.
@include 'http_api_connect_ca_common_options.mdx'
## Root and Intermediate PKI Paths ## Root and Intermediate PKI Paths
The Vault CA provider uses two separately configured 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` In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
is `connect_inter`. These values should be updated for your environment. is `connect_inter`. These values should be updated for your environment.
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
```hcl ```hcl
# Existing PKI Mounts # Existing PKI Mounts
path "/sys/mounts" { path "/sys/mounts" {
@ -153,12 +192,14 @@ path "/connect_inter/*" {
path "auth/token/renew-self" { path "auth/token/renew-self" {
capabilities = [ "update" ] capabilities = [ "update" ]
} }
path "auth/token/lookup-self" { path "auth/token/lookup-self" {
capabilities = [ "read" ] capabilities = [ "read" ]
} }
``` ```
</CodeBlockConfig>
### Consul Managed PKI Paths ### Consul Managed PKI Paths
The following Vault policy allows Consul to create and manage the PKI paths in Vault. 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` In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
is `connect_inter`. These values should be updated for your environment. is `connect_inter`. These values should be updated for your environment.
<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
```hcl ```hcl
# Consul Managed PKI Mounts # Consul Managed PKI Mounts
path "/sys/mounts" { path "/sys/mounts" {
@ -190,3 +233,10 @@ path "/connect_inter/*" {
capabilities = [ "create", "read", "update", "delete", "list" ] 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`