Ctrlk
HomeAcademyLoginTry for free
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Operations best practices

Operational recommendations for CARTO Self-Hosted

Overview

Follow these best practices for ongoing CARTO Self-Hosted operations.

Manage configuration as code

Treat your configuration as a tracked, reviewable artifact — not ad-hoc edits against a live deployment. The specifics differ by deployment method, but the principles are the same.

For Helm deployments:

  • Keep customizations.yaml in version control (Git). It is the single file you own and the source of truth for your deployment. Commit every change so you have history, blame, and the ability to roll back.

  • Never edit configuration directly against the cluster. Change the file, review it, then apply with helm upgrade. This keeps what's deployed and what's in Git in sync.

  • Review changes before applying. Use pull requests for config changes, and run the preflight checks before helm upgrade so a bad value is caught before it reaches production.

  • Store carto-values.yaml and carto-secrets.yaml alongside it, but see secrets handling below — carto-secrets.yaml must never be committed in plaintext.

For Kots deployments:

  • Manage configuration through the Admin Console, not by hand. The Config tab is the source of truth, and Version history is your change log — every Save config + Deploy creates a version you can diff and redeploy.

  • Back up the configuration for disaster recovery instead of keeping a parallel copy by hand. Follow CARTO's Kots backup procedure, and for full DR best practices — snapshots that include the Admin Console, an out-of-cluster storage destination, and scheduled retention — follow Replicated's backup and restore with snapshots.

  • Only change the Custom Configuration field with CARTO Support guidance.

Secrets handling

Your license and credentials must never live in plaintext in version control.

  • Do not commit carto-secrets.yaml (or any secret values) to Git. Store them in a secrets manager — HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager — or encrypt them at rest with SOPS or Sealed Secrets.

  • Reference Kubernetes Secrets instead of inlining values. In customizations.yaml, prefer existingSecret references (as in the database and bucket examples) over embedding passwords directly.

  • Rotate credentials deliberately. See Rotating keys.

Configuration across upgrades

When you move to a new release, CARTO replaces carto-values.yaml (Helm) or the underlying chart (Kots). You only own your overrides — customizations.yaml for Helm, or the Admin Console config for Kots — so your settings carry forward. After any upgrade, re-review your configuration against the new release notes in case defaults or available options changed.

Update cadence

CARTO releases updates regularly with new features, bug fixes, and security patches. To stay supported and secure:

  • Check release notes monthly — review the CARTO Self-Hosted release notes for new versions

  • Stay within 2 minor versions of the latest release — older versions may not receive security backports

  • Test updates in a development environment first before applying to production

  • Schedule maintenance windows for upgrades to minimize user disruption

For Helm deployments, update by running helm upgrade with the new chart version. For Kots deployments, use the Version History tab in the Admin Console.

Backup strategy

What to back up:

Item
Backup method
Frequency
Retention

PostgreSQL metadata database

Cloud provider automated snapshot

Daily

30 days minimum

customizations.yaml

Version control (Git)

On every change

Indefinitely

carto-secrets.yaml

Secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager)

On every change

Indefinitely

The PostgreSQL database is the most critical component to back up. A lost metadata database means losing all maps, workflows, connections, and user data. Test your restore procedure at least quarterly.

Object storage: Import/Temp bucket files are ephemeral and do not need to be backed up. Assets/Thumbnails bucket files should be included in backups as they cannot be regenerated on demand. (Kots: Temp Bucket / Assets Bucket — Helm: Import Bucket / Thumbnails Bucket)

Monitoring and alerting

Configure alerts for the following conditions:

Alert
Threshold
Action

Pod restart count

> 2 restarts in 10 minutes

Investigate kubectl logs for the affected pod

PostgreSQL CPU utilization

> 80% sustained

Tune connection pool or scale the database instance

PostgreSQL storage

> 80% used

Scale storage or enable auto-grow

Valkey memory utilization

> 85% of maxmemory

Increase Valkey memory or review cache policy

API error rate

> 1% of requests

Check maps-api and workspace-api logs

Node disk usage

> 80%

Clean up unused images or expand disk

CARTO services emit structured logs to stdout/stderr and run as standard Kubernetes workloads, but CARTO does not include a bundled monitoring stack — collecting these logs and metrics and configuring alerting at the infrastructure level is your responsibility. Use your cloud provider's native monitoring (Cloud Monitoring, CloudWatch, Azure Monitor) or a third-party observability stack (Datadog, Prometheus + Grafana) to collect and route these alerts. See Monitoring & Observability for the full guidance.

Disaster recovery

Plan for the following failure scenarios:

Database failure: With a managed PostgreSQL service (Multi-AZ or high-availability configuration), failover is automatic. Ensure your CARTO configuration points to the database endpoint or connection string (not a specific IP) so it follows automatic failover.

Cluster failure (Kubernetes — Helm or Kots): If using Helm, your full deployment configuration is in version-controlled YAML files (customizations.yaml, carto-values.yaml, carto-secrets.yaml). Recovery involves provisioning a new cluster and running helm install. Target a Recovery Time Objective (RTO) based on your cluster provisioning time.

VM failure (Single VM — embedded cluster): The entire CARTO stack runs on one machine. If the VM fails, recovery involves:

  1. Provision a new VM of the same size

  2. Re-run the CARTO embedded cluster installer

  3. Restore the database from your latest snapshot

  4. Re-upload the license and re-apply your configuration in the Admin Console

Keep your license file and a record of all Admin Console settings (domain, database credentials, storage credentials) in a secure location so recovery does not require contacting support.

Full disaster recovery test: Run a full DR test at least twice a year:

Do not use your production license directly for DR tests. Contact CARTO Support before running a full recovery test, as the existing license must be freed before it can be applied to a new instance.

  1. Create a new cluster in a different region or zone

  2. Restore the database from the most recent snapshot

  3. Apply your Helm/Kots configuration and deploy CARTO

  4. Verify the application is functional

Capacity review

Review resource utilization quarterly:

  • Check CPU and memory usage across CARTO pods — scale before hitting 80% sustained utilization

  • Review PostgreSQL storage growth rate — project when you will need to expand

PreviousOperationsNextRelease Notes

Last updated

Was this helpful?