This section contains guides to configure specific aspects of your CARTO Self-hosted installation.

The content of this section applies only to using Kubernetes and Helm

This document will walk you through the process of setting up OAuth connections in your CARTO Self-hosted installation, enabling secure and seamless authentication when creating your BigQuery connections from the CARTO platform.

Pre-requisites

1. Create an OAuth Consent Screen inside your Google Cloud Platform project

The first thing that has to be configured is an OAuth consent screen to allow the creation of OAuth connections. You'll have to navigate to APIs & Services > OAuth consent screen and enable this by filling up the application name, a support email for your consent screen, the authorized domain for your application and an email for developer contact. The authorized domain you choose should be the one used in the emails that will to use that feature..

The following are required to be able to create a BigQuery OAuth connection from CARTO platform.

• https://www.googleapis.com/auth/userinfo.email

• https://www.googleapis.com/auth/userinfo.profile

• https://www.googleapis.com/auth/bigquery

Navigate to APIs & Services > Credentials > Create credentials to access the OAuth credentials creation form. The following details will be required to create the OAuth client ID:

• Application type: Web application.

• Authorized JavaScript origins: https://<your_selfhosted_domain>.

• Authorized redirect URIs: https://<your_selfhosted_domain>/connections/bigquery/oauth.

Once the create button is clicked, you should be able to download the credentials generated for your application. These credentials will contain the required client_id and client_secret to enable OAuth connections in the CARTO installation.

Add the following lines to your customizations.yaml using the values you obtained from the credentials file:

Once you've configured your CARTO Self-Hosted platform to use the OAuth credentials created in GCP, the Sign in with Google button should be available from the Workspace

CARTO Self-hosted can be configured to use Google Basemaps in the builder, allowing you to choose between different Basemap styles provided by Google. All you need is a Google Maps API key and a few simple configuration steps.

Generate Google Maps API key

The CARTO Self-hosted deployment needs a Google Maps API key with the Google Maps JavaScript API enabled in order to use Google Basemaps from Builder. If you also want the Photorealistic 3D Tiles basemap, the Map Tiles API must be enabled on the same key. You can follow these steps to generate a new key:

1. Enable the Google Maps JavaScript API:

   • In the , navigate to the APIs & Services section and go to the Library tab

   • Click on the Enable APIs & Services button

   • Search for Google Maps JavaScript API and enable it. This API powers all 2D Google Basemaps (Roadmap, Satellite, Hybrid, Terrain, and the Google Maps versions of Positron, Voyager, and Dark Matter).

   • (Optional) Search for Map Tiles API and enable it only if you want the Photorealistic 3D Tiles basemap. Without it, the 3D Tiles option will fail to load in Builder; all other basemaps work without it.

1. Create Credentials:

• After enabling the APIs, navigate to Credentials tab

• Click on Create Credentials and pick API key. Your new API key should appear as soon as it's generated!

1. Copy Your API Key: This is the API Key that the CARTO Selfhosted instance will use to load the different Google Basemaps in Builder.

In order to enable Google Maps basemaps inside CARTO Self Hosted, you need to own a Google Maps API key and add one of the options below to your customizations file.

• Option 1: Automatically create the secret

Automatically create a secret based on the plain text value specified in your customizations.yaml file.

• Option 2: Manually create a secret:

Create a secret running the command below, after replacing the <REDACTED> values with your key values:

Add the following lines to your customizations.yaml, without replacing any value:

This guide provides instructions for enabling the necessary prerequisites to run CARTO AI features in a Self-Hosted environment managed via Helm. It covers configuration changes, deployment steps, and validation of the AI proxy resources.

Before modifying the Helm configuration, you must prepare your database and network environment.

To setup AI Features in CARTO Self-Hosted you need to already be using an external PostgreSQL metadata database. In legacy versions of CARTO Self-Hosted we provided an internal database that could be deployed as part of our Helm chart. If you're still using it, please get in touch with to plan the migration to an external database.

You can verify if you're using the internal database with the following command:

The AI Proxy service requires its own dedicated logical database within your PostgreSQL instance. The default recommended name is aiproxy

The is a default connection that will help you get started with our platform. It gives you access to some demo datasets in order to start using the platform from the very beginning in case you don't have your own data warehouse with spatial data yet. It will also allow using spatial datasets from CARTO’s Data Observatory without connecting your own data warehouse to get access to cloud resources.

