Skip to content

Latest commit

 

History

History
556 lines (363 loc) · 23 KB

API.md

File metadata and controls

556 lines (363 loc) · 23 KB
Raw

API Reference

Constructs

DnsValidatedCertificate

  • Implements: aws-cdk-lib.aws_certificatemanager.ICertificate, aws-cdk-lib.ITaggable

A certificate managed by AWS Certificate Manager.

Will be automatically validated using DNS validation against the specified Route 53 hosted zone. This construct should be used only for cross-region or cross-account certificate validations. The default Certificate construct is better in cases where everything is managed by the CDK application.

Please note that this construct does not support alternative names yet as it would require domain to role mapping.

Example

// ### Cross-region certificate validation
// hosted zone managed by the CDK application
const hostedZone: route53.IHostedZone = ...
// no separate validation role is needed
const certificate = new DnsValidatedCertificate(this, 'CrossRegionCertificate', {
  domainName: 'example.com',     // must be compatible with the hosted zone
  validationHostedZones: [{      // hosted zone used with the execution role's permissions
    hostedZone: hostedZone
  }],
  certificateRegion: 'us-east-1' // used by for example CloudFront
})
// ### Cross-account certificate validation
// external hosted zone
const hostedZone: route53.IHostedZone =
  route53.HostedZone.fromHostedZoneAttributes(this, 'HostedZone', {
    hostedZoneId: 'Z532DGDEDFS123456789',
    zoneName: 'example.com'
  })
// validation role in the same account as the hosted zone
const roleArn = 'arn:aws:iam::123456789:role/ChangeDnsRecordsRole'
const externalId = 'domain-assume'
const validationRole: iam.IRole =
  iam.Role.fromRoleArn(this, 'ValidationRole', roleArn)
const certificate = new DnsValidatedCertificate(this, 'CrossAccountCertificate', {
  domainName: 'example.com',
  validationHostedZones: [{
    hostedZone: hostedZone,
    validationRole: validationRole,
    validationExternalId: externalId
  }]
})
// ### Cross-account alternative name validation
// example.com is validated on same account against managed hosted zone
// and secondary.com is validated against external hosted zone on other account
const hostedZoneForMain: route53.IHostedZone = ...
const hostedZoneForAlternative: route53.IHostedZone =
  route53.HostedZone.fromHostedZoneAttributes(this, 'SecondaryHostedZone', {
    hostedZoneId: 'Z532DGDEDFS123456789',
    zoneName: 'secondary.com'
  })
const certificate = new DnsValidatedCertificate(this, 'CrossAccountCertificate', {
  domainName: 'example.com',
  alternativeDomainNames: ['secondary.com'],
  validationHostedZones: [{
    hostedZone: hostedZoneForMain
  },{
    hostedZone: hostedZoneForAlternative,
    validationRole: iam.Role.fromRoleArn(
      this, 'SecondaryValidationRole', 'arn:aws:iam::123456789:role/ChangeDnsRecordsRole'
    ),
    validationExternalId: 'domain-assume'
  }]
})@resource[object Object]@resource[object Object]

Initializers 

import { DnsValidatedCertificate } from '@trautonen/cdk-dns-validated-certificate'

new DnsValidatedCertificate(scope: Construct, id: string, props: DnsValidatedCertificateProps)
Name Type Description
scope constructs.Construct construct hosting this construct.
id string construct's identifier.
props DnsValidatedCertificateProps properties for the construct.
scopeRequired
  • Type: constructs.Construct

construct hosting this construct.

idRequired
  • Type: string

construct's identifier.

propsRequired

properties for the construct.

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
metricDaysToExpiry Return the DaysToExpiry metric for this AWS Certificate Manager Certificate. By default, this is the minimum value over 1 day.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
metricDaysToExpiry 
public metricDaysToExpiry(props?: MetricOptions): Metric

Return the DaysToExpiry metric for this AWS Certificate Manager Certificate. By default, this is the minimum value over 1 day.

This metric is no longer emitted once the certificate has effectively expired, so alarms configured on this metric should probably treat missing data as "breaching".

propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
isConstruct 
import { DnsValidatedCertificate } from '@trautonen/cdk-dns-validated-certificate'

DnsValidatedCertificate.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { DnsValidatedCertificate } from '@trautonen/cdk-dns-validated-certificate'

DnsValidatedCertificate.isOwnedResource(construct: IConstruct)

Returns true if the construct was created by CDK, and false otherwise.

constructRequired
  • Type: constructs.IConstruct
isResource 
import { DnsValidatedCertificate } from '@trautonen/cdk-dns-validated-certificate'

DnsValidatedCertificate.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
certificateArn string The certificate's ARN.
certificateRegion string The region where the certificate is deployed to.
tags aws-cdk-lib.TagManager The tag manager to set, remove and format tags for the certificate.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

certificateArnRequired 
public readonly certificateArn: string;
  • Type: string

The certificate's ARN.

certificateRegionRequired 
public readonly certificateRegion: string;
  • Type: string

