Object Storage (blob buckets)

Object storage (blob buckets) prerequisites for CARTO Self-Hosted

CARTO Self-Hosted requires object storage that you provide and manage in your own cloud account. Complete all steps on this page before deploying CARTO. See How CARTO uses Object Storage for background.

Supported providers

Provider	Service
Google Cloud	Cloud Storage (GCS)
Amazon Web Services	Amazon S3
Microsoft Azure	Azure Blob Storage
Any S3-compatible provider	Oracle OCI, OVH, Ceph, and others

Required buckets

The bucket names shown in the Admin Console (Kots) and in customizations.yaml (Helm) differ. There are no naming constraints; use any names that comply with your cloud provider's rules.

☸️ Kots (Admin Console)

Bucket	Required	Purpose
Temp Bucket	Yes	Upload and import datasets into CARTO
Assets Bucket	Yes	Store generated map thumbnails and customization assets
Export Bucket	Optional	Export data from your data warehouse

🛞 Helm (customizations.yaml)

Bucket	Required	Config key	Purpose
Import Bucket	Yes	workspaceImportsBucket	Upload and import datasets into CARTO
Thumbnails Bucket	Yes	workspaceThumbnailsBucket	Store generated map thumbnails and customization assets
Export Bucket	Optional	workspaceExportsBucket (BigQuery) / awsExportBucket (S3)	Export data from your data warehouse

Export bucket provider: Two warehouses require a specific provider, because they write the export file themselves. The rest work with any supported store:

Data Warehouse	Required Storage Provider
BigQuery	Google Cloud Storage
Redshift	AWS S3
Snowflake, Oracle, PostgreSQL, Databricks	Any bucket CARTO supports — GCS, AWS S3, Azure Blob, or an S3-compatible store

---

Setting up your buckets

Select your cloud provider and follow the steps to create the buckets, configure CORS, and set up access permissions before deploying CARTO:

Google Cloud Storage

1. Create the buckets

Create the following buckets in GCS:

1. Temp Bucket (Kots) / Import Bucket (Helm)

2. Assets Bucket (Kots) / Thumbnails Bucket (Helm)

3. Export Bucket (optional, only if you plan to export data from your data warehouse)

Custom markers won't work unless the Assets / Thumbnails bucket is public.

2. Configure CORS

Temp/Import and Assets/Thumbnails buckets require CORS configured at the bucket level:

[
  {
    "origin": ["*"],
    "method": ["GET", "PUT", "POST"],
    "responseHeader": [
      "Content-Type",
      "Content-MD5",
      "Content-Disposition",
      "Cache-Control",
      "x-goog-content-length-range",
      "x-goog-meta-filename"
    ],
    "maxAgeSeconds": 3600
  }
]

How do I set up CORS? Check the GCS provider docs.

3. Configure access permissions

Ensure that the identity used to access your GCS buckets has read/write permissions on all of them. It should have the roles/storage.admin role over the buckets that will be used.

Provide the Project ID of the GCP project where your buckets are located. You will need this when configuring CARTO.

If you can't set up Service Account Keys due to security constraints, you can use keyless identity federation instead: Use Workload Identity in GCP.

AWS S3

1. Create the buckets

Create the following buckets in your AWS S3 account:

1. Temp Bucket (Kots) / Import Bucket (Helm)

2. Assets Bucket (Kots) / Thumbnails Bucket (Helm)

3. Export Bucket (optional, only if you plan to export data from your data warehouse)

When creating your S3 buckets:

• ACLs must be enabled — CARTO sets public-read permissions on individual thumbnail objects.

• If server-side encryption is enabled, the user must be granted permissions over the KMS key — see AWS documentation.

Custom markers won't work unless the Assets / Thumbnails bucket has ACLs enabled.

2. Configure CORS

Temp/Import and Assets/Thumbnails buckets require CORS configured at the bucket level:

[
  {
    "AllowedHeaders": [
      "Content-Type",
      "Content-MD5",
      "Content-Disposition",
      "Cache-Control"
    ],
    "AllowedMethods": ["PUT", "POST", "GET"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3600
  }
]

How do I set up CORS? Check the S3 provider docs.

3. Configure access permissions

Create an IAM user and generate a programmatic Access Key ID and Secret Access Key with read/write access permissions over the buckets. All buckets must be in the same AWS region.

If you can't set up Access Keys due to security constraints, you can use keyless identity federation instead: Use EKS Pod Identity in AWS.

Azure Blob Storage

1. Create the containers

Create the following containers in your Azure Blob storage account:

1. Temp Bucket (Kots) / Import Bucket (Helm)

2. Assets Bucket (Kots) / Thumbnails Bucket (Helm)

3. Export Bucket (optional, only if you plan to export data from your data warehouse)

Custom markers won't work unless the Assets / Thumbnails container is public.

2. Configure CORS

Temp/Import and Assets/Thumbnails containers require CORS configured at the storage account level:

[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST"],
    "AllowedHeaders": [
      "Content-Type",
      "Content-MD5",
      "Content-Disposition",
      "Cache-Control",
      "x-ms-blob-type",
      "Access-Control-Request-Headers"
    ],
    "ExposedHeaders": [],
    "MaxAgeInSeconds": 3600
  }
]

If you're using the Azure Portal, these fields map directly to the CORS blade's columns: Allowed origins, Allowed methods, Allowed headers, Exposed headers, and Max age. Enter the values as plain comma-separated names, without the JSON quotes or brackets — pasted quotes become part of the stored header names, and Azure will then silently reject upload (PUT) preflights while GET keeps working. How do I set up CORS? Check the Azure provider docs.

3. Configure access

Generate an Access Key from the storage account's Security properties. You will need this when configuring CARTO.

S3-compatible

Follow the AWS S3 steps above — create the buckets, apply the same CORS policy, and generate an access key pair with read/write access over them. Your provider's console will use its own names for these, and its CORS syntax may differ; the origins, methods, and headers to allow are the same.

Your store must support:

• Signature Version 4 authentication

• Presigned URLs for GET and PUT — browsers upload and download objects directly

• CORS configured per bucket, or account-wide

Note down your endpoint — the URL clients use to reach your store, for example https://objects.example.com. CARTO needs it.

CARTO sets public-read on individual thumbnail objects. If your provider doesn't honour object ACLs, keep the assets bucket private; CARTO then serves those objects through signed URLs instead.

---

Checklist

☸️ Kots (Admin Console)

• Temp Bucket created

• Assets Bucket created

• Export Bucket created (only if you'll export data)

• CORS applied to Temp and Assets buckets

• CARTO has read/write access to all buckets

• Bucket names and credentials are ready to enter in the Admin Console

🛞 Helm (customizations.yaml)

• Import Bucket created (workspaceImportsBucket)

• Thumbnails Bucket created (workspaceThumbnailsBucket)

• Export Bucket created (only if you'll export data)

• CORS applied to Import and Thumbnails buckets

• CARTO has read/write access to all buckets

• Bucket names and credentials are ready to add to customizations.yaml

Once your buckets are ready, configure CARTO to use them in Configure your own buckets.