By default, the CARTO Data Warehouse in CARTO Self-Hosted is disabled. In this state, certain functionalities are limited compared to when it's enabled. Understanding these limitations is essential for optimal use of CARTO's capabilities.

The CARTO platform has some demo tables, maps, and workflows powered by the CARTO Data Warehouse that can't be used when it is not enabled. Once it's enabled, you'll be able to complete the onboarding experience using these demo resources.

Without the CARTO Data Warehouse, you can still explore the , but you can’t subscribe or use the data it offers it in Workflows/Builder directly. Instead, you’ll need to contact our team, who can deploy a copy of the data in your Data Warehouse.

With the activation of the CARTO Data Warehouse, a dedicated connection is automatically established for every new created organization within your Self-Hosted installation. This seamlessly integrated connection allow users to import data and start using the platform's capabilities.

When deploying CARTO Self-Hosted, each installation is accompanied by a dedicated infrastructure, including a Service Account key necessary for utilizing certain deployed services. However, if you prefer to utilize your own Google Cloud Platform (GCP) Service Account, please follow these steps before initiating the Self-Hosted installation:

1. Create a Dedicated Service Account: Generate a dedicated Service Account specifically for your CARTO Self-Hosted deployment within your Google Cloud Platform console.

2. Contact CARTO Support: Reach out to our CARTO support team and provide them with the email associated with the Service Account you've created. This step ensures seamless integration of your Service Account with your CARTO Self-Hosted deployment. Email CARTO Support Team with the service account email.

To import data into Redshift through CARTO Self-Hosted, follow these step-by-step instructions.

1. Create an AWS IAM user with programmatic access. Take note of the user's ARN, Key ID and Key secret.

2. Create an AWS S3 Bucket:

   • ACLs should be allowed.

   • If server-side encryption is enabled, the user must be granted with permissions over the KMS key following the .

3. Create an AWS IAM role with the following settings:

   1. Trusted entity type: Custom trust policy.

   2. Custom trust policy: Make sure to replace <your_aws_user_arn>.
4. Configure your CARTO Self-Hosted deployment:\

   Add the following lines to your customizations.yaml file:

5. Update your installation to apply the changes.

6. Configure Redshift Integration in CARTO:

   1. Log into your CARTO Self-Hosted, go to Data Explorer > Connections > Add new connection and create a new Redshift connection.

   2. Then go to Settings > Advanced > Integrations > Redshift > New, introduce your S3 Bucket name and region and copy the policy generated.
7. Import Data to Redshift:

   1. Go to Data Explorer > Import data > Redshift connection. Now, you should be able to ! 🎉

allows Kubernetes pods in EKS clusters to securely assume specific AWS IAM roles, enabling secure, granular access to AWS resources without embedding credentials within the pods.

This approach enhances security by reducing the risk of exposed access keys and supports fine-grained access control by enabling distinct permissions for each workload. With EKS Pod Identity, managing access credentials becomes simpler and safer, allowing developers to control AWS resource permissions at the pod level.

Enabling EKS Pod Identity on a cluster allows assuming an IAM role from the pods deployed. When Amazon EKS starts a new pod that uses a service account with an EKS Pod Identity association it injects some environment variables in the pods that can be used to authenticate against AWS APIs.

In order to enable this feature in your EKS cluster, you can check the following .

CARTO Self-Hosted running on an EKS cluster can take advantage of EKS Pod Identity feature to connect to the PostgreSQL metadata database if it's deployed in RDS.

This guide outlines the steps to configure Single Sign-On (SSO) for your CARTO Self-Hosted instance. enhances security and user experience by allowing users to log in with a single set of credentials across multiple systems.

1. Contact CARTO Support:

   • Initiate contact with the CARTO Support team to request assistance with SSO configuration.

CARTO now supports tracking activity data from public maps, allowing administrators to measure the impact of their public maps by tracking interactions from unauthenticated visitors (e.g., views, exports, most active maps).

For more details, see: https://docs.carto.com/whats-new#tracking-activity-data-from-public-maps

This feature is not enabled by default. To enable it, add the following configuration in your customizations.yaml file:

appConfigValues:
  publicEventsApiEnabled: true

You'll have to deploy the new changes to you environment to ensure that the new component that will be handling the events triggered by your public maps is ready!

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:

Add the following lines in your customizations.yaml file:

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.

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

Add the following lines in your customizations.yaml file:

• 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.

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.

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:

