184 lines
6.7 KiB
Plaintext
184 lines
6.7 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Connect - Certificate Management
|
|
description: >-
|
|
Consul can be used with AWS Certificate Manager Private CA to manage and sign
|
|
certificates.
|
|
---
|
|
|
|
# AWS Certificate Manager Private CA as a Connect CA
|
|
|
|
Consul can be used with [AWS Certificate Manager (ACM) Private Certificate
|
|
Authority
|
|
(CA)](https://aws.amazon.com/certificate-manager/private-certificate-authority/)
|
|
to manage and sign certificates.
|
|
|
|
-> This page documents the specifics of the AWS ACM Private CA provider.
|
|
Please read the [certificate management overview](/docs/connect/ca)
|
|
page first to understand how Consul manages certificates with configurable
|
|
CA providers.
|
|
|
|
## Requirements
|
|
|
|
The ACM Private CA Provider was added in Consul 1.7.0.
|
|
|
|
The ACM Private CA Provider needs to be authorized via IAM credentials to
|
|
perform operations. Every Consul server needs to be running in an environment
|
|
where a suitable IAM configuration is present.
|
|
|
|
The [standard AWS SDK credential
|
|
locations](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials)
|
|
are used, which means that suitable credentials and region configuration need to be present in one of the following:
|
|
|
|
1. Environment variables
|
|
1. Shared credentials file
|
|
1. Via an EC2 instance role
|
|
|
|
The IAM credential provided must have permission for the following actions:
|
|
|
|
- CreateCertificateAuthority - assuming an existing CA is not specified in `existing_arn`
|
|
- DescribeCertificateAuthority
|
|
- GetCertificate
|
|
- IssueCertificate
|
|
|
|
## Configuration
|
|
|
|
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"
|
|
ca_config {
|
|
existing_arn = "arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-123456789012"
|
|
}
|
|
}
|
|
```
|
|
|
|
</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 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,
|
|
Consul will attempt to use the existing CA to issue certificates.
|
|
|
|
- In the primary datacenter this ARN **must identify a root CA**. See
|
|
[limitations](#limitations).
|
|
- In a secondary datacenter, it must identify a subordinate CA signed by
|
|
the same root used in the primary datacenter. If it is signed by another
|
|
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
|
|
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
|
|
[limits](https://docs.aws.amazon.com/acm-pca/latest/userguide/PcaLimits.html)
|
|
that restrict how fast certificates can be issued. This may impact how quickly
|
|
large clusters can rotate all issued certificates.
|
|
|
|
Currently, the ACM Private CA provider for Connect has some additional
|
|
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 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.
|
|
|
|
For now, the limitation means that once ACM Private CA is configured as the CA
|
|
provider, it is not possible to reconfigure a different CA provider, or rotate
|
|
the root CA key without potentially observing some transient connection
|
|
failures. See the section on [forced rotation without
|
|
cross-signing](/docs/connect/ca#forced-rotation-without-cross-signing) for
|
|
more details.
|
|
|
|
### Primary DC Must be a Root CA
|
|
|
|
Currently, if an existing ACM Private CA is used, the primary DC must use a Root
|
|
CA directly to issue certificates.
|
|
|
|
## Cost Planning
|
|
|
|
To help estimate costs, an example is provided below of the resources that would
|
|
be used.
|
|
|
|
~> This is intended to illustrate the behavior of the CA for cost planning
|
|
purposes. Please refer to the [pricing for ACM Private
|
|
CA](https://aws.amazon.com/certificate-manager/pricing/) for actual cost
|
|
information.
|
|
|
|
Assume the following Consul datacenters exist and are configured to use ACM
|
|
Private CA as their Connect CA with the default leaf certificate lifetime of
|
|
72 hours:
|
|
|
|
| Datacenter | Primary | CA Resource Created | Number of service instances |
|
|
| ---------- | ------- | ------------------- | --------------------------- |
|
|
| dc1 | yes | 1 ROOT | 100 |
|
|
| dc2 | no | 1 SUBORDINATE | 50 |
|
|
| dc3 | no | 1 SUBORDINATE | 500 |
|
|
|
|
Leaf certificates are valid for 72 hours but are refreshed when
|
|
between 60% and 90% of their lifetime has elapsed. On average each certificate
|
|
will be reissued every 54 hours or roughly 13.3 times per month.
|
|
|
|
So monthly cost would be calculated as:
|
|
|
|
- 3 ⨉ Monthly CA cost, plus
|
|
- 8630 ⨉ Certificate Issue cost, made up of:
|
|
- 100 ⨉ 13.3 = 1,330 certificates issued in dc1
|
|
- 50 ⨉ 13.3 = 665 certificates issued in dc2
|
|
- 500 ⨉ 13.3 = 6,650 certificates issued in dc3
|
|
|
|
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
|