# Networking

![api architecture diagram](https://user-images.githubusercontent.com/808475/84695323-8507dd00-aeff-11ea-8b32-5a55cef76c79.png)

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](realtime-api/api-configuration.md) and [Batch API configuration](batch-api/api-configuration.md). 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](../cluster-management/config.md) 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](../cluster-management/config.md) 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.

## Common API networking configurations

### Public https endpoint (with API Gateway)

This is the most common configuration for public APIs. [Custom domains](../guides/custom-domain.md) can be used with this setup, but are not required.

```yaml
# cluster.yaml

api_load_balancer_scheme: internal
```

```yaml
# 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](../guides/vpc-peering.md) 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](../guides/custom-domain.md), which will use ACM to provision SSL certs for your domain.

```yaml
# 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/***
```

```yaml
# 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](../guides/vpc-peering.md) to connect to your APIs.

```yaml
# cluster.yaml

api_load_balancer_scheme: internal  # this is the default, so can be omitted
```

```yaml
# 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](../guides/custom-domain.md), which will use ACM to provision SSL certs for your domain.

```yaml
# 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/***
```

```yaml
# 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):

```yaml
# cluster.yaml

api_load_balancer_scheme: internet-facing  # this is the default, so can be omitted
```

```yaml
# cortex.yaml

- name: my-api
  ...
  networking:
    api_gateway: none
```
