From 9c2036d74bb27f563ba32029d519b4363092d792 Mon Sep 17 00:00:00 2001 From: Nick Lynch Date: Tue, 18 Aug 2020 16:48:15 +0100 Subject: [PATCH] chore(certificatemanager): Update README to inline examples and mention limits 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 --- .../@aws-cdk/aws-certificatemanager/README.md | 92 +++++++++++++------ .../test/example.dns.lit.ts | 36 -------- .../test/example.simple-request.lit.ts | 21 ----- 3 files changed, 62 insertions(+), 87 deletions(-) delete mode 100644 packages/@aws-cdk/aws-certificatemanager/test/example.dns.lit.ts delete mode 100644 packages/@aws-cdk/aws-certificatemanager/test/example.simple-request.lit.ts diff --git a/packages/@aws-cdk/aws-certificatemanager/README.md b/packages/@aws-cdk/aws-certificatemanager/README.md index 15fbc1a8e09b4..f90edaf1ef9bf 100644 --- a/packages/@aws-cdk/aws-certificatemanager/README.md +++ b/packages/@aws-cdk/aws-certificatemanager/README.md @@ -1,4 +1,5 @@ ## AWS Certificate Manager Construct Library + --- @@ -9,12 +10,11 @@ --- -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 @@ -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); ``` diff --git a/packages/@aws-cdk/aws-certificatemanager/test/example.dns.lit.ts b/packages/@aws-cdk/aws-certificatemanager/test/example.dns.lit.ts deleted file mode 100644 index c2cfd41ff0e15..0000000000000 --- a/packages/@aws-cdk/aws-certificatemanager/test/example.dns.lit.ts +++ /dev/null @@ -1,36 +0,0 @@ -import * as route53 from '@aws-cdk/aws-route53'; -import { App, CfnOutput, Construct, Stack } from '@aws-cdk/core'; -import * as acm from '../lib'; - -class AcmStack extends Stack { - constructor(scope: Construct, id: string) { - super(scope, id); - /// !show - 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, - }), - }); - /// !hide - - new CfnOutput(this, 'Output', { - value: cert.certificateArn, - }); - } -} - -const app = new App(); -new AcmStack(app, 'AcmStack'); -app.synth(); diff --git a/packages/@aws-cdk/aws-certificatemanager/test/example.simple-request.lit.ts b/packages/@aws-cdk/aws-certificatemanager/test/example.simple-request.lit.ts deleted file mode 100644 index 36ce17dd9d6a4..0000000000000 --- a/packages/@aws-cdk/aws-certificatemanager/test/example.simple-request.lit.ts +++ /dev/null @@ -1,21 +0,0 @@ -import { App, CfnOutput, Construct, Stack } from '@aws-cdk/core'; -import * as certmgr from '../lib'; - -class CertStack extends Stack { - constructor(scope: Construct, id: string) { - super(scope, id); - /// !show - const cert = new certmgr.Certificate(this, 'Certificate', { - domainName: 'example.com', - }); - /// !hide - - new CfnOutput(this, 'Output', { - value: cert.certificateArn, - }); - } -} - -const app = new App(); -new CertStack(app, 'MyStack4'); -app.synth();