How Configuration Works
Understand how configuration works in CARTO Self-Hosted, and how it differs between Helm and Kots
Overview
Your configuration is the set of environment-specific settings that make a deployment yours — domain, database connection, storage buckets, cache, SSO, AI features, and so on. Together with the metadata database, it is one of the two restore-critical elements of an installation.
How you manage that configuration depends on your deployment method:
Helm uses a file-based model — you own a set of YAML files and apply them with
helm upgrade.Kots (Standard Orchestrated and Single VM) uses the Admin Console — a web UI that stores your configuration in the cluster and versions it for you.
Understanding which model applies to you determines where your configuration lives, how you change it, and how you track it over time.
Configuration by deployment method
A Kots deployment is configured through the Admin Console — a web UI that lets you set everything without editing YAML by hand. Your configuration is stored in the cluster, not in files you keep.
The Config tab groups all editable settings (Application, Database, Object Storage, Cache, Networking, SSO, AI Features). After editing, you Save config and Deploy to apply changes — see Apply configuration changes for the step-by-step.
The Version history tab is your built-in change log: it lists every deployed version and lets you view the diff between them (config changes and image updates) and roll a configuration forward to a specific version.
The Custom Configuration field is a free-form YAML escape hatch for advanced Helm values, deep-merged last. Use it only with CARTO Support guidance.
Manage Kots configuration through the Admin Console, and back it up for disaster recovery following CARTO's Kots backup procedure and Replicated's snapshot-based backup and restore.
A Helm deployment is configured through a layered set of three files:
carto-values.yaml
CARTO
No
Default application settings for your release
carto-secrets.yaml
CARTO
No
Your license and private registry credentials
customizations.yaml
You
Yes
Your overrides and environment-specific settings
When you install or upgrade, Helm merges the three files, with the values in your customizations.yaml taking precedence. You only ever edit customizations.yaml; the two CARTO-provided files are replaced as-is when you move to a new release.
To apply a configuration change, edit customizations.yaml and re-deploy with helm upgrade (this is an apply changes operation, not a version change). See Apply configuration changes for the step-by-step, and the Advanced customizations reference for available overrides.
Where your configuration lives
Edited via
customizations.yaml (text editor)
Admin Console UI
Stored in
Files you keep
The cluster
Versioned by
You (e.g. Git)
Kots Version history
Apply a change
helm upgrade
Save config → Deploy
Built-in change log / diff
No — you provide it
Yes — Version history
The practical consequence: with Helm you are responsible for tracking and backing up your configuration files; with Kots, the Admin Console tracks deployed versions for you, and you back up and restore the configuration using the documented Kots backup procedure rather than maintaining files by hand.
Manage configuration as code
Whichever method you use, treat configuration as a tracked, reviewable artifact rather than ad-hoc live edits. The full set of recommendations — version control, secrets handling, review before apply, and the upgrade lifecycle — is covered in Manage configuration as code.
Next steps
Backups & Restore — what to back up and how to restore your configuration
Operations best practices — version control, secrets, and update cadence
Choosing a deployment method — Helm vs Kots vs Single VM
Last updated
Was this helpful?