almacdkdomain

README

npm i -D @alma-cdk/domain

Simplifies creation of subdomain with a TLS certificate and configuration with services like AWS CloudFront.

🚧   Project Stability

This construct is still versioned with v0 major version and breaking changes might be introduced if necessary (without a major version bump), though we aim to keep the API as stable as possible (even within v0 development). We aim to publish v1.0.0 soon and after that breaking changes will be introduced via major version bumps.

Getting Started

import { Domain } from '@alma-cdk/domain';
import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';

const domain = new Domain(this, 'Domain', {
  zone: 'example.com', // retrieve the zone via lookup, or provide IHostedZone
  subdomain: 'foobar', // optional subdomain
});

const distribution = new cloudfront.Distribution(this, 'Distribution', {
  /* other cloudfront configuration values removed for brevity */

  certificate: domain.certificate, // reference to created ICertificate
  domainNames: [domain.fqdn], // foobar.example.com
  enableIpv6: domain.enableIpv6, // true by default – set enableIpv6 prop to false during new Domain()
})

// assign CloudFront distribution to given fqdn with A + AAAA records
domain.addTarget(new targets.CloudFrontTarget(distribution))

CloudFront helper

Instead of assigning certificate, domainNames and enableIpv6 properties individually, you may choose to use the one-liner helper utility method configureCloudFront() to set all three values at once – don't forget to use ... object spread syntax:

const distribution = new cloudfront.Distribution(this, 'Distribution', {
  /* other cloudfront configuration values removed for brevity */

  // one-liner to configure certificate, domainNames and IPv6 support
  ...domain.configureCloudFront(),
})

// assign CloudFront distribution to given fqdn with A + AAAA records
domain.addTarget(new targets.CloudFrontTarget(distribution))

Note: The returned domain names configuration is domainNames: [domain.fqdn], meaning this only works in scenarios where your CloudFront distribution has only single domain name.

Documentation

Overview

Domain with certificate

Domain with certificate

Domain with certificate

Domain with certificate

Domain with certificate

Domain with certificate

Index

• func Domain_IsConstruct(x interface{}) *bool
• func NewDomain_Override(d Domain, scope constructs.Construct, id *string, props *DomainProps)
• type Domain
  • func NewDomain(scope constructs.Construct, id *string, props *DomainProps) Domain
• type DomainProps
• type ICloudFrontConfiguration
• type IDomain

Functions

func Domain_IsConstruct

func Domain_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func NewDomain_Override

func NewDomain_Override(d Domain, scope constructs.Construct, id *string, props *DomainProps)

Initializing a `new Domain` construct instance will lookup the Route53 hosted zone and define ACM DNS-validated certificate.

After initialization you must use `assign(alias)` method to to configure `A`/`AAAA` records with the `alias` as the record value. Experimental.

Types

type Domain

type Domain interface {
	constructs.Construct
	IDomain
	// Certificate Manager certificate.
	// Experimental.
	Certificate() awscertificatemanager.ICertificate
	// Has IPv6 AAAA records been created.
	//
	// Can be used to conditionally configure IPv6 support
	// to CloudFront distribution.
	// Experimental.
	EnableIpv6() *bool
	// Fully-qualified domain name.
	// Experimental.
	Fqdn() *string
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// Route53 hosted zone used to assign the domain into.
	// Experimental.
	Zone() awsroute53.IHostedZone
	// Assign an alias as record target with the fully-qualified domain name.
	//
	// This will create both `A` & `AAAA` DNS records, unless `disableIpV6` was set to `true`
	// during initialization of `Domain` construct (resulting in only `A` record being created).
	//
	// Example:
	//   domain.addTarget(new targets.CloudFrontTarget(distribution))
	//
	// Experimental.
	AddTarget(alias awsroute53.IAliasRecordTarget)
	// Helper method to configure CloudFront distribution with the domain, certificate and IPv6 support.
	//
	// Returns: CloudFront configuration for certificate, domainNames and IPv6.
	// Experimental.
	ConfigureCloudFront() ICloudFrontConfiguration
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

Experimental.

func NewDomain

func NewDomain(scope constructs.Construct, id *string, props *DomainProps) Domain

Initializing a `new Domain` construct instance will lookup the Route53 hosted zone and define ACM DNS-validated certificate.

After initialization you must use `assign(alias)` method to to configure `A`/`AAAA` records with the `alias` as the record value. Experimental.

type DomainProps

type DomainProps struct {
	// Provide either a fully-qualified domain name as string to perform a hosted zone lookup or a previously defined hosted zone as `route53.IHostedZone`.
	// Experimental.
	Zone interface{} `field:"required" json:"zone" yaml:"zone"`
	// Provide your own pre-existing certificate.
	//
	// If not provided, a new certificate will be created
	// by default.
	// Experimental.
	Certificate awscertificatemanager.ICertificate `field:"optional" json:"certificate" yaml:"certificate"`
	// Set to false to disable IPv6 `AAAA` record creation.
	// Experimental.
	EnableIpv6 *bool `field:"optional" json:"enableIpv6" yaml:"enableIpv6"`
	// AWS Region to deploy the certificate into.
	//
	// Defaults to `us-east-1` which is the only region where
	// ACM certificates can be deployed to CloudFront.
	// Experimental.
	Region *string `field:"optional" json:"region" yaml:"region"`
	// Provide subdomain or leave undefined to use the zone apex domain.
	//
	// If subdomain provided, the resulting FQDN will be `subdomain.zone`.
	// Experimental.
	Subdomain *string `field:"optional" json:"subdomain" yaml:"subdomain"`
}

Properties to configure the domain (zone and certificate). Experimental.

type ICloudFrontConfiguration

type ICloudFrontConfiguration interface {
	// Certificate Manager certificate.
	// Experimental.
	Certificate() awscertificatemanager.ICertificate
	// Alternative domain names for this distribution.
	// Experimental.
	DomainNames() *[]*string
	// Has IPv6 AAAA records been created.
	//
	// Can be used to conditionally configure IPv6 support
	// to CloudFront distribution.
	// Experimental.
	EnableIpv6() *bool
}

Experimental.

type IDomain

type IDomain interface {
	// Assign an alias as record target with the fully-qualified domain name.
	//
	// This will create both `A` & `AAAA` DNS records, unless `disableIpV6` was set to `true`
	// during initialization of `Domain` construct (resulting in only `A` record being created).
	//
	// Example:
	//   domain.addTarget(new targets.CloudFrontTarget(distribution))
	//
	// Experimental.
	AddTarget(alias awsroute53.IAliasRecordTarget)
	// Certificate Manager certificate.
	// Experimental.
	Certificate() awscertificatemanager.ICertificate
	// Has IPv6 AAAA records been created.
	//
	// Can be used to conditionally configure IPv6 support
	// to CloudFront distribution.
	// Experimental.
	EnableIpv6() *bool
	// Fully-qualified domain name.
	// Experimental.
	Fqdn() *string
	// Route53 hosted zone used to assign the domain into.
	// Experimental.
	Zone() awsroute53.IHostedZone
}

Interface contract implemented by Domain construct. Experimental.