Configure an external proxy

This documentation is for the CARTO Self-Hosted Legacy Version. Use only if you've installed this specific version. Explore our latest documentation for updated features.

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:

Set the following environment variables (both in uppercase and lowercase) in your .env file:

HTTP_PROXY="http://my-proxy:3128"
http_proxy="http://my-proxy:3128"
HTTPS_PROXY="http://my-proxy:3128"
https_proxy="http://my-proxy:3128"
GRPC_PROXY="http://my-proxy:3128"
grpc_proxy="http://my-proxy:3128"
NO_PROXY="localhost,mega.io,dropbox.com,filestack.com"
no_proxy="localhost,mega.io,dropbox.com,filestack.com"

HTTP_PROXY (mandatory): Proxy connection string, consisting of http://<hostname>:<port>.
HTTPS_PROXY (mandatory): Same as HTTP_PROXY.
GRPC_PROXY (mandatory): Same as HTTP_PROXY.
NO_PROXY (optional): Comma-separated list of domains to exclude from proxying.

Add the following lines in your customizations.yaml file:

externalProxy:
  enabled: true
  host: <Proxy IP/Hostname>
  port: <Proxy port>
  type: http
  excludedDomains: ["localhost,.svc.cluster.local"]

The externalProxy.excludedDomains property contains 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.

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 excuded domains:

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:

Set the following environment variables (both in uppercase and lowercase) in your .env file:

HTTP_PROXY="https://my-proxy:3129"
http_proxy="https://my-proxy:3129"
HTTPS_PROXY="https://my-proxy:3129"
https_proxy="https://my-proxy:3129"
NO_PROXY="mega.io,dropbox.com,filestack.com"
no_proxy="mega.io,dropbox.com,filestack.com"
NODE_EXTRA_CA_CERTS=/opt/carto/certs/proxy-ca.crt
NODE_TLS_REJECT_UNAUTHORIZED=0

HTTP_PROXY (mandatory): Proxy connection string, consisting of https://<hostname>:<port>.
HTTPS_PROXY (mandatory): Same as HTTP_PROXY.
NO_PROXY (optional): Comma-separated list of domains to exclude from proxying.
NODE_EXTRA_CA_CERTS (optional): Path to the proxy CA certificate. If the proxy certificate is signed by a custom CA, such CA must be included here. If the proxy certificate is signed by a well known CA, there is no need to add it here. Well known CAs are usually part of the ca-certificates package
NODE_TLS_REJECT_UNAUTHORIZED (optional): Specify if CARTO Self-hosted should check if the proxy certificate is valid (1) or not (0). For instance, self signed certificates validation must be skipped.

Add the following lines in your customizations.yaml file:

externalProxy:
  enabled: true
  host: <Proxy IP/Hostname>
  port: <Proxy port>
  type: https
  excludedDomains: ["localhost,.svc.cluster.local"]
  ## NOTE: Please, carefully read CARTO Self-hosted proxy documentation to understand the  the current limitations with [custom CAs].
  sslRejectUnauthorized: true
  # sslCA: |
  #  -----BEGIN CERTIFICATE-----
  #  XXXXXXXXXXXXXXXXXXXXXXXXXXX
  #  -----END CERTIFICATE-----

externalProxy.excludedDomains : obtains 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.
externalProxy.sslRejectUnauthorized (optional): Specify if CARTO Self-hosted should check if the proxy certificate is valid or not. For instance, self-signed certificates validation must be skipped.
externalProxy.sslCA (optional): Path to the proxy CA certificate. If the proxy certificate is signed by a custom CA, such CA must be included here, but if it's signed by a well known CA, there is no need to add it here. Well known CAs are usually part of the ca-certificates package.

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.

Enhanced control over non-proxied egress traffic

The following configuration just applies for orchestrated container deployments of CARTO Self-Hosted, so if you're using the Single VM deployment this section must 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
        # Redis
        - 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.

PreviousEnable the CARTO Data Warehouse NextEnable BigQuery OAuth connections

Last updated 24 days ago