Custom domains

By default, an AppSync API is available under https://<apiid>.appsync-api.eu-central-1.amazonaws.com/graphql. While it works for most cases, such as when you provide a webapp or a mobile app, as clients might not see this generated domain name. On cases when clients directly go to the API instead of some frontend application, offering the API under your own domain name is a requirement.

AppSync just recently started supporting custom domains. This works by creating a CloudFront distribution in the background and configure it to forward traffic to the AppSync endpoint.

In this chapter, we'll look into how to set up an AppSync domain on a custom URL. We'll see what prerequisites are needed in terms of certificates and domain setup and how to use the resulting endpoints.

Note

A custom endpoint supports only the AppSync API on it, so you can't host other parts of the infrastructure on the same host. For example, it's not possible to set up example.com as a webapp and example.com/graphql as the API enpoint.

To setup a custom domain, we need to do several steps:

  • Set up a certificate on ACM
  • Add the custom domain on AppSync
  • Associate the API with the custom domain
  • Forward traffic to the AppSync API
test.appsynctest.cloudns.clCustom domainAppSync APIACMDistribution1) Domain verificationCNAME2) Certificate3) associatecreates4) CNAME
Custom domain setup
Note

At first sight, it should be possible to set up a CloudFront distribution yourself and point it to the AppSync API URL instead of using the built-in custom domain feature. While this works for GraphQL queries, it won't work for the realtime WebSockets channel as it needs to encode the host in the query parameters. I spent quite some time finding a workaround but it seems like it is not supported.

ACM setup

Custom domains in AWS require an ACM certificate in the us-east-1 region for the domain. Make sure to select the N. Virginia region and add the domain name:

An ACM certificate for the domain in the us-east-1 region

Then AWS requires a verification which can be email-, or domain-based. The latter is the preferred way to verify ownership as after adding a record there is no manual action needed for renewals.

ACM shows the validation record you need to add:

ACM requires a CNAME record for verification

Go to your DNS settings and add the record:

The verification record added to the domain

If you use Route53 to manage the domain AWS even provides a button to do this. But if you use anything else, you can always manually add it.

Custom domain setting

Now that you have a valid ACM certificate for the domain, go to the AppSync console and add the custom domain:

The custom domain has a CloudFront domain name

Notice that the AppSync domain name is a cloudfront.net subdomain. This is not a coincidence: AWS creates a CloudFront distribution in the background, which also explains why it takes so long to create or make any changes to it.

Note

The CloudFront distribution comes with the usual problems regarding domain configuration: it only comes as a domain and not as an IP address. This means you can only setup a CNAME record when you forward traffic to it, and not an A (and AAAA) record and CNAME records are generally not supported on the apex (example.com) only on subdomains (test.example.com).

Several services support CNAME flattening which means they emulate the CNAME behavior but under the hood fetch the current IP address and return an A/AAAA record, such as Cloudflare. On Route53, you can configure an ALIAS for the A/AAAA records that point to an AWS service that solves this problem.

If you need to use the apex use a service that supports CNAME flattening or set up a Route53 Hosted Zone and use an NS record to delegate domain config there. See this article for more info.

Also notice that the real-time endpoint is on the same domain as the regular GraphQL endpoint. Amplify handles this automatically, but you might need to setup your client library if you use something else.

The next step is to associate the custom domain with the AppSync API:

The API has to be associated with the custom domain

Forward traffic

Finally, forward traffic going to the domain to the CloudFront distribution using a CNAME (or A/AAAA) record:

Forward traffic to the CloudFront domain

With this setup, the API is available under the custom domain:

Requests are handled on the custom domain

In the resolvers, the $context.request.domainName contains the domain the request came from. This makes it easy to distinguish between the different sources, especially as the original domain (https://<apiid>.appsync-api.eu-central-1.amazonaws.com/graphql) still works.

Master AppSync and GraphQL
Support this book and get all future updates and extra chapters in ebook format.