feat: add alternate domain names to cdn site host construct (#84)

.circleci/config.yml

@@ -104,6 +104,19 @@ jobs:
       - run:
           name: Build and deploy authenticated api example code
           command: cd examples/simple-authenticated-api && npm install && npm run build && npx cdk --require-approval never deploy
+  deploy-cdn-site-hosting:
+    executor: default_executor
+    steps:
+      - add_ssh_keys:
+          fingerprints:
+            - "ee:b4:00:e6:23:5b:55:bb:fd:07:bc:73:9e:f7:89:9c" # [email protected] 'talis-cdk-constructs Deploy Key'
+      - restore_root_build_number
+      - set_aws_prefix
+      - checkout
+      - node_install_packages
+      - run:
+          name: Build and deploy cdn site hosting example code
+          command: cd examples/simple-cdn-site-hosting-construct && npm install && npm run build && npx cdk --require-approval never deploy
   test:
     executor: default_executor
     steps:
@@ -146,6 +159,19 @@ jobs:
       - run:
           name: Destroy authenticated api example code
           command: cd examples/simple-authenticated-api && npm install && npm run build && npx cdk --require-approval never destroy --force
+  destroy-cdn-site-hosting:
+    executor: default_executor
+    steps:
+      - add_ssh_keys:
+          fingerprints:
+            - "ee:b4:00:e6:23:5b:55:bb:fd:07:bc:73:9e:f7:89:9c" # [email protected] 'talis-cdk-constructs Deploy Key'
+      - restore_root_build_number
+      - set_aws_prefix
+      - checkout
+      - node_install_packages
+      - run:
+          name: Destroy cdn site hosting example code
+          command: cd examples/simple-cdn-site-hosting-construct && npm install && npm run build && npx cdk --require-approval never destroy --force
   semantic-release:
     executor: default_executor
     steps:
@@ -197,10 +223,18 @@ workflows:
             - cdk-deploy-to-shared-aspire-20211202
             - aws-region-eu
             - talis-cdk-constructs-build
+      - deploy-cdn-site-hosting:
+          requires:
+            - build
+          context:
+            - cdk-deploy-to-shared-aspire-20211202
+            - aws-region-eu
+            - talis-cdk-constructs-build
       - test:
           requires:
             - deploy-lambda-worker
             - deploy-authenticated-api
+            - deploy-cdn-site-hosting
           context:
             - cdk-deploy-to-shared-aspire-20211202
             - aws-region-eu
@@ -219,10 +253,18 @@ workflows:
             - cdk-deploy-to-shared-aspire-20211202
             - aws-region-eu
             - talis-cdk-constructs-build
+      - destroy-cdn-site-hosting:
+          requires:
+            - test
+          context:
+            - cdk-deploy-to-shared-aspire-20211202
+            - aws-region-eu
+            - talis-cdk-constructs-build
       - semantic-release:
           requires:
             - destroy-lambda-worker
             - destroy-authenticated-api
+            - destroy-cdn-site-hosting
           context:
             - cdk-deploy-to-shared-aspire-20211202
             - aws-region-eu

examples/simple-cdn-site-hosting-construct/.gitignore

@@ -0,0 +1,8 @@
+*.js
+!jest.config.js
+*.d.ts
+node_modules
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

examples/simple-cdn-site-hosting-construct/.npmignore

@@ -0,0 +1,6 @@
+*.ts
+!*.d.ts
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

examples/simple-cdn-site-hosting-construct/README.md

@@ -0,0 +1,119 @@
+# CdnSiteHostingConstruct Example: SimpleCdnSiteHostingConstructStack
+
+This is an example of using the CdnSiteHostingConstruct and the CdnSiteHostingWithDnsConstruct in a simple stack to host a static website.
+
+The CdnSiteHostingConstruct:
+
+- creates a bucket to host the static html
+- creates a cloudfront distribution to server the website
+
+Optionionally, the CdnSiteHostingWithDnsConstruct:
+
+- sets up a DNS entry int Route 53 pointing at the cloudfront distribution
+
+## This Example
+
+To build and deploy this example:
+
+- `export AWS_PREFIX=development-XX-` where XX are your initials
+  - This is used in the name of the stack and resources created, so that they do not clash with anyone elses stack in AWS
+- `source awsenv <profile>` to set your credentials to the shared account
+- `npm install`
+- `npm run build`
+- `cdk deploy`
+
+After you have finished with the example, remove your stack in AWS using:
+
+- `cdk destroy`
+
+## Best Practice Using this Construct
+
+It's best practice NOT to create a DNS entry for a production website within a cloud formation stack. In production
+best practice is to be bring up a cloud formation stack and manually point a route 53 entry to the cloud front distribution.
+
+Why? We want the ability, if necessary, to bring up a new cloud formation stack and when we are happy that it is working
+as expected, switch the DNS manually to point to the new stack.
+
+Therefore, production deployments should use the CdnSiteHostingConstruct and set a watermarked sub domain name. For example:
+
+```typescript
+    new CdnSiteHostingConstruct(
+      this,
+      `TalisAppCdnSiteHostingConstruct`,
+      {
+        domainName: "talis.io",
+        siteSubDomain: `production-eu-20231025-talis-app`,
+        aliasSubDomains: ['talis-app'],
+        ...
+      },
+    );
+```
+
+The above will create a cloud front distribution with two aliases:
+
+- `production-eu-20231025-talis-app.talis.io`
+- `talis-app.talis.io`
+
+Outside of the cloud formation stack, DNS entries can be manually created for both the aliases and either can be used to access the website.
+
+Unfortunately, cloud front can NOT have the same alias on two different distributions. This means we can not always set the `talis-app` alias from
+the above example on a new cloud front distribution. i.e. Attempting to create:
+
+```typescript
+    new CdnSiteHostingConstruct(
+      this,
+      `TalisAppCdnSiteHostingConstruct`,
+      {
+        domainName: "talis.io",
+        siteSubDomain: `production-eu-20231026-talis-app`,
+        aliasSubDomains: ['talis-app'],
+        ...
+      },
+    );
+```
+
+will fail. Despite the cloud formation stack having a different watermark, 20231026 instead of 20231025, and the siteSubDomain being `production-eu-20231026-talis-app.talis.io` instead of `production-eu-20231025-talis-app.talis.io` - the creation of the stack will fail due to the duplicate alias `talis-app.talis.io`.
+
+Therefore - when bringing up a new watermarked stack alongside an already live production stack, the alias sub domain must not initially be set:
+
+```typescript
+    new CdnSiteHostingConstruct(
+      this,
+      `TalisAppCdnSiteHostingConstruct`,
+      {
+        domainName: "talis.io",
+        siteSubDomain: `production-eu-20231026-talis-app`,
+        aliasSubDomains: [],
+        ...
+      },
+    );
+```
+
+This will mean the new stack can be deployed and tested at the watermarked DNS name, e.g. `production-eu-20231026-talis-app.talis.io`.
+
+When ready to switch the stacks in production, the `talis-app.talis.io` alias needs to be deleted from the old stack and added to the new stack manually.
+The DNS is then switched from the old cloud front distribution to the new one.
+
+If this was a simple DNS change, there would be no downtime. But due to the need to delete and recreate the alias on the cloud front distribution, there is a small
+period where the website is in accessible. Therefore, for a production site, ONLY when switching to a new cloud formation stack, NOT on every release, a maintenance
+window is required for the switch over.
+
+Subsequent deployments after the stack switch over DO need to add in the `talis-app` alias to the aliasSubDomains property of the construct. If they do not,
+the alias will be deleted and an outage will occur.
+
+This process should be managed via the hercules deployment script - setting up the `aliasSubDomain` for a standard deploy to the live watermark to include the
+additional alias. When a different watermark is specified, to bring up a new none live stack, hercules should ensure the `aliasSubDomain` property does not
+contain the additional alias.
+
+This will require logic in both the hercules script and the projects CDK deployment code to ensure this property is set correctly.
+
+LINK TO EXAMPLE HERE WHEN WE HAVE ONE
+
+## Useful commands
+
+- `npm run build` compile typescript to js
+- `npm run watch` watch for changes and compile
+- `npm run test` perform the jest unit tests
+- `cdk deploy` deploy this stack to your default AWS account/region
+- `cdk diff` compare deployed stack with current state
+- `cdk synth` emits the synthesized CloudFormation template

examples/simple-cdn-site-hosting-construct/bin/simple-cdn-site-hosting-construct.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import "source-map-support/register";
+import * as cdk from "aws-cdk-lib";
+import { SimpleCdnSiteHostingConstructStack } from "../lib/simple-cdn-site-hosting-construct-stack";
+
+const app = new cdk.App();
+new SimpleCdnSiteHostingConstructStack(
+  app,
+  `${process.env.AWS_PREFIX}simple-cdn-site-hosting-construct-stack`,
+  {
+    env: {
+      account: process.env.CDK_DEFAULT_ACCOUNT,
+      region: process.env.CDK_DEFAULT_REGION,
+    },
+  },
+);

examples/simple-cdn-site-hosting-construct/cdk.context.json

@@ -0,0 +1,6 @@
+{
+  "hosted-zone:account=302477901552:domainName=talis.io:region=eu-west-1": {
+    "Id": "/hostedzone/ZQLU3GTNLTUB",
+    "Name": "talis.io."
+  }
+}

examples/simple-cdn-site-hosting-construct/cdk.json

@@ -0,0 +1,55 @@
+{
+  "app": "npx ts-node --prefer-ts-exts bin/simple-cdn-site-hosting-construct.ts",
+  "watch": {
+    "include": ["**"],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "**/*.d.ts",
+      "**/*.js",
+      "tsconfig.json",
+      "package*.json",
+      "yarn.lock",
+      "node_modules",
+      "test"
+    ]
+  },
+  "context": {
+    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
+    "@aws-cdk/core:checkSecretUsage": true,
+    "@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
+    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
+    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
+    "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
+    "@aws-cdk/aws-iam:minimizePolicies": true,
+    "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
+    "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
+    "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
+    "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
+    "@aws-cdk/aws-apigateway:disableCloudWatchRole": true,
+    "@aws-cdk/core:enablePartitionLiterals": true,
+    "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
+    "@aws-cdk/aws-iam:standardizedServicePrincipals": true,
+    "@aws-cdk/aws-ecs:disableExplicitDeploymentControllerForCircuitBreaker": true,
+    "@aws-cdk/aws-iam:importedRoleStackSafeDefaultPolicyName": true,
+    "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true,
+    "@aws-cdk/aws-route53-patters:useCertificate": true,
+    "@aws-cdk/customresources:installLatestAwsSdkDefault": false,
+    "@aws-cdk/aws-rds:databaseProxyUniqueResourceName": true,
+    "@aws-cdk/aws-codedeploy:removeAlarmsFromDeploymentGroup": true,
+    "@aws-cdk/aws-apigateway:authorizerChangeDeploymentLogicalId": true,
+    "@aws-cdk/aws-ec2:launchTemplateDefaultUserData": true,
+    "@aws-cdk/aws-secretsmanager:useAttachedSecretResourcePolicyForSecretTargetAttachments": true,
+    "@aws-cdk/aws-redshift:columnId": true,
+    "@aws-cdk/aws-stepfunctions-tasks:enableEmrServicePolicyV2": true,
+    "@aws-cdk/aws-ec2:restrictDefaultSecurityGroup": true,
+    "@aws-cdk/aws-apigateway:requestValidatorUniqueId": true,
+    "@aws-cdk/aws-kms:aliasNameRef": true,
+    "@aws-cdk/aws-autoscaling:generateLaunchTemplateInsteadOfLaunchConfig": true,
+    "@aws-cdk/core:includePrefixInUniqueNameGeneration": true,
+    "@aws-cdk/aws-efs:denyAnonymousAccess": true,
+    "@aws-cdk/aws-opensearchservice:enableOpensearchMultiAzWithStandby": true,
+    "@aws-cdk/aws-lambda-nodejs:useLatestRuntimeVersion": true,
+    "@aws-cdk/aws-efs:mountTargetOrderInsensitiveLogicalId": true
+  }
+}

