Create an appsync custom domain association in your Amplify project

setup.md

Pre-req

Create the custom domain name separately. Since the domain name is a longer-lived resource, you may not want it modified, or deleted by your application stack.

Do this in the console as shown in this blog, or use your favorite IaC tool.

Example with CDK:

import * as cdk from '@aws-cdk/core'
import { CfnDomainName } from '@aws-cdk/aws-appsync'

export class CustomDomainStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props)

    const domainName = 'my-custom-api.example.com'
    const certificateArn = 'arn:aws:acm:us-east-1:<account>:certificate/<id>'
    const dnr = new CfnDomainName(this, 'customDomainName', { domainName, certificateArn })

    new cdk.CfnOutput(this, 'appsyncDomainName', {
      value: dnr.attrAppSyncDomainName,
      description: 'The AppSync domain name',
    })

    new cdk.CfnOutput(this, 'hostedZone', {
      value: dnr.attrHostedZoneId,
      description: 'The ID of your Amazon Route 53 hosted zone',
    })
  }
}

Steps

1. Starting in the root directory of you Amplify project, create a new custom resource

$ amplify add custom
✔ How do you want to define this custom resource? · AWS CDK
✔ Provide a name for your custom resource · domainNameAssociation
✅ Created skeleton CDK stack in amplify/backend/custom/domainNameAssociation directory
✔ Do you want to edit the CDK stack now? (Y/n) · yes

2. switch to your custom resource directory

$ cd amplify/backend/custom/domainNameAssociation

3. update CDK depdencies to latest and install aws-appsync module (here it's 1.137.0)

  "dependencies": {
    "@aws-amplify/cli-extensibility-helper": "^2.0.0",
    "@aws-cdk/core": "1.137.0",
    "@aws-cdk/aws-appsync": "1.137.0"
  },

then

$ npm install

4. Define your custom resource. Edit amplify/backend/custom/domainNameAssociation/cdk-stack.ts.

import * as cdk from '@aws-cdk/core'
import * as AmplifyHelpers from '@aws-amplify/cli-extensibility-helper'
import { AmplifyDependentResourcesAttributes } from '../../types/amplify-dependent-resources-ref'
import { CfnDomainNameApiAssociation } from '@aws-cdk/aws-appsync'

export class cdkStack extends cdk.Stack {
  constructor(
    scope: cdk.Construct,
    id: string,
    props?: cdk.StackProps,
    amplifyResourceProps?: AmplifyHelpers.AmplifyResourceProps
  ) {
    super(scope, id, props)
    /* Do not remove - Amplify CLI automatically injects the current deployment environment in this input parameter */
    new cdk.CfnParameter(this, 'env', {
      type: 'String',
      description: 'Current Amplify CLI env name',
    })

    const dependencies: AmplifyDependentResourcesAttributes = AmplifyHelpers.addResourceDependency(
      this,
      amplifyResourceProps.category,
      amplifyResourceProps.resourceName,
      [{ category: 'api', resourceName: 'myapi' }]
    )

    const domainName = 'my-custom-api.example.com'
    const apiId = cdk.Fn.ref(dependencies.api.myapi.GraphQLAPIIdOutput)
    new CfnDomainNameApiAssociation(this, 'association', { domainName, apiId })
  }
}

5. Finally, deploy it:

$ amplify push --yes