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.
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
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:
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:
Go to your DNS settings and add the record:
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:
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.
- all future updates
- full web-based access
- PDF and Epub versions