examples/simple-cdn-site-hosting-construct/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  testEnvironment: 'node',
+  roots: ['<rootDir>/test'],
+  testMatch: ['**/*.test.ts'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest'
+  }
+};

examples/simple-cdn-site-hosting-construct/lib/simple-cdn-site-hosting-construct-stack.ts

@@ -0,0 +1,64 @@
+import * as cdk from "aws-cdk-lib";
+import { aws_s3_deployment as s3deploy } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import * as path from "path";
+
+import {
+  CdnSiteHostingConstruct,
+  CdnSiteHostingWithDnsConstruct,
+} from "../../../lib";
+
+export const STAGING_TALIS_IO_TLS_CERT_ARN =
+  "arn:aws:acm:us-east-1:302477901552:certificate/7973186a-2f4f-4d4e-92c7-d50f92f32718";
+
+export class SimpleCdnSiteHostingConstructStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    // Use AWS_PREFIX to give all resources in this sample
+    // a unique name. This is usually `development-xx` where xx are your initials.
+    // If you do not set AWS_PREFIX, when you deploy this stack, it may conflict
+    // with someone elses stack who has also not set AWS_PREFIX
+    const prefix = process.env.AWS_PREFIX
+      ? process.env.AWS_PREFIX
+      : "development-xx-";
+
+    // Create a site without setting DNS
+    /* const cdnSiteHostingConstruct = */ new CdnSiteHostingConstruct(
+      this,
+      `${prefix}CdnSiteHostingConstruct`,
+      {
+        domainName: "talis.io",
+        removalPolicy: cdk.RemovalPolicy.DESTROY,
+        // siteDomain: This would be the watermarked domain name e.g. elevate-20231025 from https://elevate-20231025.talis.com
+        siteSubDomain: `${prefix}cdn-site-hosting-construct`,
+        // aliasSubDomains: The production stack would supply this alias, e.g. elevate.talis.com
+        aliasSubDomains: [`${prefix}cdn-site-hosting-construct-alias`],
+        sources: [
+          s3deploy.Source.asset(path.resolve(__dirname, "./static-site")),
+        ],
+        websiteIndexDocument: "index.html",
+        certificateArn: STAGING_TALIS_IO_TLS_CERT_ARN,
+      },
+    );
+
+    // Create a site with DNS
+    /* const cdnSiteHostingWithDnsConstruct = */ new CdnSiteHostingWithDnsConstruct(
+      this,
+      `${prefix}CdnSiteHostingWithDnsConstruct`,
+      {
+        domainName: "talis.io",
+        removalPolicy: cdk.RemovalPolicy.DESTROY,
+        // siteSubDomain: This would be the watermarked domain name e.g. elevate-20231025 from https://elevate-20231025.talis.com
+        siteSubDomain: `${prefix}cdn-site-hosting-with-dns-construct`,
+        // aliasSubDomains: The production stack would supply this alias, e.g. elevate.talis.com
+        aliasSubDomains: [`${prefix}cdn-site-hosting-with-dns-construct-alias`],
+        sources: [
+          s3deploy.Source.asset(path.resolve(__dirname, "./static-site")),
+        ],
+        websiteIndexDocument: "index.html",
+        certificateArn: STAGING_TALIS_IO_TLS_CERT_ARN,
+      },
+    );
+  }
+}

examples/simple-cdn-site-hosting-construct/lib/static-site/index.html

@@ -0,0 +1 @@
+<h1>Test Deployment</h1>