# Updates (Helm)

{% hint style="info" %}
This documentation only applies to **advanced Orchestrated container deployments** using **Kubernetes** and **Helm**
{% endhint %}

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

{% hint style="danger" %}
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.
{% endhint %}

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.

## 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 release](https://github.com/CartoDB/carto-selfhosted/releases):

```
git checkout tags/2026.3.10
```

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

Run the script passing the following arguments:

<table><thead><tr><th width="132.5" align="center">flag</th><th>description</th></tr></thead><tbody><tr><td align="center"><code>-d</code></td><td>Directory containing the existing customer package files.</td></tr><tr><td align="center"><code>-s</code></td><td>Carto selfhosted installation mode. Possible values for mode are <code>docker</code> (Single VM deployment) and <code>k8s</code>(Orchestrated container deployment)</td></tr></tbody></table>

<pre class="language-bash" data-full-width="false"><code class="lang-bash"><strong>./tools/carto-download-customer-package.sh -s k8s -d /tmp/carto
</strong></code></pre>

Example output:

```bash
ℹ️  selfhosted mode: k8s
✅ found: ../carto3-onprem-customers/package/mcalzado-sh/k8s/carto-values.yaml
✅ found: ../carto3-onprem-customers/package/mcalzado-sh/k8s/carto-secrets.yaml
✅ activating: service account credentials for: [serv-onp-mcalzado-sh@carto-tnt-onp-mcalzado-sh.iam.gserviceaccount.com]
ℹ️  latest version: 2025-1-10
ℹ️  download file: gs://carto-tnt-onp-mcalzado-sh-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-mcalzado-sh-2025-1-10.zip
Copying gs://carto-tnt-onp-mcalzado-sh-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-mcalzado-sh-2025-1-10.zip...
/ [1 files][  3.0 KiB/  3.0 KiB]                                                
Operation completed over 1 objects/3.0 KiB.                                      
✅ downloading: carto-selfhosted-k8s-customer-package-mcalzado-sh-2025-1-10.zip

##############################################################
Current selfhosted version in [carto-values.yaml]: feature/sc-446879/enable-firestore-in-the-carto-sh-licenses-2
Latest selfhosted version downloaded: 2025-1-10
Downloaded file: carto-selfhosted-k8s-customer-package-mcalzado-sh-2025-1-10.zip
Downloaded from: gs://carto-tnt-onp-mcalzado-sh-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-mcalzado-sh-2025-1-10.zip
##############################################################

✅ finished [0]
```

## Upgrade Selfhosted version

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

{% hint style="danger" %}
**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
  {% endhint %}

{% hint style="danger" %}
**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.
{% endhint %}

### Pre-Upgrade Requirements

{% hint style="info" %}
Important: **Always Back Up Your Databases Before Upgrading**
{% endhint %}

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.

### Run Helm upgrade

1\) Update the helm chart:

```
helm repo update
```

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

```
helm upgrade \
  carto \
  carto/carto \
  -f carto-values.yaml \
  -f carto-secrets.yaml \
  -f customizations.yaml
```