Password authentication is not supported for the proxy connection.

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

• Custom Analytics Toolbox location

• Allow embedding CARTO into an iframe

• Enabling/Disabling TrackJS

The default location of the Analytics Toolbox can be customized for all connections in your CARTO Self-Hosted installation. If you edit this value, each new connection will have the AT location configured in the specified location:

Update your config in the customizations.yaml file:

CARTO Self-Hosted is prepared to be allowed into an iframe when needed. This way, custom applications using CARTO can work without any issue from an iframe. In order to allow your application using the platform through an iframe, you'll have to configure the allowed domains that can embed CARTO:

Update your customizations.yaml file:

TrackJS is a useful tool as it provides valuable insights into the performance and errors occurring within the CARTO platform.

TrackJS is enabled by default in the frontend components, but you can disable adding the following config in the customizations.yaml file:

The CARTO Self-Hosted deployment exposes the 443 port through a component called router, which is running a NGINX service under the hood. The following customization options are available for this service:

CARTO Self-Hosted connects to your data warehouse to perform different operations with your data. When connecting it with Postgres or Redshift, it's important to understand how the connection pool works.

Each node will have a connection pool controlled by the environment variables MAPS_API_V3_POSTGRES_POOL_SIZE and MAPS_API_V3_REDSHIFT_POOL_SIZE. The pool is per connection created from CARTO Self Hosted. If each user creates a different connection, each one will have its own pool. The maximum connections can be calculated with the following formula:

When a request is sent to an external data warehouse, we're applying some limits on the amount of time that a query can take to finish. If you'd like to customize the timeout applied to the queries executed against your data warehouse, you'll have to edit the following environment variables:

Their default value is set to 20 seconds. Please take into account that the updated value should be specified in milliseconds.

This guide outlines the steps to migrate the internal database of a CARTO Self-Hosted installation to an external database. By following these steps, you can seamlessly transition your CARTO workspace to a new database environment.

Prerequisites

Before starting the migration process, ensure that you have the following:

• Access to the CARTO Self-Hosted installation

• Credentials for the external database (hostname, port, username, password)

How to perform the migration to an external database

Step 1: Dump the Container Database

Use the following command to create a dump of the internal database:

1. Obtain the PostgreSQL password generated by the CARTO installation from the secret created for postgresql:\

1. Obtain the name of your workspace database pod. The following command should return a pod named postgresql

2. Run the following command to perform a backup of the internal database located in your cluster:

This command exports the database structure and data to a SQL file named dump.sql

Run the following command to create the necessary user in the new external database:

Execute the following commands to create the database in the external database:

Restore the dumped data into the new external database. If you have access to the external database using psql you can directly restore the database using the following command:

You have successfully migrated your CARTO Self-Hosted installation to an external database! 🎉 Ensure that you update your CARTO configuration files to reflect the changes in the database connection details. You can find more information about how to connect your Self-Hosted installation to an external database in our .

CARTO Self-Hosted requires Valkey (version 6 or above) to work. This Valkey instance does not need persistence, as it is used solely as a cache.

Both and come already with an internal Valkey deployment, but they lack any backups, autoscaling, or monitoring. Cloud vendors already offer Valkey deployments at scale as a service:

• .

• .

What is Workload Identity?

Applications running on Google Kubernetes Engine might need access to Google Cloud APIs such as Compute Engine API, BigQuery API, or Storage APIs.

Workload Identity allows a Kubernetes service account in your GKE cluster to act as an IAM service account. Pods that use the configured Kubernetes service account automatically authenticate as the IAM service account when accessing Google Cloud APIs. Using Workload Identity allows you to assign distinct, fine-grained identities and authorization for each application in your cluster.

How does Workload Identity work?

When you enable Workload Identity on a cluster, GKE automatically creates a fixed workload identity pool for the cluster's Google Cloud project. A workload identity pool allows IAM to understand and trust Kubernetes service account credentials. GKE uses this pool for all clusters in the project that use Workload Identity. The workload identity pool has the following format:

PROJECT_ID.svc.id.goog

When you configure a Kubernetes service account in a namespace to use Workload Identity, IAM authenticates the credentials using the following member name:

serviceAccount:PROJECT_ID.svc.id.goog[KUBERNETES_NAMESPACE/KUBERNETES_SERVICE_ACCOUNT]

In this member name:

• PROJECT_ID: your Google Cloud project ID.

• KUBERNETES_NAMESPACE: the namespace of the Kubernetes service account.

