Common-2026 (32.0.0): A Breaking Rework of the Common Library
Common-2026 Released: Our Biggest Common Release Yet
Section titled “Common-2026 Released: Our Biggest Common Release Yet”We are happy to announce the release of common 32.0.0, better known as common-2026. Common is the shared Helm library behind every TrueCharts chart, and this is the largest rework it has ever had.
Highlights include a universal dependency system, PostgreSQL 18 with the CNPG Barman Cloud plugin,
our own images for Valkey, MariaDB, MongoDB, ClickHouse and Memcached, complete Gateway API support,
Cilium network policies, and a strict, closed JSON schema for values.yaml.
How Common-2026 Relates to the Stable and Incubator Charts
Section titled “How Common-2026 Relates to the Stable and Incubator Charts”Every chart in our stable and incubator trains depends on common, pinned to a specific version.
Releasing common-2026 therefore does not change any chart you have installed today.
Your charts keep using the common version they are currently pinned to.
Stable and incubator charts will be updated to common-2026 at a later date, chart by chart.
Charts that use Helm sub-chart dependencies for Valkey, MariaDB, MongoDB, ClickHouse or Memcached,
or the cnpg database, need real migration work before they can move.
Charts that do not use those can move more easily, but still have to pass the stricter schema.
What’s New
Section titled “What’s New”- Universal dependency system:
dependencies.<name>replaceshelm-dependencies. Dependencies can run as plain workloads (standalonemode) or be provided by an operator (operatormode). - PostgreSQL 18 and CNPG Barman Cloud plugin: PostgreSQL 17 and 18 are supported, with 18 as the new default. Backups and recovery now use the Barman Cloud plugin.
- Our own database images: Valkey, MariaDB, MongoDB, ClickHouse and Memcached now run on our own images, as UID/GID 568 with a read-only root filesystem and no added privileges.
- Complete Gateway API support: routes are now at feature parity with ingress, including gateway selection,
per-route TLS with cert-manager, Traefik and Envoy Gateway integrations, and
listenerSet. - More network policies: Cilium network policies, workload-specific selector labels, and policies that target multiple workloads or regular expressions.
- Closed JSON schema: building on common 3.4.0, unknown keys are now rejected everywhere.
- Better notes: connection info for databases, routes, LoadBalancer and NodePort services, with credentials hidden by default.
- Security improvements: credentials move out of plain
envvalues intosecretKeyRef, andexternalSecretis supported. - Docs generated from the schema: the common documentation can no longer drift away from the code.
⚠️ (Potentially) Breaking Changes
Section titled “⚠️ (Potentially) Breaking Changes”Values and schema
Section titled “Values and schema”- The schema is now closed: unknown and removed keys fail rendering instead of being silently ignored.
- Strings such as
"false"on boolean keys that do not supporttplnow fail. - An enabled top-level
redis,valkey,mariadb,mongodb,clickhouse,memcached,solrorcnpgkey now fails rendering. - A top-level
volumeClaimTemplatesnow fails rendering. It never created a volume. - Env-list support is removed.
- Keys no template read are removed, such as the legacy probe keys,
ingress.autoLink,global.ignoreIsStopped,securityContext.container.fsGroup, init containerimageandname, and containertype. - Documentation URLs changed.
Dependencies
Section titled “Dependencies”- Settings move to
dependencies.<name>, and credentials are read from.Values.dependencies.<name>.depconfig.creds..Values.redis.credsand similar no longer exist. - Dependency images move from
dependencies.<name>.imageto root keys:clickhouseImage,mariadbImage,memcachedImage,mongodbImageandvalkeyImage. - The host of each dependency changes to the primary service, such as
myapp-mariadb-main. Memcached has nocreds, so use the service name<fullname>-memcached-main. - Predefined dependencies no longer inherit root, privileges or capabilities from the chart.
- MariaDB URL schemes are corrected to
mysql://andjdbc:mariadb://, and MariaDB passwords under 4 characters fail rendering. - The Valkey URL now contains the user:
redis://default:PASSWORD@host:6379/0. - Upgrades across major versions of MariaDB and MongoDB are not automatic.
- The MongoDB image is licensed under the SSPL, unlike our other images.
PostgreSQL (CNPG)
Section titled “PostgreSQL (CNPG)”cnpgmoves todependencies.postgresql(operatormode, one cluster per release).- The
cnpg-main-urlssecret andcnpg.main.credsare replaced by<release>-postgresqlcredsanddepconfig.creds. barmanMode,recovery.backupName,recovery.method: backup,operator.verifyand thetimescaledbtype are removed.- Backup metrics are renamed from
cnpg_collector_*tobarman_cloud_cloudnative_pg_io_*. - PostgreSQL images move from Debian 11 and 12 to Debian 13.
- Expect a rolling restart, and a brief outage on clusters with a single instance.
Other changes
Section titled “Other changes”- Credentials in the notes now show as
HIDDEN. Setnotes.showCredentials: trueto show them. whoaminow defaults to port8080instead of80, as it runs as non-root.- Our
netshootimage does not includectop,websocatorzsh. runAsNonRootis no longer forced to false on GID 0. Explicit configuration is honored.- VolSync mover pods now get
seccompProfile: RuntimeDefault. - Images for
whoami,netshoot,gluetunandtailscalenow come from containerforge instead oftccr.
Migration Guide
Section titled “Migration Guide”This guide is for chart maintainers and users with custom values who move a chart to common-2026. If you use a stable or incubator chart, wait for the chart’s own major release, and follow its release notes together with this guide.
1. Before upgrading
Section titled “1. Before upgrading”- Back up everything: persistent volumes, and databases. Test that the backup can be restored.
- Dump MariaDB, MongoDB and ClickHouse databases, as their data is not migrated.
- Pin your PostgreSQL version with
dependencies.postgresql.operator.pgVersionif you do not want to move to 18. - Install the Barman Cloud plugin if you use backups or object store recovery.
- Delete or rename existing
Backupobjects created frommanualBackups. Their spec is immutable, so the upgrade fails otherwise. - Remove old keys from your values, such as
barmanMode, and replacerecovery.method: backupwithobject_store. - Keep
destinationPath,serverNameandrevisionunchanged, so existing backups stay usable.
2. Rewrite your values
Section titled “2. Rewrite your values”A chart moves by putting its settings under dependencies.<name>.
PostgreSQL, before:
cnpg: main: enabled: true user: myapp database: myappPostgreSQL, after:
dependencies: postgresql: enabled: true operator: pgVersion: 17 # pin, if you do not want to move to 18Valkey, before:
valkey: enabled: trueValkey, after:
dependencies: valkey: enabled: trueThe same applies to mariadb, mongodb, clickhouse and memcached.
Read credentials from .Values.dependencies.<name>.depconfig.creds, and use the new service host names.
Steps for each dependency are in the dependencies documentation.
3. After upgrading
Section titled “3. After upgrading”- PostGIS clusters: run
SELECT postgis_extensions_upgrade();. - pgvecto.rs clusters with
vectorsindexes: runALTER EXTENSION vectors UPDATE;andSELECT pgvectors_upgrade();, then restart and reindex. - Custom
localeCollateorlocaleCtype: reindex and runALTER DATABASE ... REFRESH COLLATION VERSION. Clusters on the defaultCare not affected. - MariaDB, MongoDB and ClickHouse: restore your dumps.
- Update applications, dashboards and alerts that use the old secrets, URLs or
cnpg_collector_*metrics.
Changelog
Section titled “Changelog”Dependencies: general
Section titled “Dependencies: general”- Add a universal dependency system replacing
helm-dependencies, withmodeandoperatorkeys. - Allow objects of a dependency to be the primary objects of the release.
- Support the
codeserver,gluetun,netshootandtailscaleaddons in dependencies. - Reject keys a dependency cannot support, and fail on enabled legacy top-level dependency keys.
- Run predefined dependencies as UID/GID 568 with a read-only root filesystem and no added privileges.
- Move dependency images to root keys.
- Remove the unused Solr dependency code.
Dependencies: PostgreSQL (CNPG)
Section titled “Dependencies: PostgreSQL (CNPG)”- Add
dependencies.postgresql, instandaloneoroperatormode. - Add PostgreSQL 17 and 18 support to CNPG and default to 18.
- Move PostgreSQL and PostGIS to
-standard-trixieimages, and update PostGIS and pgvecto.rs. - Add CNPG Barman Cloud plugin support and remove in-tree Barman.
- Replace
cnpg-main-urlsandcnpg.main.credswith<release>-postgresqlcredsanddepconfig.creds. - Remove the
timescaledbtype and the no-opoperator.verify.
Dependencies: Valkey, MariaDB, MongoDB, ClickHouse and Memcached
Section titled “Dependencies: Valkey, MariaDB, MongoDB, ClickHouse and Memcached”- Run Valkey on our image, and spawn a
ValkeyClusterinoperatormode. - Fix
valkey-waitblocking the Valkey dependency itself, or waiting forever on a password-protected Valkey. - Move MariaDB, MongoDB, ClickHouse and Memcached to
dependencies.<name>on our images. - Passwords of MariaDB, MongoDB and ClickHouse are applied on every start, so they can be changed later.
- Correct MariaDB URL schemes and fail on MariaDB passwords under 4 characters.
Gateway API and routes
Section titled “Gateway API and routes”- Rework Gateway API route integration and complete gateway and route support.
- Bring routes to feature parity with ingress, including per-route TLS with cert-manager and Traefik and Envoy Gateway integrations.
- Add
listenerSetandroute.<name>.listenerSet. - Add a route to the codeserver addon.
- Correct
chartContext.appUrlfor routes on an HTTP listener, and for primary TCP and UDP routes.
Network policies
Section titled “Network policies”- Add Cilium network policies with
networkpolicy.<name>.type: cilium. - Add workload-specific
extraSelectorLabels. - Allow NetworkPolicies to target multiple workloads, or workloads matched by regular expressions.
Values schema and validation
Section titled “Values schema and validation”- Add the JSON schema with descriptions ported from the docs, and close it with
additionalProperties: false. - Move 130 type and enum checks from the templates into the schema.
- Remove keys that no template reads.
- Add one template for all errors about removed and deprecated keys.
- Validate every
common-testtest against the schema, and add a unittest coverage check up to 100%.
Notes (NOTES.txt)
Section titled “Notes (NOTES.txt)”- Add connection info for databases, routes, LoadBalancer and NodePort services.
- Fix internal URL formatting.
- Add
notes.showCredentialsand hide credentials by default.
Security
Section titled “Security”- Move credentials from plain
envvalues tosecretKeyRef. - Add
externalSecret. - Stop forcing
runAsNonRootto false on GID 0. - Render the full
moverSecurityContextfor VolSync, with restricted Pod Security defaults.
Other features and fixes
Section titled “Other features and fixes”- Remove env-list support and unused containers.
- Add a default emptyDir for crontab, and folder-based ConfigMap inclusions.
- Add
maxResponseBodySizeand templated address for Traefik ForwardAuth middlewares. - Fix
prometheusRulesnot rendering, and addannotations. - Add VolSync mover resources and fix a VolSync render error on access modes.
- Fix two bugs in the RWO rolling update checks, and extend them to
ReadWriteOncePod. - Update all images to their newest versions.
Tooling, CI and docs
Section titled “Tooling, CI and docs”- Rewrite the docs generator. Pages are now defined by
x-docs-*schema metadata, and generated docs are checked in CI. - Add scripts to test the schema against known-good charts, and to estimate schema coverage.
- Remove the old Renovate config.
- Fix install tests getting stuck, and a random CI failure caused by a duplicate ingress host.
Thank You
Section titled “Thank You”Common-2026 is the result of a large amount of work. Thank you to all contributors who help build and maintain TrueCharts, and to all users for the feedback and support that drive the project forward.
For more information or to get involved, visit: https://trueforge.org