feat: add custom domain and API health check resource

Author: coderbyheart

.github/workflows/deploy.yaml

@@ -20,6 +20,7 @@ env:
   FORCE_COLOR: 3
   JSII_SILENCE_WARNING_UNTESTED_NODE_VERSION: 1
   REGISTRY: ghcr.io
+  API_DOMAIN_NAME: api.nordicsemi.world
 
 jobs:
   print-inputs:

README.md

@@ -57,6 +57,18 @@ npx cdk bootstrap # if this is the first time you use CDK in this account
 npx cdk deploy
 ```
 
+## Custom domain name
+
+You can specify a custom domain name for the deployed API using the environment
+variable `API_DOMAIN_NAME`.
+
+If you do so, make sure to create a certificate in the region for this domain
+name.
+
+After deploying the stack, make sure to set up a CNAME record for this domain
+that points to the hostname of the deployed API (available in the stack output
+`gatewayDomainName`).
+
 ## Continuous Deployment using GitHub Actions
 
 After deploying the stack manually once,

aws/acm.ts

@@ -0,0 +1,46 @@
+import {
+	ACMClient,
+	CertificateStatus,
+	ListCertificatesCommand,
+} from '@aws-sdk/client-acm'
+import chalk from 'chalk'
+
+export type DomainCert = {
+	domain: string
+	certificateArn: string
+}
+
+const getDomainCertificate =
+	(acm: ACMClient) =>
+	async (domain: string): Promise<DomainCert> => {
+		const { CertificateSummaryList } = await acm.send(
+			new ListCertificatesCommand({
+				CertificateStatuses: [CertificateStatus.ISSUED],
+			}),
+		)
+		const cert = (CertificateSummaryList ?? []).find(
+			({ DomainName }) => DomainName === domain,
+		)
+		if (cert === undefined)
+			throw new Error(`Failed to find certificate for ${domain}!`)
+		return {
+			domain,
+			certificateArn: cert.CertificateArn as string,
+		}
+	}
+
+export const getCertificateForDomain =
+	(acm: ACMClient) =>
+	async (domainName: string): Promise<DomainCert> => {
+		try {
+			return await getDomainCertificate(acm)(domainName)
+		} catch (err) {
+			console.error(
+				chalk.red(
+					`Failed to determine certificate for API domain ${domainName}!`,
+				),
+			)
+			console.error(err)
+			process.exit(1)
+		}
+	}

cdk/BackendApp.ts

@@ -1,11 +1,10 @@
 import { App } from 'aws-cdk-lib'
-import { BackendStack } from './stacks/BackendStack.js'
+import { BackendStack } from './BackendStack.js'
 
 export class BackendApp extends App {
 	public constructor({
 		isTest,
 		version,
-		domain,
 		...backendArgs
 	}: ConstructorParameters<typeof BackendStack>[1] & {
 		isTest: boolean
@@ -16,7 +15,6 @@ export class BackendApp extends App {
 			context: {
 				isTest,
 				version,
-				domain,
 			},
 		})
 

cdk/BackendLambdas.d.ts

@@ -13,4 +13,5 @@ type BackendLambdas = {
 	openSSL: PackedLambda
 	senMLToLwM2M: PackedLambda
 	senMLImportLogs: PackedLambda
+	apiHealthCheck: PackedLambda
 }

cdk/stacks/BackendStack.ts renamed to cdk/BackendStack.ts

@@ -5,22 +5,25 @@ import {
 	Stack,
 	aws_ecr as ECR,
 } from 'aws-cdk-lib'
-import type { BackendLambdas } from '../BackendLambdas.js'
+import type { BackendLambdas } from './BackendLambdas.js'
 import type { PackedLayer } from '@bifravst/aws-cdk-lambda-helpers/layer'
 import { LambdaSource } from '@bifravst/aws-cdk-lambda-helpers/cdk'
-import { ConnectionInformationGeoLocation } from '../resources/ConnectionInformationGeoLocation.js'
-import { LwM2MShadow } from '../resources/LwM2MShadow.js'
-import { PublicDevices } from '../resources/PublicDevices.js'
-import { ShareAPI } from '../resources/ShareAPI.js'
+import { ConnectionInformationGeoLocation } from './resources/ConnectionInformationGeoLocation.js'
+import { LwM2MShadow } from './resources/LwM2MShadow.js'
+import { PublicDevices } from './resources/PublicDevices.js'
+import { ShareAPI } from './resources/ShareAPI.js'
 import { STACK_NAME } from './stackConfig.js'
-import { DevicesAPI } from '../resources/DevicesAPI.js'
-import { LwM2MObjectsHistory } from '../resources/LwM2MObjectsHistory.js'
-import { CustomDevicesAPI } from '../resources/CustomDevicesAPI.js'
-import { SenMLMessages } from '../resources/SenMLMessage.js'
-import { ContainerRepositoryId } from '../../aws/ecr.js'
+import { DevicesAPI } from './resources/DevicesAPI.js'
+import { LwM2MObjectsHistory } from './resources/LwM2MObjectsHistory.js'
+import { CustomDevicesAPI } from './resources/CustomDevicesAPI.js'
+import { SenMLMessages } from './resources/SenMLMessage.js'
+import { ContainerRepositoryId } from '../aws/ecr.js'
 import { repositoryName } from '@bifravst/aws-cdk-ecr-helpers/repository'
 import { ContinuousDeployment } from '@bifravst/ci'
-import { API } from '../resources/api/API.js'
+import { API } from './resources/api/API.js'
+import type { DomainCert } from '../aws/acm.js'
+import { ApiHealthCheck } from './resources/api/HealthCheck.js'
+import { CustomDomain } from './resources/api/CustomDomain.js'
 
 /**
  * Provides resources for the backend serving data to hello.nrfcloud.com/map
@@ -29,12 +32,16 @@ export class BackendStack extends Stack {
 	constructor(
 		parent: App,
 		{
+			domain,
+			apiDomain,
 			layer,
 			lambdaSources,
 			openSSLLambdaContainerTag,
 			repository,
 			gitHubOICDProviderArn,
 		}: {
+			domain: string
+			apiDomain?: DomainCert
 			layer: PackedLayer
 			lambdaSources: BackendLambdas
 			openSSLLambdaContainerTag: string
@@ -59,8 +66,41 @@ export class BackendStack extends Stack {
 		})
 
 		const publicDevices = new PublicDevices(this)
+		new CfnOutput(this, 'publicDevicesTableName', {
+			exportName: `${this.stackName}:publicDevicesTableName`,
+			description: 'name of the public devices table',
+			value: publicDevices.publicDevicesTable.tableName,
+		})
 
 		const api = new API(this)
+		api.addRoute(
+			'GET /health',
+			new ApiHealthCheck(this, { baseLayer, lambdaSources }).fn,
+		)
+
+		if (apiDomain === undefined) {
+			new CfnOutput(this, 'APIURL', {
+				exportName: `${this.stackName}:APIURL`,
+				description: 'API endpoint',
+				value: api.URL,
+			})
+		} else {
+			const domain = new CustomDomain(this, {
+				api,
+				apiDomain,
+			})
+			new CfnOutput(this, 'gatewayDomainName', {
+				exportName: `${this.stackName}:gatewayDomainName`,
+				description:
+					'The domain name associated with the regional endpoint for the custom domain name. Use this as the target for the CNAME record for your custom domain name.',
+				value: domain.gatewayDomainName.toString(),
+			})
+			new CfnOutput(this, 'APIURL', {
+				exportName: `${this.stackName}:APIURL`,
+				description: 'API endpoint',
+				value: domain.URL,
+			})
+		}
 
 		new LwM2MShadow(this, {
 			baseLayer,
@@ -84,6 +124,7 @@ export class BackendStack extends Stack {
 		})
 
 		const shareAPI = new ShareAPI(this, {
+			domain,
 			baseLayer,
 			lambdaSources,
 			publicDevices,
@@ -124,22 +165,12 @@ export class BackendStack extends Stack {
 
 		api.addRoute('POST /credentials', customDevicesAPI.createCredentials)
 
+		// CD
+
 		const cd = new ContinuousDeployment(this, {
 			repository,
 			gitHubOICDProviderArn,
 		})
-
-		// Outputs
-		new CfnOutput(this, 'APIURL', {
-			exportName: `${this.stackName}:APIURL`,
-			description: 'API endpoint',
-			value: api.URL,
-		})
-		new CfnOutput(this, 'publicDevicesTableName', {
-			exportName: `${this.stackName}:publicDevicesTableName`,
-			description: 'name of the public devices table',
-			value: publicDevices.publicDevicesTable.tableName,
-		})
 		new CfnOutput(this, 'cdRoleArn', {
 			exportName: `${this.stackName}:cdRoleArn`,
 			description: 'Role ARN to use in the deploy GitHub Actions Workflow',
@@ -149,7 +180,20 @@ export class BackendStack extends Stack {
 }
 
 export type StackOutputs = {
-	APIURL: string // e.g. 'https://iiet67bnlmbtuhiblik4wcy4ni0oujot.execute-api.eu-west-1.amazonaws.com/2024-04-12/'
+	/**
+	 * The URL of the deployed API
+	 * @example https://api.nordicsemi.world/2024-04-12/
+	 * @example https://9gsm5gind2.execute-api.eu-west-1.amazonaws.com/2024-04-12
+	 */
+	APIURL: string
+	/**
+	 * The domain name associated with the regional endpoint for the custom domain name. Use this as the target for the CNAME record for your custom domain name.
+	 *
+	 * Only present if custom domain is used
+	 *
+	 * @example d-nygno3o155.execute-api.eu-west-1.amazonaws.com
+	 */
+	gatewayDomainName?: string
 	publicDevicesTableName: string
 	/**
 	 * Role ARN to use in the deploy GitHub Actions Workflow

cdk/backend.ts

@@ -5,6 +5,8 @@ import { BackendApp } from './BackendApp.js'
 import { pack as packBaseLayer } from './baseLayer.js'
 import { ensureGitHubOIDCProvider } from '@bifravst/ci'
 import { packBackendLambdas } from './packBackendLambdas.js'
+import { ACMClient } from '@aws-sdk/client-acm'
+import { getCertificateForDomain } from '../aws/acm.js'
 
 const repoUrl = new URL(pJSON.repository.url)
 const repository = {
@@ -13,22 +15,30 @@ const repository = {
 }
 
 const iam = new IAMClient({})
+const acm = new ACMClient({})
 
 // Ensure needed container images exist
 const { openSSLLambdaContainerTag } = fromEnv({
 	openSSLLambdaContainerTag: 'OPENSSL_LAMBDA_CONTAINER_TAG',
 })(process.env)
 
+const isTest = process.env.IS_TEST === '1'
+const apiDomainName = process.env.API_DOMAIN_NAME
+
 new BackendApp({
 	lambdaSources: await packBackendLambdas(),
 	layer: await packBaseLayer(),
 	repository,
 	gitHubOICDProviderArn: await ensureGitHubOIDCProvider({
 		iam,
 	}),
-	isTest: process.env.IS_TEST === '1',
+	isTest,
 	openSSLLambdaContainerTag,
 	domain: 'hello.nrfcloud.com',
+	apiDomain:
+		apiDomainName !== undefined
+			? await getCertificateForDomain(acm)(apiDomainName)
+			: undefined,
 	version: (() => {
 		const v = process.env.VERSION
 		const defaultVersion = '0.0.0-development'

cdk/packBackendLambdas.ts

@@ -18,4 +18,5 @@ export const packBackendLambdas = async (): Promise<BackendLambdas> => ({
 	openSSL: await pack('openSSL'),
 	senMLToLwM2M: await pack('senMLToLwM2M'),
 	senMLImportLogs: await pack('senMLImportLogs'),
+	apiHealthCheck: await pack('apiHealthCheck'),
 })

cdk/resources/ConnectionInformationGeoLocation.ts

@@ -8,7 +8,7 @@ import {
 	RemovalPolicy,
 	Stack,
 } from 'aws-cdk-lib'
-import { STACK_NAME } from '../stacks/stackConfig.js'
+import { STACK_NAME } from '../stackConfig.js'
 import {
 	LambdaLogGroup,
 	LambdaSource,

cdk/resources/CustomDevicesAPI.ts

@@ -8,7 +8,7 @@ import {
 } from 'aws-cdk-lib'
 import { Construct } from 'constructs'
 import type { BackendLambdas } from '../BackendLambdas.js'
-import { STACK_NAME } from '../stacks/stackConfig.js'
+import { STACK_NAME } from '../stackConfig.js'
 import type { PublicDevices } from './PublicDevices.js'
 
 export class CustomDevicesAPI extends Construct {