search
HomeAcademyLoginTry for free

Updates (Helm)

For CARTO Self-hosted using Kubernetes and Helm

circle-info

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

hashtag
Support lifecycle policy

At CARTO, we are committed to providing reliable, secure, and high-quality support for all our users. To ensure the best experience, our support services are available only for CARTO Self-hosted versions released within the past 12 months.

Maintaining your installation on an up-to-date version is essential to:

  • Guarantee optimal performance of the platform.

  • Ensure security and compliance through the latest patches.

  • Benefit from continuous improvements, including new features and resolved issues.

triangle-exclamation

We strongly recommend that all users regularly update their CARTO installations. Doing so not only secures continued eligibility for support services but also allows you to take full advantage of CARTO’s latest capabilities and innovations.

Keeping your environment current is the best way to maximize the value of your CARTO deployment while ensuring stability, security, and a seamless user experience.

hashtag
Download customer package

Once a new release is available, you will need to download the latest customer package.

Clone the CARTO Self-Hosted github repo:

git clone https://github.com/CartoDB/carto-selfhosted.git
cd carto-selfhosted

Checkout to the latest stable releasearrow-up-right:

git checkout tags/2025.11.11

You should Install the following packages on your machine:yq, jq and gcloud.

Run the script passing the following arguments:

flag
description

-d

Directory containing the existing customer package files.

-s

Carto selfhosted installation mode. Possible values for mode are docker (Single VM deployment) and k8s(Orchestrated container deployment)

Example output:

hashtag
Upgrade Selfhosted version

Follow the steps below if you're using an Orchestrated container deployment in Kubernetes.

triangle-exclamation

Warning: Version rollbacks are not supported

CARTO Self-Hosted does not support rolling back to previous versions. This includes:

  • Using helm rollback to revert to an older release

  • Installing a previous chart version after upgrading

  • Downgrading the appVersion in any way

Why? Database schema migrations run automatically during upgrades and are designed to be forward-only. Rolling back the application while the database remains at a newer schema version will cause:

  • Application errors due to schema mismatches

  • Potential data corruption

  • Features becoming non-functional

triangle-exclamation

If an upgrade fails: Contact CARTO Support immediately. Do not attempt to rollback. If you must restore to a previous state, you will need to restore from a database backup taken before the upgrade and reinstall the matching chart version.

hashtag
Pre-Upgrade Requirements

circle-info

Important: Always Back Up Your Databases Before Upgrading

Before performing any upgrade to a new CARTO Self-Hosted version, you must create a backup of your databases:

  1. Backup the following databases:

    • metadata - Main CARTO metadata database (PostgreSQL) - Required

    • aiproxy - AI Proxy database (PostgreSQL) - Only if AI features are enabled

  2. Verify backups are complete and restorable before proceeding with the upgrade.

  3. Document the current chart version (helm list -n <namespace>) in case you need to reinstall.

This is your only recovery path if an upgrade fails. Without a pre-upgrade backup, rolling back to a previous working state is not possible.

hashtag
Run Helm upgrade

1) Update the helm chart:

2) Download the latest customer package (using the repo downloaded in the previous step)

./tools/carto-download-customer-package.sh -d . -s k8s

3) Upgrade the CARTO application

PreviousMaintenance (Helm)NextMonitoring (Helm)

Last updated

Was this helpful?