Set up HTTPS on a subdomain

The recommended way to set up HTTPS with trusted certificates is by using API Gateway because it's simpler and enables you to use API Gateway features such as rate limiting (it also supports custom domains). This guide is only recommended if HTTPS is required and you don't wish to use API Gateway (e.g. it doesn't support your use case due to limitations such as the 29 second request timeout).

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) to support HTTPS traffic to Cortex APIs. By the end of this guide, you will have a Cortex cluster with APIs accessible via https://<your-subdomain>/<api-endpoint>.

You must own a domain and be able to modify its DNS records.

Step 1

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

This guide will use cortexlabs.dev as the example domain and api.cortexlabs.dev 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.

cortexlabs.dev 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

Step 15

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 16

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 kubernetes.io/service-name tag.

Take note of the load balancer's name.

step 16

Step 17

Go to the hosted zone you created in the Route 53 console and add an Alias record that routes traffic to your Cortex cluster's API load balancer (leave "Name" blank).

step 17

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 http://a5044e34a352d44b0945adcd455c7fa3-32fa161d3e5bcbf9.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json

Would become:

# replace loadbalancer url with your subdomain
curl https://api.cortexlabs.dev/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json

Debugging connectivity issues

You may encounter connectivity issues due to cached DNS records that haven't expired yet. It could take anywhere from a few minutes to 48 hours for DNS cache to completely refresh.

You could run into connectivity issues if you make a request to your API without waiting long enough after step 17.

To test connectivity try the following steps: 1. Deploy any api (e.g. iris-classifier). 1. Make an HTTPS GET request to the your api e.g. curl https://api.cortexlabs.dev/iris-classifier or enter the url in your browser. 1. If you run into an error such as curl: (6) Could not resolve host: api.cortexlabs.dev 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",...}

Cleanup

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