• KUBERNETES_SERVICE_ACCOUNT: the name of the Kubernetes service account making the request.

The process of configuring Workload Identity includes using an IAM policy binding to bind the Kubernetes service account member name to an IAM service account that has the permissions your workloads need. Any Google Cloud API calls from workloads that use this Kubernetes service account are authenticated as the bound IAM service account.

In order to enable Workload Identity in your CARTO Self-Hosted installation, you'll have to follow these steps:

1. Create an IAM service account for your application, or use an existing IAM service account instead.

1. Send email to CARTO Support Team with Service Account Contact CARTO Support to let us know the Service Account you want to use for Workload Identity. We will ensure that your Service Account is granted the required roles to run CARTO Self-Hosted.

1. Add the following lines to your customizations.yaml file:

1. Allow the Kubernetes service account that is going to be created in your GKE cluster to impersonate the IAM service account by adding an IAM policy binding between the two service accounts. This binding allows the Kubernetes service account to act as the IAM service account.

CARTO Self-Hosted running on a GKE cluster can take advantage of GKE Workload Identity feature to create a connection between the CARTO Self-Hosted platform and BigQuery without any user action.

1. Setup GKE Workload Identity for CARTO Self-Hosted following the .

2. Grant your Workload Identity service account with BigQuery to your data warehouse project.

3. Add the following environment variables in your customizations.yaml file:

1. Follow the previous command output and grant the service account the following role:

Once you've applied the changes performed in your customizations.yaml file, your CARTO deployment will automatically create a new BigQuery connection using Workload Identity owned by the CARTO user specified in the deployment configuration!

This guide provides best practices guidance for exposing CARTO Self-Hosted to users in production environments. It covers load balancing architectures, configuration patterns, and cloud provider-specific recommendations for Kubernetes deployments using Helm.

1. Prerequisites

• CARTO Self-Hosted deployed via Helm.

• Kubernetes cluster running on a cloud provider (GCP, AWS, or Azure).

• Understanding of Kubernetes Services and Ingress resources.

• Domain name configured for your CARTO deployment.

CARTO Self-Hosted uses a component called router-http as the main entry point for all HTTP/HTTPS traffic. You can see the details on Carto Self-hosted architecture here:

This router service can be exposed through different Kubernetes networking patterns:

Below you'll find in detail the two recommended patterns to publish your CARTO SelfHosted instance through a Load Balancer:

• Cloud Load Balancer + Router LoadBalancer Service.

• Ingress/GatewayAPI Layer + Router ClusterIP Service.

In this pattern, you define the service type as LoadBalancer. The Kubernetes Cloud Controller Manager talks directly to your cloud provider (AWS, GCP, Azure) to automatically provision and configure a native Cloud Load Balancer. You handle your own Cloud Load Balancing layer on top of this K8s integration.

Kubernetes requests a Load Balancer from the cloud provider. The cloud provider provisions it, assigns it a public/private IP, and automatically updates the backend target groups (nodes) as the cluster autoscales or nodes are replaced.

When to use:

• Simplicity: You want a dedicated Load Balancer for CARTO without the complexity of configuring an Ingress Controller.

• Automation: You want Kubernetes to automatically manage the backend node registration (avoiding the risk of stale Node IPs).

• Cloud-specific features: You need to utilize specific cloud features (like AWS NLB or Azure Internal LB) triggered via Service Annotations.

To enable this pattern, simply update the router service type in your values file.

You can customize the behavior of the cloud-provisioned Load Balancer (such as enabling SSL, setting timeouts, or making it internal-only) using annotations.

These annotations are specific to your Cloud Provider (AWS, GCP, Azure) and are passed directly to the router.service.annotations field.

Key configuration options:

This example configures an AWS Load Balancer with SSL termination, specific timeouts, and an internet-facing scheme.

• GCP Internal LB:

• Azure Internal LB:

• ✅ Automated Lifecycle: Kubernetes automatically updates the Load Balancer when nodes change or die.

• ✅ Cloud Integration: Deep integration with cloud provider features via annotations.

• ✅ Reduced Maintenance: No need to manually track Node Ports or update target groups.

The CARTO router service remains internal to the cluster (ClusterIP). A Kubernetes Ingress or GatewayAPI resource (managed separately from Helm) handles external access, SSL termination, and routing.

When to use:

• Standard Kubernetes deployments on cloud providers (GKE, EKS, AKS)

