APIs are deployed with a public API Gateway by default (the API Gateway forwards requests to the API load balancer). Each API can be independently configured to not create the API Gateway endpoint by setting api_gateway: none in the networking field of the Realtime API configuration and Batch API configuration. If the API Gateway endpoint is not created, your API can still be accessed via the API load balancer; cortex get API_NAME will show the load balancer endpoint if API Gateway is disabled. API Gateway is enabled by default, and is generally recommended unless it doesn't support your use case due to limitations such as the 29 second request timeout, or if you are keeping your APIs private to your VPC. See below for common configurations. To disable API Gateway cluster-wide (thereby enforcing that all APIs cannot create API Gateway endpoints), set api_gateway: none in your cluster configuration file (before creating your cluster).

By default, the API load balancer is public. You can configure your API load balancer to be private by setting api_load_balancer_scheme: internal in your cluster configuration file (before creating your cluster). This will force external traffic to go through your API Gateway endpoint, or if you disabled API Gateway for your API, it will make your API only accessible through VPC Peering. Note that if API Gateway is used, endpoints will be public regardless of api_load_balancer_scheme. See below for common configurations.

The API Gateway that Cortex creates in AWS is the "HTTP" type. If you need to use AWS's "REST" API Gateway, see here.

Common API networking configurations

Public https endpoint (with API Gateway)

This is the most common configuration for public APIs. Custom domains can be used with this setup, but are not required.

# cluster.yaml
​
api_load_balancer_scheme: internal

# cortex.yaml
​
- name: my-api
  ...
  networking:
    api_gateway: public  # this is the default, so can be omitted

Private https endpoint

You can configure your API to be private. If you do this, you must use VPC Peering to connect to your APIs.

The SSL certificate on the API load balancer is autogenerated during installation using localhost as the Common Name (CN). Therefore, clients will need to skip certificate verification when making HTTPS requests (e.g. curl -k). Alternatively, you can set up a custom domain, which will use ACM to provision SSL certs for your domain.

# cluster.yaml
​
api_load_balancer_scheme: internal  # this is the default, so can be omitted
​
# use this to configure a custom domain
# if you don't use a custom domain, clients will need to skip certificate verification when making HTTPS requests (e.g. `curl -k`)
ssl_certificate_arn: arn:aws:acm:us-west-2:***:certificate/***

# cortex.yaml
​
- name: my-api
  ...
  networking:
    api_gateway: none

Private http endpoint

You can configure your API to be private. If you do this, you must use VPC Peering to connect to your APIs.

# cluster.yaml
​
api_load_balancer_scheme: internal  # this is the default, so can be omitted

# cortex.yaml
​
- name: my-api
  ...
  networking:
    api_gateway: none

Public https endpoint (without API Gateway)

API gateway is generally recommended for public https APIs, but there may be a situation where you don't wish to use it (e.g. requests take longer than 29 seconds to complete, which is the max for API Gateway). In this case, clients can connect directly to the API load balancer.

The SSL certificate on the API load balancer is autogenerated during installation using localhost as the Common Name (CN). Therefore, clients will need to skip certificate verification when making HTTPS requests (e.g. curl -k). Alternatively, you can set up a custom domain, which will use ACM to provision SSL certs for your domain.

# cluster.yaml
​
api_load_balancer_scheme: internet-facing  # this is the default, so can be omitted
​
# use this to configure a custom domain
# if you don't use a custom domain, clients will need to skip certificate verification when making HTTPS requests (e.g. `curl -k`)
ssl_certificate_arn: arn:aws:acm:us-west-2:***:certificate/***

# cortex.yaml
​
- name: my-api
  ...
  networking:
    api_gateway: none

Public http endpoint

If you don't wish to use https for your public API, you can simply disable API gateway (your API will be accessed directly via the API load balancer):

# cluster.yaml
​
api_load_balancer_scheme: internet-facing  # this is the default, so can be omitted

# cortex.yaml
​
- name: my-api
  ...
  networking:
    api_gateway: none