From e62b1d05d887d6f98cdfa6801e9594b1773d123b Mon Sep 17 00:00:00 2001 From: Blake Covarrubias Date: Thu, 19 Aug 2021 11:18:55 -0700 Subject: [PATCH] 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 --- website/content/docs/agent/options.mdx | 49 +++++----- website/content/docs/connect/ca/aws.mdx | 55 +++++++++-- website/content/docs/connect/ca/consul.mdx | 20 ++-- website/content/docs/connect/ca/index.mdx | 6 +- website/content/docs/connect/ca/vault.mdx | 98 ++++++++++++++----- .../http_api_connect_ca_common_options.mdx | 71 ++++++++++++++ 6 files changed, 233 insertions(+), 66 deletions(-) create mode 100644 website/content/partials/http_api_connect_ca_common_options.mdx diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx index 946a177577..4909b3c12a 100644 --- a/website/content/docs/agent/options.mdx +++ b/website/content/docs/agent/options.mdx @@ -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. - `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). @@ -1176,6 +1176,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 @@ -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: - - `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) @@ -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 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. @@ -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 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. @@ -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 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. @@ -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 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 diff --git a/website/content/docs/connect/ca/aws.mdx b/website/content/docs/connect/ca/aws.mdx index 77eca45875..46e215f87c 100644 --- a/website/content/docs/connect/ca/aws.mdx +++ b/website/content/docs/connect/ca/aws.mdx @@ -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: + + + + ```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 + + + + +```json +{ + "Provider": "aws-pca", + "Config": { + "ExistingARN": "arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-123456789012" + } +} +``` + + + + + +~> **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: `) - 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. + + +[`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 diff --git a/website/content/docs/connect/ca/consul.mdx b/website/content/docs/connect/ca/consul.mdx index 72ed653aff..bad7effbb0 100644 --- a/website/content/docs/connect/ca/consul.mdx +++ b/website/content/docs/connect/ca/consul.mdx @@ -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: + + ```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. + + +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`. diff --git a/website/content/docs/connect/ca/index.mdx b/website/content/docs/connect/ca/index.mdx index e3bd830494..94d7bf3946 100644 --- a/website/content/docs/connect/ca/index.mdx +++ b/website/content/docs/connect/ca/index.mdx @@ -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. diff --git a/website/content/docs/connect/ca/vault.mdx b/website/content/docs/connect/ca/vault.mdx index 8bcb75a97d..6b96616b20 100644 --- a/website/content/docs/connect/ca/vault.mdx +++ b/website/content/docs/connect/ca/vault.mdx @@ -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: + + + + ```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. + + + + +```json +{ + "Provider": "vault", + "Config": { + "Address": "http://localhost:8200", + "Token": "", + "RootPKIPath": "connect-root", + "IntermediatePKIPath": "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 are adding the configuration to the agent's + configuration file. - `Address` / `address` (`string: `) - The address of the Vault server. - `Token` / `token` (`string: `) - 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: `) - 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: `) - 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. + + ```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" ] } ``` + + ### 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. + + ```hcl # Consul Managed PKI Mounts path "/sys/mounts" { @@ -190,3 +233,10 @@ path "/connect_inter/*" { capabilities = [ "create", "read", "update", "delete", "list" ] } ``` + + + + +[`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 diff --git a/website/content/partials/http_api_connect_ca_common_options.mdx b/website/content/partials/http_api_connect_ca_common_options.mdx new file mode 100644 index 0000000000..d64d6ee475 --- /dev/null +++ b/website/content/partials/http_api_connect_ca_common_options.mdx @@ -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`