Configure your own buckets (Helm)

For CARTO Self-hosted using Kubernetes and Helm

This documentation only applies to advanced Orchestrated container deployments using Kubernetes and Helm

1. Overview

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

Purpose	Is Mandatory?	Description	Example contents
1. Import Bucket	Yes	Used to upload and import datasets into CARTO.	.csv, .geojson, .zip
2. Thumbnails Bucket	Yes	Stores generated map thumbnails and customization assets (logos, markers, etc.).	.png images
3. Export Bucket	No, this bucket is optional	Used for exporting data from your data warehouse (BigQuery, Snowflake, Redshift, or Amazon RDS). Create this only if you plan to use data export features.	.csv, .json, .parquet

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

• Google Cloud Storage

• AWS S3

• Azure Blob Storage

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

   • BigQuery: Google Cloud Storage

   • Snowflake: AWS S3

   • Redshift: AWS S3

   • Amazon RDS: AWS S3

2. Pre-requisites

2.1. Create the required buckets

1. Import Bucket

2. Thumbnails Bucket

3. Export Bucket (optional)

There are no naming constraints for these buckets.

3. Configuration notes

3.1. Thumbnails bucket access

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

• To make them private, set:

  WORKSPACE_THUMBNAILS_PUBLIC="false"

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

  • Enable public objects

  • Allow ACLs (non-uniform permissions)

  • Disable server-side encryption

3.2. Export bucket provider requirements

Data Warehouse	Required Storage Provider
BigQuery	Google Cloud Storage
Snowflake	AWS S3
Redshift	AWS S3
Amazon RDS (PostgreSQL)	AWS S3

3.3. CORS Configuration

Required for Import and Thumbnails Buckets

Setting	Value
Allowed origins	*
Allowed methods	GET, PUT, POST
Allowed headers (common)	Content-Type, Content-MD5, Content-Disposition, Cache-Control
GCS extra headers	x-goog-content-length-range, x-goog-meta-filename
Azure extra headers	Access-Control-Request-Headers, X-MS-Blob-Type
Max age	3600

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

3.4. Authentication requirements

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

Provider	Auth Method
GCS	Service Account Key
AWS S3	Access Key ID + Secret Access Key
Azure Blob	Access Key

If you can't setup Service Account Keys, Access Keys or Secret Access Key due to security constraints or other reasons you can setup GCP Workload Identity or EKS Pod Identity using the following guides:

• Use Workload Identity in GCP (Helm)

• Use EKS Pod Identity in AWS (Helm)

4. Setup per provider

4.1 Import and Thumbnails buckets

Google Cloud Storage

In order to use Google Cloud Storage custom buckets you need to:

1. Add the following lines to your customizations.yaml and replace the <values> with your own settings:

appConfigValues:
  storageProvider: "gcp"
  workspaceImportsBucket: <import_bucket_name>
  workspaceImportsPublic: <false|true>
  workspaceThumbnailsBucket: <thumbnails_bucket_name>
  workspaceThumbnailsPublic: <false|true>
  thumbnailsBucketExternalURL: <public or authenticated external bucket URL>
  googleCloudStorageProjectId: <gcp_project_id>

Note that thumbnailsBucketExternalURL could be https://storage.googleapis.com/<thumbnails_bucket_name>/ for public access or https://storage.cloud.google.com/<thumbnails_bucket_name>/ for authenticated access.

1. Select a Service Account that will be used by the application to interact with the buckets. There are two options:

   1. Using a custom Service Account, that will be used not only for the buckets, but for the services deployed by CARTO as well. If you are using Workload Identity, that's your option.

   2. Using a dedicated Service Account only for the buckets

2. Grant the selected Service Account with the role roles/iam.serviceAccountTokenCreator in the GCP project where it was created.

⚠️ We don't recommend granting this role at project IAM level, but instead at the Service Account permissions level (IAM > Service Accounts > your_service_account > Permissions).

1. Grant the selected Service Account with the role roles/storage.admin to the buckets created.

2. [OPTIONAL] Pass your GCP credentials as secrets: This is only required if you are going to use a dedicated Service Account only for the buckets

   • Option 1: Automatically create the secret:

     appSecrets:
       googleCloudStorageServiceAccountKey:
         value: |
           <REDACTED>

   appSecrets.googleCloudStorageServiceAccountKey.value should be in plain text, preserving the multiline and correctly tabulated.

   • Option 2: Using existing secret: Create a secret running the command below, after replacing the <PATH_TO_YOUR_SECRET.json> value with the path to the file of the Service Account:

     kubectl create secret generic \
       [-n my-namespace] \
       mycarto-google-storage-service-account \
       --from-file=key=<PATH_TO_YOUR_SECRET.json>

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

     appSecrets:
       googleCloudStorageServiceAccountKey:
         existingSecret:
           name: mycarto-google-storage-service-account
           key: key

AWS S3

Azure Blob Storage

5. Data export bucket

5.1 BigQuery

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 pre-requisites.

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

appConfigValues:
    workspaceExportsBucket: <YOUR_EXPORTS_BUCKET>

5.2 Snowflake and Redshift

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.

If you've already configured the Import and Thumbnails buckets using AWS S3, you can use the same user you already created for these buckets.

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

   {
     "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Allow",
             "Principal": {
                 "AWS": "<your_aws_user_arn>"
             },
             "Action": [
                 "sts:AssumeRole",
                 "sts:TagSession"
             ]
         }
     ]
   }

   1. Add permissions: Create a new permissions' policy, replacing <your_aws_s3_bucket_name>.

   {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "s3:ListBucket",
              "Resource": "arn:aws:s3:::<your_aws_s3_bucket_name>"
          },
          {
              "Effect": "Allow",
              "Action": "s3:*Object",
              "Resource": "arn:aws:s3:::<your_aws_s3_bucket_name>/*"
          }
      ]
   }

2. Update your customizations.yaml file with the following values:

appConfigValues:
    awsExportBucket: <BUCKET_NAME>
    awsExportBucketRegion: <REGION>
    exportAwsRoleArn: <ROLE_ARN>

Pass your AWS credentials as secrets:

• Option 1: Automatically create the secret:

  appSecrets:
    exportAwsSecretAccessKey:
      value: <REDACTED>
    exportAwsAccessKeyId:
      value: <REDACTED>

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:

  kubectl create secret generic \
    [-n my-namespace] \
    mycarto-export-aws-access-key \
    --from-literal=key-id=<ACCESS_KEY_ID>
    --from-literal=key-secret=<ACCESS_KEY_SECRET>

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

  appSecrets:
    exportAwsSecretAccessKey:
      existingSecret:
        name: mycarto-export-aws-access-key
        key: key-id
    exportAwsAccessKeyId:
      existingSecret:
        name: mycarto-export-aws-access-key-id
        key: key-secret

Configure data exports in Amazon RDS for PostgreSQL

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 how to configure your S3 bucket integration for Amazon RDS for PostgreSQL.