Set up a custom domain

You can use any custom domain (that you own) for your prediction endpoints. For example, you can make your API accessible via This guide will demonstrate how to create a dedicated subdomain in AWS Route 53 and use an SSL certificate provisioned by AWS Certificate Manager (ACM).

There are two methods for achieving this, and which method to use depends on whether you're using API Gateway or not (without API Gateway, requests are sent directly to the API load balancer instead). API Gateway is enabled by default.

The first set of steps are the same whether or not you're using API Gateway. If you aren't using API gateway, follow this guide before creating your Cortex cluster.

note: you must own a domain and be able to modify its DNS records to complete this guide.

Generate a certificate for your domain

Step 1

Decide on a subdomain that you want to dedicate to Cortex APIs. For example if your domain is, a valid subdomain can be

This guide will use as the example domain and as the subdomain.

Step 2

We will set up a hosted zone on Route 53 to manage the DNS records for the subdomain. Go to the Route 53 console and click "Hosted Zones".

step 2

Step 3

Click "Create Hosted Zone" and then enter your subdomain as the domain name for your hosted zone and click "Create".

step 3

Step 4

Take note of the values in the NS record.

step 4

Step 5

Navigate to your root DNS service provider (e.g. Google Domains, AWS Route 53, Go Daddy). Your root DNS service provider is typically the registrar where you purchased your domain (unless you have transferred DNS management elsewhere). The procedure for adding DNS records may vary based on your service provider.

We are going to add an NS (name server) record that specifies that any traffic to your subdomain should use the name servers of your hosted zone in Route 53 for DNS resolution. is managed by Google Domains. The image below is a screenshot for adding a DNS record in Google Domains (your UI may differ based on your DNS service provider).

step 5

Step 6

We are now going to create an SSL certificate for your subdomain. Go to the ACM console and click "Get Started" under the "Provision certificates" section.

step 6

Step 7

Select "Request a public certificate" and then "Request a certificate".

step 7

Step 8

Enter your subdomain and then click "Next".

step 8

Step 9

Select "DNS validation" and then click "Next".

step 9

Step 10

Add tags for searchability (optional) then click "Review".

step 10

Step 11

Click "Confirm and request".

step 11

Step 12

Click "Create record in Route 53". A popup will appear indicating that a Record is going to be added to Route 53. Click "Create" to automatically add the DNS record to your subdomain's hosted zone. Then click "Continue".

step 12

Step 13

Wait for the Certificate Status to be "issued". This might take a few minutes.

step 13

Step 14

Take note of the certificate's ARN. The certificate is ineligible for renewal because it is currently not being used. It will be eligible for renewal after it is used in Cortex.

step 14

If you are using API Gateway, continue to the next section to configure API Gateway. Otherwise (i.e. clients connect directly to your API load balancer) skip to configure the API load balancer.

Configure API Gateway

If you aren't using API Gateway (i.e. clients connect directly to your API load balancer), skip this section and configure the API load balancer instead.

Step 1

Navigate to the API Gateway console (make sure that the region in top right matches your Cortex region). Click "Custom domain names" and then click "Create".

step 1

Step 2

Type in the name of your domain and choose the Regional endpoint type, TLS 1.2, and the ACM certificate that you created earlier. Then click "Create".

step 2

Step 3

This should take you back to the custom domains page, and you should see your new custom domain. Make sure your API is selected. Take note of the API Gateway domain name (we will use this later), and click "Configure API mappings".

step 3

Step 4

Click "Add new mapping".

step 4

Step 5

Select your API Gateway, choose the "$default" stage, and lave "Path" blank. Click Save.

step 5

Step 6

Go back to the Route 53 console and select the hosted zone you created earlier. Click "Create Record Set", and add an Alias record that routes traffic to your Cortex cluster's API Gateway (the target name should match the "API Gateway domain name" show in step 3). Leave "Name" blank.

step 6

Proceed to using your new endpoint.

Configure the API load balancer

If you are using API Gateway, this section does not apply; follow the instructions above to configure API Gateway instead.

Step 1

Add the following field to your cluster configuration:

# cluster.yaml
ssl_certificate_arn: <ARN of your certificate>

and then create a Cortex cluster.

$ cortex cluster up --config cluster.yaml

Step 2

After your cluster has been created, navigate to your EC2 Load Balancer console and locate the Cortex API load balancer. You can determine which is the API load balancer by inspecting the tag.

Take note of the load balancer's name.

step 2

Step 3

Go back to the Route 53 console and select the hosted zone you created earlier. Click "Create Record Set", and add an Alias record that routes traffic to your Cortex cluster's API load balancer (leave "Name" blank).

step 3

Using your new endpoint

Wait a few minutes to allow the DNS changes to propagate. You may now use your subdomain in place of your API load balancer endpoint in your client. For example, this curl request:

curl -X POST -H "Content-Type: application/json" -d @sample.json

Would become:

# replace loadbalancer url with your subdomain
curl -X POST -H "Content-Type: application/json" -d @sample.json

Debugging connectivity issues

You could run into connectivity issues if you make a request to your API without waiting long enough for your DNS records to propagate after creating them (it usually takes 5-10 mintues). If you are updating existing DNS records, it could take anywhere from a few minutes to 48 hours for the DNS cache to expire (until then, your previous DNS configuration will be used).

To test connectivity, try the following steps:

  1. Deploy any api (e.g. examples/pytorch/iris-classifier).

  2. Make an HTTPS GET request to the your api e.g. curl or enter the url in your browser.

  3. If you run into an error such as curl: (6) Could not resolve host: wait a few minutes and make the HTTPS Get request from another device that hasn't made a request to that url in a while. A successful request looks like this:

{"message":"make a prediction by sending a post request to this endpoint with a json payload",...}


Spin down your Cortex cluster.

Delete the hosted zone for your subdomain in the Route 53 console:

delete hosted zone

Delete your certificate from the ACM console:

delete certificate