The region where the certificate is deployed to.

tagsRequired 
public readonly tags: TagManager;
  • Type: aws-cdk-lib.TagManager

The tag manager to set, remove and format tags for the certificate.

Structs

DnsValidatedCertificateProps

Initializer 

import { DnsValidatedCertificateProps } from '@trautonen/cdk-dns-validated-certificate'

const dnsValidatedCertificateProps: DnsValidatedCertificateProps = { ... }

Properties

Name Type Description
domainName string Fully-qualified domain name to request a certificate for.
validationHostedZones ValidationHostedZone[] List of hosted zones to use for validation.
alternativeDomainNames string[] Fully-qualified alternative domain names to request a certificate for.
certificateRegion string AWS region where the certificate is deployed.
cleanupValidationRecords boolean Enable or disable cleaning of validation DNS records from the hosted zone.
customResourceRole aws-cdk-lib.aws_iam.IRole The role that is used for the custom resource Lambda execution.
removalPolicy aws-cdk-lib.RemovalPolicy Apply the given removal policy to this resource.
transparencyLoggingEnabled boolean Enable or disable transparency logging for this certificate.
domainNameRequired 
public readonly domainName: string;
  • Type: string

Fully-qualified domain name to request a certificate for.

May contain wildcards, such as *.domain.com.

validationHostedZonesRequired 
public readonly validationHostedZones: ValidationHostedZone[];

List of hosted zones to use for validation.

Hosted zones are mapped to domain names by the zone name.

alternativeDomainNamesOptional 
public readonly alternativeDomainNames: string[];
  • Type: string[]

Fully-qualified alternative domain names to request a certificate for.

May contain wildcards, such as *.otherdomain.com.

certificateRegionOptional 
public readonly certificateRegion: string;
  • Type: string
  • Default: Same region as the stack.

AWS region where the certificate is deployed.

You should use the default Certificate construct instead if the region is same as the stack's and the hosted zone is in the same account.

cleanupValidationRecordsOptional 
public readonly cleanupValidationRecords: boolean;
  • Type: boolean
  • Default: true

Enable or disable cleaning of validation DNS records from the hosted zone.

If there's multiple certificates created for same domain, it is possible to encouter a race condition where some certificate is removed and another certificate would need the same validation record. Prefer single certificate for a domain or set this to false and cleanup records manually when not needed anymore. If you change this property after creation, a new certificate will be requested.

customResourceRoleOptional 
public readonly customResourceRole: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole
  • Default: Lambda creates a default execution role.

The role that is used for the custom resource Lambda execution.

The role is given permissions to request certificates from ACM. If there are any validationRoles provided, this role is also given permission to assume the validationRole. Otherwise it is assumed that the hosted zone is in same account and the execution role is given permissions to change DNS records for the given domainName.

removalPolicyOptional 
public readonly removalPolicy: RemovalPolicy;
  • Type: aws-cdk-lib.RemovalPolicy
  • Default: RemovalPolicy.DESTROY

Apply the given removal policy to this resource.

The removal policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced. The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN). If you change this property after creation, a new certificate will be requested.

transparencyLoggingEnabledOptional 
public readonly transparencyLoggingEnabled: boolean;
  • Type: boolean
  • Default: true

Enable or disable transparency logging for this certificate.

Once a certificate has been logged, it cannot be removed from the log. Opting out at that point will have no effect. If you change this property after creation, a new certificate will be requested.

https://docs.aws.amazon.com/acm/latest/userguide/acm-bestpractices.html#best-practices-transparency

ValidationHostedZone

Initializer 

import { ValidationHostedZone } from '@trautonen/cdk-dns-validated-certificate'

const validationHostedZone: ValidationHostedZone = { ... }

Properties

Name Type Description
hostedZone aws-cdk-lib.aws_route53.IHostedZone Hosted zone to use for DNS validation.
validationExternalId string External id for validationRole role assume verification.
validationRole aws-cdk-lib.aws_iam.IRole The role that is assumed for DNS record changes for certificate validation.
hostedZoneRequired 
public readonly hostedZone: IHostedZone;
  • Type: aws-cdk-lib.aws_route53.IHostedZone

Hosted zone to use for DNS validation.

The zone name is matched to domain name to use the right hosted zone for validation.

If the hosted zone is not managed by the CDK application, it needs to be provided via HostedZone.fromHostedZoneAttributes().

validationExternalIdOptional 
public readonly validationExternalId: string;
  • Type: string
  • Default: No external id provided during assume.

External id for validationRole role assume verification.

This should be used only when validationRole is given and the role expects an external id provided on assume.

validationRoleOptional 
public readonly validationRole: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole
  • Default: No separate role for DNS record changes. The given customResourceRole or the default role is used for DNS record changes.

The role that is assumed for DNS record changes for certificate validation.

This role should exist in the same account as the hosted zone and include permissions to change the DNS records for the given hostedZone. The customResourceRole or the default execution role is given permission to assume this role.