Nov 23, 2020
How to set up custom domains for API Gateway with OVH
Unsettling at the start, but easier than it seems.
When working with AWS API Gateway, you will notice that the default URL of your stages is far from being user-friendly.
But the real problem is that the API’s ID is a part of the URL. If your API got deleted and re-created, this ID will no longer be the same, and so will be its URL.
And this is a problem. If your app uses those URLs, you could end up having to update every link leading to your REST API.
The best way to avoid that is to create a custom domain name in API Gateway. If your API’s ID changes, you just have to update the path of your custom domain in the API Gateway console.
Amazon Certificate Manager
First thing first, let’s head to Amazon Certificate Manager (ACM) to request a new certificate.
Select “Request public certificate”, then next.
You have to add at least one domain name, here I choose “yohann.tech”.
You also have the possibility to create additional domain names.
To accommodate any future domain, you can use a wildcard (*), like shown in the following screen :
This is also required if I want to use “www.yohann.tech”.
Click next, and you will arrive at the validation method.
ACM has to be sure that this domain is your property. To do so there are two options :
- DNS validation, covered in this article.
- Email validation, pretty straightforward but not always possible.
Select DNS validation and click next.
The next screen is about tags. This is optional, technically speaking, but recommended in your day to day AWS management. Yet, tag is a subject on its own, so we won’t cover it here.
Click “Review”.
You can review the certificates you are about to request, but there is nothing more to do on this page.
Click “Confirm and request” to create the records in ACM.
The next page displays the CNAME value you will have to register to OVH. In my case, both are the same.
Recording that CNAME is the proof that you own this domain.
It will unlock the capability to register the domain names you provided to ACM, here “yohann.tech” and “*.yohann.tech”, as custom domains for a variety of service, including API Gateway.
OVH
Keep the ACM validation page opened, and log in to your OVH account.
Open your domain configuration page.
Head to the DNS zone tab and click “Add an entry”.
On the next screen select CNAME, and click next.
The next step has 3 fields: Sub-domain, TTL, and Target.
Go back to the ACM validation page, and copy the first part of the name field for your domain. The name is created like: “xxx.yohann.tech”.
You need the first part, the “xxx”.
Paste this first part into the sub-domain field as shown below.
Go back to the ACM validation page and this time copy the “value” field entirely.
Paste it into the target field. You can leave the TTL “By default”, and you should end up with something like this :
Click next. The final step is a review of your configuration. Nothing to do here, except reviewing. You can “Confirm”.
As soon as you confirm, the CNAME is validated and needs to be propagated. ACM will check periodically the DNS records and will display “success” instead of “pending validation” once found.
On your ACM console, you should now have an “Issued” certificate.
This process can take a moment to happen. This is usually pretty quick — few minutes — but it can take up to 72 hours if you’re unlucky.
We are not done yet. We gave ACM the proof that we own this domain, but we did not create any sub-domain, and we did not link this sub-domain to API Gateway.
API Gateway
For the next part, head to the API Gateway console.
I created a REST API with only one route as an example for this article.
In the API Gateway console, go to “Custom Domain Names”, and click “Create”.
The “Create Domain Name” form appears. The first field is the domain name you want to create.
In this article, I recorded two domains in ACM: “yohann.tech” and “*.yohann.tech”, meaning that I can create any domain name I want.
If I only registered “dev.yohann.tech”, the only domain name I would be allowed to create is “dev.yohann.tech”.
In that case, if I wanted to create “prod.yohann.tech”, I would have to create a second ACM certificate for the domain “prod.yohann.tech”.
Keeping this in mind, choose the domain name you want
You can leave “Minimum TLS version” and “Mutual TLS authentication” by default.
In the “Endpoint configuration” part, select “Regional” and the certificate you created in ACM.
Only an “Issued” ACM certificate is visible in the dropdown field. If your certificate is still “pending validation” you won’t be able to select it here.
The next step, tags, is optional.
Click “Create domain name”, and you should end up with this screen :
We’re not done yet, the last part of the configuration is to tell the system where we want to route the user.
Click on the “API mappings” tab.
And click on “Configure API mapping”.
On the next page, click “Add new mapping”, and select the API you want to route, the stage you want to route, and an optional path.
Finally, you can click save and should see something like the following.
Aaaaaaaaaaand we are not done yet.
If you go to the domain you created, here “example.yohann.tech”, you will get something like this
That’s because we created the domain and its routing in API Gateway, but we did not register the new domain in our DNS.
Remember, the ACM part is only proof that you own the domain.
On the “Custom Domain Names” page, locate the “API Gateway domain name” for your domain.
Copy it, we will need it for the final part of this tutorial.
Go back to your OVH domain configuration, in the DNS zone like before, and click to create a new entry.
Select CNAME again, and now in the sub-domain field use the domain you created in API Gateway.
In the “Target *”, paste the “API Gateway domain name”, the URL you copied earlier.
Don’t forget to add a “.” at the end of the URL, this is needed to register your target as the full target.
You can click next, review, and confirm.
DNS propagation takes a bit of time, but usually, this is just a matter of minutes. You can follow this propagation with online tools, like https://dnschecker.org/.
Fill the field with your domain, select CNAME in the dropdown, and click search. The map will refresh the status of your domain.
When the propagation is finished, you can admire your brand new domain, and enjoy a nice cup of coffee as a reward.
Setting up a custom domain name may seem long and difficult, but as we can see the procedure is pretty easy.
And always the same.
Well done.
