Skip to content

Commit

Permalink
chore(certificatemanager): Update README to inline examples and menti…
Browse files Browse the repository at this point in the history
…on limits (#9800)

Minor refactoring of the README to inline the examples (from the `.lit.ts`
files), and to explicitly call out the yearly certificate limit.

fixes #5889

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
  • Loading branch information
njlynch authored Aug 18, 2020
1 parent 286ff50 commit ffb06ab
Show file tree
Hide file tree
Showing 3 changed files with 62 additions and 87 deletions.
92 changes: 62 additions & 30 deletions packages/@aws-cdk/aws-certificatemanager/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
## AWS Certificate Manager Construct Library

<!--BEGIN STABILITY BANNER-->
---

Expand All @@ -9,12 +10,11 @@
---
<!--END STABILITY BANNER-->

This package provides Constructs for provisioning and referencing
certificates which can be used in CloudFront and ELB.

The following requests a certificate for a given domain:
AWS Certificate Manager (ACM) handles the complexity of creating, storing, and renewing public and private SSL/TLS X.509 certificates and keys that
protect your AWS websites and applications. ACM certificates can secure singular domain names, multiple specific domain names, wildcard domains, or
combinations of these. ACM wildcard certificates can protect an unlimited number of subdomains.

[request a certificate example](test/example.simple-request.lit.ts)
This package provides Constructs for provisioning and referencing ACM certificates which can be used with CloudFront and ELB.

After requesting a certificate, you will need to prove that you own the
domain in question before the certificate will be granted. The CloudFormation
Expand All @@ -24,67 +24,99 @@ Because of this wait time, when using manual validation methods, it's better
to provision your certificates either in a separate stack from your main
service, or provision them manually and import them into your CDK application.

### Email validation
**Note:** There is a limit on total number of ACM certificates that can be requested on an account and region within a year.
The default limit is 2000, but this limit may be (much) lower on new AWS accounts.
See https://docs.aws.amazon.com/acm/latest/userguide/acm-limits.html for more information.

Email-validated certificates (the default) are validated by receiving an
email on one of a number of predefined domains and following the instructions
in the email.
### DNS validation

See [Validate with Email](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-email.html)
DNS validation is the preferred method to validate domain ownership, as it has a number of advantages over email validation.
See also [Validate with DNS](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-dns.html)
in the AWS Certificate Manager User Guide.

### DNS validation

If Amazon Route 53 is your DNS provider for the requested domain, the DNS record can be
created automatically:

```ts
new Certificate(this, 'Certificate', {
import * as acm from '@aws-cdk/aws-certificatemanager';
import * as route53 from '@aws-cdk/aws-route53';

const myHostedZone = new route53.HostedZone(this, 'HostedZone', {
zoneName: 'example.com',
});
new acm.Certificate(this, 'Certificate', {
domainName: 'hello.example.com',
validation: CertificateValidation.fromDns(myHostedZone), // Route 53 hosted zone
validation: acm.CertificateValidation.fromDns(myHostedZone),
});
```

Otherwise DNS records must be added manually and the stack will not complete
If Route 53 is not your DNS provider, the DNS records must be added manually and the stack will not complete
creating until the records are added.

```ts
new Certificate(this, 'Certificate', {
new acm.Certificate(this, 'Certificate', {
domainName: 'hello.example.com',
validation: CertificateValidation.fromDns(), // Records must be added manually
validation: acm.CertificateValidation.fromDns(), // Records must be added manually
});
```

See also [Validate with DNS](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-dns.html)
in the AWS Certificate Manager User Guide.

When working with multiple domains, use the `CertificateValidation.fromDnsMultiZone()`:

[multiple domains DNS validation](test/example.dns.lit.ts)
```ts
const exampleCom = new route53.HostedZone(this, 'ExampleCom', {
zoneName: 'example.com',
});
const exampleNet = new route53.HostedZone(this, 'ExampelNet', {
zoneName: 'example.net',
});

const cert = new acm.Certificate(this, 'Certificate', {
domainName: 'test.example.com',
subjectAlternativeNames: ['cool.example.com', 'test.example.net'],
validation: acm.CertificateValidation.fromDnsMultiZone({
'text.example.com': exampleCom,
'cool.example.com': exampleCom,
'test.example.net': exampleNet,
}),
});
```

### Email validation

Use the `DnsValidatedCertificate` construct for cross-region certificate creation:
Email-validated certificates (the default) are validated by receiving an
email on one of a number of predefined domains and following the instructions
in the email.

See [Validate with Email](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-email.html)
in the AWS Certificate Manager User Guide.

```ts
new DnsValidatedCertificate(this, 'CrossRegionCertificate', {
new acm.Certificate(this, 'Certificate', {
domainName: 'hello.example.com',
hostedZone: myHostedZone,
region: 'us-east-1',
validation: acm.CertificateValidation.fromEmail(), // Optional, this is the default
});
```

This is useful when deploying a stack in a region other than `us-east-1` with a
certificate for a CloudFront distribution.
### Cross-region Certificates

If cross-region is not needed, the recommended solution is to use the
`Certificate` construct which uses a native CloudFormation implementation.
ACM certificates that are used with CloudFront -- or higher-level constructs which rely on CloudFront -- must be in the `us-east-1` region.
The `DnsValidatedCertificate` construct exists to faciliate creating these certificates cross-region. This resource can only be used with
Route53-based DNS validation.

```ts
new acm.DnsValidatedCertificate(this, 'CrossRegionCertificate', {
domainName: 'hello.example.com',
hostedZone: myHostedZone,
region: 'us-east-1',
});
```

### Importing

If you want to import an existing certificate, you can do so from its ARN:

```ts
const arn = "arn:aws:...";
const arn = 'arn:aws:...';
const certificate = Certificate.fromCertificateArn(this, 'Certificate', arn);
```

Expand Down
36 changes: 0 additions & 36 deletions packages/@aws-cdk/aws-certificatemanager/test/example.dns.lit.ts

This file was deleted.

This file was deleted.

0 comments on commit ffb06ab

Please sign in to comment.