Skip to content

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.

  • Universal dependency system: dependencies.<name> replaces helm-dependencies. Dependencies can run as plain workloads (standalone mode) or be provided by an operator (operator mode).
  • 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 env values into secretKeyRef, and externalSecret is supported.
  • Docs generated from the schema: the common documentation can no longer drift away from the code.
  • 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 support tpl now fail.
  • An enabled top-level redis, valkey, mariadb, mongodb, clickhouse, memcached, solr or cnpg key now fails rendering.
  • A top-level volumeClaimTemplates now 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 container image and name, and container type.
  • Documentation URLs changed.
  • Settings move to dependencies.<name>, and credentials are read from .Values.dependencies.<name>.depconfig.creds. .Values.redis.creds and similar no longer exist.
  • Dependency images move from dependencies.<name>.image to root keys: clickhouseImage, mariadbImage, memcachedImage, mongodbImage and valkeyImage.
  • The host of each dependency changes to the primary service, such as myapp-mariadb-main. Memcached has no creds, 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:// and jdbc: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.
  • cnpg moves to dependencies.postgresql (operator mode, one cluster per release).
  • The cnpg-main-urls secret and cnpg.main.creds are replaced by <release>-postgresqlcreds and depconfig.creds.
  • barmanMode, recovery.backupName, recovery.method: backup, operator.verify and the timescaledb type are removed.
  • Backup metrics are renamed from cnpg_collector_* to barman_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.
  • Credentials in the notes now show as HIDDEN. Set notes.showCredentials: true to show them.
  • whoami now defaults to port 8080 instead of 80, as it runs as non-root.
  • Our netshoot image does not include ctop, websocat or zsh.
  • runAsNonRoot is no longer forced to false on GID 0. Explicit configuration is honored.
  • VolSync mover pods now get seccompProfile: RuntimeDefault.
  • Images for whoami, netshoot, gluetun and tailscale now come from containerforge instead of tccr.

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. Back up everything: persistent volumes, and databases. Test that the backup can be restored.
  2. Dump MariaDB, MongoDB and ClickHouse databases, as their data is not migrated.
  3. Pin your PostgreSQL version with dependencies.postgresql.operator.pgVersion if you do not want to move to 18.
  4. Install the Barman Cloud plugin if you use backups or object store recovery.
  5. Delete or rename existing Backup objects created from manualBackups. Their spec is immutable, so the upgrade fails otherwise.
  6. Remove old keys from your values, such as barmanMode, and replace recovery.method: backup with object_store.
  7. Keep destinationPath, serverName and revision unchanged, so existing backups stay usable.

A chart moves by putting its settings under dependencies.<name>.

PostgreSQL, before:

cnpg:
main:
enabled: true
user: myapp
database: myapp

PostgreSQL, after:

dependencies:
postgresql:
enabled: true
operator:
pgVersion: 17 # pin, if you do not want to move to 18

Valkey, before:

valkey:
enabled: true

Valkey, after:

dependencies:
valkey:
enabled: true

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

  • PostGIS clusters: run SELECT postgis_extensions_upgrade();.
  • pgvecto.rs clusters with vectors indexes: run ALTER EXTENSION vectors UPDATE; and SELECT pgvectors_upgrade();, then restart and reindex.
  • Custom localeCollate or localeCtype: reindex and run ALTER DATABASE ... REFRESH COLLATION VERSION. Clusters on the default C are not affected.
  • MariaDB, MongoDB and ClickHouse: restore your dumps.
  • Update applications, dashboards and alerts that use the old secrets, URLs or cnpg_collector_* metrics.
  • Add a universal dependency system replacing helm-dependencies, with mode and operator keys.
  • Allow objects of a dependency to be the primary objects of the release.
  • Support the codeserver, gluetun, netshoot and tailscale addons 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.
  • Add dependencies.postgresql, in standalone or operator mode.
  • Add PostgreSQL 17 and 18 support to CNPG and default to 18.
  • Move PostgreSQL and PostGIS to -standard-trixie images, and update PostGIS and pgvecto.rs.
  • Add CNPG Barman Cloud plugin support and remove in-tree Barman.
  • Replace cnpg-main-urls and cnpg.main.creds with <release>-postgresqlcreds and depconfig.creds.
  • Remove the timescaledb type and the no-op operator.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 ValkeyCluster in operator mode.
  • Fix valkey-wait blocking 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.
  • 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 listenerSet and route.<name>.listenerSet.
  • Add a route to the codeserver addon.
  • Correct chartContext.appUrl for routes on an HTTP listener, and for primary TCP and UDP routes.
  • 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.
  • 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-test test against the schema, and add a unittest coverage check up to 100%.
  • Add connection info for databases, routes, LoadBalancer and NodePort services.
  • Fix internal URL formatting.
  • Add notes.showCredentials and hide credentials by default.
  • Move credentials from plain env values to secretKeyRef.
  • Add externalSecret.
  • Stop forcing runAsNonRoot to false on GID 0.
  • Render the full moverSecurityContext for VolSync, with restricted Pod Security defaults.
  • Remove env-list support and unused containers.
  • Add a default emptyDir for crontab, and folder-based ConfigMap inclusions.
  • Add maxResponseBodySize and templated address for Traefik ForwardAuth middlewares.
  • Fix prometheusRules not rendering, and add annotations.
  • 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.
  • 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.

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