mirror of https://github.com/hashicorp/consul
183 lines
7.0 KiB
Markdown
183 lines
7.0 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: Service Mesh Certificate Authority - AWS Certificate Manager
|
|
description: >-
|
|
You can use the AWS Certificate Manager Private Certificate Authority as the Consul service mesh's certificate authority to secure your service mesh. Learn how to configure the AWS ACM Private CA, its limitations in Consul, and cost planning considerations.
|
|
---
|
|
|
|
# AWS Certificate Manager as a Service Mesh Certificate Authority
|
|
|
|
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/config/config-files#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/config/config-files#connect_ca_config
|
|
[`ca_provider`]: /docs/agent/config/config-files#connect_ca_provider
|
|
[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration
|