Configure a forward proxy

Route CARTO Self-Hosted outbound traffic through a forward proxy

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.

This is a forward proxy: it sits between CARTO and the internet and routes CARTO's outbound (egress) traffic to external services. It is not a reverse proxy for inbound user traffic — for publishing CARTO to your users, see Load balancing best practices.

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:

Kots

Kots

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 a forward proxy.

Orchestrated container deployment

Helm

HTTPS

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

Kots

Kots

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 a forward proxy.

Orchestrated container deployment

Helm

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.

• Oracle: 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 oraclecloud.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.

Enhanced control over non-proxied egress traffic

The following configuration applies only to Helm-based orchestrated container deployments of CARTO Self-Hosted. If you're using the Single VM deployment or Kots, this section can be skipped.

When no network policy is enforced, all outgoing traffic that does not pass through a proxy will be permitted.

In restrictive environments, it is indispensable to maintain strict control over connections made by CARTO Self-hosted components. To achieve this, you should configure your proxy to allow only approved external services (whitelisting), while blocking any other outgoing traffic that does not go through the proxy.

To accomplish this, you can apply a custom network policy, such as the one provided in this example:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: carto-no-internet-access
  # Optional labels
  labels:
    app.kubernetes.io/instance: <instance-name>
    app.kubernetes.io/managed-by: <managed-by>
    app.kubernetes.io/name: <app-name>
spec:
  # Match all Pods except the proxy Pod.
  # NOTE: Make sure your proxy pod has the label app.kubernetes.io/component: proxy
  # NOTE: Proxy pod is not deployed with the CARTO Self-hosted chart
  podSelector:
    matchExpressions:
      - key: app.kubernetes.io/component
        operator: NotIn
        values:
          - proxy
          - router
  policyTypes:
    - Ingress
    - Egress
  ingress:
    # Allow connections within the same namespace
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: <namespace>
  egress:
    # Allow connections within the same namespace
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: <namespace>
    # Allow DNS resolution
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: kube-system
        - podSelector:
            matchLabels:
              k8s-app: kube-dns
      ports:
        - port: 53
          protocol: UDP
    # Allow connections to external datawarehouses
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
      ports:
        # Postgres
        - port: 5432
          protocol: TCP
        # Redshift
        - port: 5439
          protocol: TCP
        # Valkey
        - port: 6379
          protocol: TCP
    # Allow connections to other datawarehouses hosts on port 443
    - to:
        - ipBlock:
            cidr: <CIDR>
      ports:
        - port: 443
          protocol: TCP

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.