Configure an external proxy

For CARTO Self-hosted using Kots

CARTO Self-hosted supports operating behind an HTTP or HTTPS proxy. The proxy acts as a gateway, enabling CARTO Self-hosted components to establish connections with essential external services like CARTO licensing system, or auth.carto.com. You can find detailed information about these components and services in the network requirements section.

CARTO Self-hosted does not provide or install any proxy component; It's built to connect to an existing proxy software deployed on your side.

A comprehensive list of domains that must be whitelisted by the proxy for the proper operation of CARTO Self-hosted can be found here. Such list includes domains for the core services of CARTO Self-hosted, as well as some optional domains that should be enabled to access specific features.

HTTP

In order to configure an external HTTP proxy on your CARTO Self-hosted installation, you'll have to:

Single VM deployment

Update your installation so that it uses an HTTP proxy:

sudo ./carto install \
    --license license.yaml \
    --https-proxy=http://<your_proxy_host> \
    --http-proxy=http://<your_proxy_host> \
    --no-proxy=dropbox.io

The no-proxy flag receives a comma-separated list of domains to exclude from proxying.

Once the embedded cluster installation is done, you'll have to edit the config of CARTO Self-Hosted platform from the Admin Console to allow the usage of an external proxy.

Orchestrated container deployment

Update your installation so that it uses an HTTP proxy:

kubectl kots install carto \
  --namespace <namespace> \
  --http-proxy http://<your_proxy_host> \
  --https-proxy http://<your_proxy_host> \
  --no-proxy "localhost,.svc.cluster.local,<k8s_cluster_ip_service>"

The no-proxy flag receives a comma-separated list of domains to exclude from proxying. The .svc.cluster.local domain must be in the list to allow internal communication between components within your cluster.

In order to obtain the k8s_cluster_ip_service IP address is the one that belongs to the Cluster IP service that Kubernetes creates by default in your default namespace. You can obtain it running the following command:

kubectl get svc kubernetes -n default

Once your installation has been updated, you'll have to edit the config of CARTO Self-Hosted platform from the Admin Console to allow the usage of an external proxy.

Please, take into account that if you're configuring an external proxy in a CARTO Self-Hosted installation running in GKE with Workload Identity configured, you'll have to add the following excluded domains:

pubsub.googleapis.com,*.googleapis.com,169.254.169.254,metadata,metadata.google.internal

These domains are required when authenticating the requests performed from an installation using Workload Identity.

HTTPS

To configure an HTTPS proxy on CARTO Self-hosted, you'll have to change the following configuration:

Single VM deployment

Update your installation so that it uses an HTTPS proxy:

sudo ./carto install \
    --license license.yaml \
    --https-proxy=https://<your_proxy_host> \
    --http-proxy=https://<your_proxy_host> \
    --no-proxy=dropbox.io

The no-proxy flag receives a comma-separated list of domains to exclude from proxying.

If your proxy requires a custom Certificate Authority (CA), make sure it's already configured on the host where you're installing CARTO Self-Hosted. The installer will automatically inject the CA certificate to enable secure communication with your proxy.

Once the embedded cluster installation is done, you'll have to edit the config of CARTO Self-Hosted platform from the Admin Console to allow the usage of an external proxy.

Orchestrated container deployment

Update your installation so that it uses an HTTPS proxy:

kubectl kots install carto \
  --namespace <namespace> \
  --http-proxy https://<your_proxy_host> \
  --https-proxy https://<your_proxy_host> \
  --private-ca-configmap <your_ca_configmap>
  --no-proxy "localhost,.svc.cluster.local,<k8s_cluster_ip_service>"

If your proxy requires a custom Certificate Authority (CA), make sure it's already configured on the host where you're installing CARTO Self-Hosted. The installer will automatically inject the CA certificate to enable secure communication with your proxy.

The no-proxy flag receives a comma-separated list of domains to exclude from proxying. The .svc.cluster.local domain must be in the list to allow internal communication between components within your cluster.

In order to obtain the k8s_cluster_ip_service IP address is the one that belongs to the Cluster IP service that Kubernetes creates by default in your default namespace. You can obtain it running the following command:

kubectl get svc kubernetes -n default

Once your installation has been updated, you'll have to edit the config of CARTO Self-Hosted platform from the Admin Console to allow the usage of an external proxy.

Please, take into account that if you're configuring an external proxy in a CARTO Self-Hosted installation running in GKE with Workload Identity configured, you'll have to add the following excluded domains:

pubsub.googleapis.com,*.googleapis.com,169.254.169.254,metadata,metadata.google.internal

These domains are required when authenticating the requests performed from an installation using Workload Identity.

Support for data warehouses

While certain data warehouses can be configured to work with a proxy, there are some providers that will inherently bypass it. This means that the connection to these data warehouses won't be created through the proxy, so CARTO Self-hosted services will try to directly perform requests to the providers.

• BigQuery: It supports both HTTP and HTTPs proxy.

• PostgreSQL and Redshift: They use a TCP connection instead of HTTP(S), so the proxy is bypassed.

• Databricks: Proxy is not supported, so the HTTPS connection will be bypassed.

• Snowflake: It supports HTTP proxy, but HTTPS is not supported and will have to be bypassed. In order to bypass it, you'll have to add snowflakecomputing.com to the list of excluded domains.

When the proxy is bypassed, and you have a restrictive network policy in place, you will need to explicitly allow this egress of non-proxied traffic.

Limitations

Password authentication is not supported for the proxy connection.

Importing data using an HTTPS Proxy configured with a certificate signed by a Custom CA is not supported.