• Teams familiar with Kubernetes networking patterns

• Need for native Kubernetes certificate management (cert-manager, cloud-managed certs)

• Multi-service deployments sharing the same ingress controller

Configuration:

Key characteristics:

• ✅ Kubernetes-native: Uses standard Ingress resources and controllers

• ✅ Ecosystem integration: Works seamlessly with cert-manager, external-dns, etc.

• ✅ Simpler architecture: No need to manage node IPs or port mappings

CARTO Self-Hosted supports two primary SSL/TLS termination strategies. Your choice should align with your security requirements, compliance needs, and operational preferences:

• TLS Offloading (recommended): Termination occurs at the external Load Balancer or Ingress.

• End-to-End TLS: TLS traffic passes through to the CARTO Router, which handles termination.

Use this table to quickly determine the best strategy for your TLS/SSL Configuration in CARTO deployment.

In this recommended architecture, SSL/TLS is terminated at your Load Balancer or Ingress Controller. HTTP traffic is then forwarded internally to the CARTO Router.

When to Use

• Standard production deployments.

• Requirement for automated certificate provisioning and renewal (zero manual intervention).

• Integration with WAF or DDoS protection.

• Simplified operations with no certificate expiration concerns.

No explicit TLS configuration is needed within the CARTO Helm chart, the external component handles all SSL aspects.

In this setup, SSL/TLS remains encrypted all the way to the CARTO Router, which is responsible for TLS termination.

When to Use

• Strict compliance requirements mandating encryption throughout the infrastructure.

• Zero-trust architectures that require absolute end-to-end encryption.

• Requirement for Client Certificate Authentication.

Before configuring the Helm chart, you must obtain a valid SSL/TLS certificate from a Certificate Authority (CA).

Certificate Requirements:

• Valid SSL certificate for your CARTO domain

• Full certificate chain (server certificate + intermediate CA certificates)

• Private key corresponding to the certificate

• PEM-encoded format for both certificate and key

The Helm chart requires certificates to be base64-encoded without line breaks.

You must explicitly enable TLS and reference a Kubernetes secret containing your certificate and key.

1. Overview

Every CARTO Self-Hosted installation requires two cloud storage buckets to handle data and assets used by the platform:

You can create and use your own storage buckets in any of the following supported storage providers:

1. (Optional) Create the data export bucket. This bucket has to be created in different storage providers depending on your data warehouse:

   • BigQuery:

   • Snowflake:

1. Import Bucket

2. Thumbnails Bucket

3. Export Bucket (optional)

There are no naming constraints for these buckets.

• Thumbnails objects (.png) can be public (default) or private.

• To make them private, set:

• ⚠️ Some features (branding, custom markers) require public access. To keep the bucket private while allowing these features:

Required for Import and Thumbnails Buckets

CORS configuration location:

• GCS / S3: Bucket level

• Azure Blob: Storage account level

For more details, refer to:

• Google Cloud Storage CORS Setup

• AWS S3 CORS Setup

• Azure Blob CORS Setup

The buckets access from the Carto platform require authentication configuration. You'll find below the authentication methods available for each provider:

To enable exporting data from BigQuery on CARTO Self-Hosted platform these are the required steps:

1. Grant read/write permissions to the service account used by your CARTO Self-Hosted installation on the GCS bucket created in the .

2. Define the name the bucket that will be used for exporting data in your customizations.yaml file:

Snowflake and Redshift require an AWS S3 bucket to export data from CARTO platform. These are the needed steps for allowing exporting data from CARTO Self-Hosted in these providers:

1. Create an IAM user and generate a programmatic key ID and secret. If server-side encryption is enabled, the user must be granted with permissions over the KMS key used.

1. Create an AWS IAM role with the following settings:

   1. Trusted entity type: Custom trust policy.

   2. Custom trust policy: Make sure to replace <your_aws_user_arn>.

Pass your AWS credentials as secrets:

• Option 1: Automatically create the secret:

appSecrets.exportAwsSecretAccessKey.value and appSecrets.exportAwsAccessKeyId.value be in plain text, preserving the multiline and correctly tabulated.

• Option 2: Using existing secret: Create a secret running the command below:

  Add the following lines to your customizations.yaml, without replacing any value:

The bucket to export data from Amazon RDS for PostgreSQL can be configured from the CARTO platform UI. Once your Self-Hosted installation is finished, you can check in the following documentation .