Skip to content

CamundaRelease

CamundaRelease is a cluster-scoped description of what a platform runs. It holds the Camunda version, the connectors version, the Elasticsearch version, and the PostgreSQL version. It also holds an optional pinned image per Camunda process and the environment that a version needs. You create it, or another tool creates it for you.

A release separates what runs from the shape of a resource. The shape lives in a preset: CamundaClusterPreset, ElasticsearchClusterPreset, or DatabaseServerPreset. A platform team keeps a handful of presets, such as small and medium, and one release per rollout, such as camunda-8-9-4. To move a fleet to a new version set, the team edits one release. To move one resource, the owner changes one releaseRef.

A release creates nothing, and it reports no status. A resource that fits no release leaves releaseRef unset and sets version inline.

The smallest release names one version:

apiVersion: core.camunda.io/v1
kind: CamundaRelease
metadata:
  name: camunda-8-9-4
spec:
  version: "8.9.4"

graph LR
    CC[CamundaCluster] -.->|presetRef| CCP[CamundaClusterPreset]
    CC -.->|releaseRef| CR[CamundaRelease]
    CC -.->|platformConfigRef| PFC[CamundaPlatformConfig]
    EC[ElasticsearchCluster] -.->|releaseRef| CR
    DS[DatabaseServer] -.->|releaseRef| CR
Hold "Alt" / "Option" to enable pan & zoom

Merge position

A CamundaCluster, an ElasticsearchCluster, and a DatabaseServer each merge their configuration in this order: the preset, then the release, then their own spec. A later layer wins. For a cluster, a release extraEnv entry replaces a preset entry with the same name, and a cluster entry replaces both. extraEnvFrom concatenates in the same order. The merge rules of the preset apply unchanged.

A resource that sets spec.version next to a releaseRef runs its own version. Leave spec.version unset to follow the release.

Versions

Each version in the table below moves on its own. The connectors, Elasticsearch, and PostgreSQL versions do not change when spec.version changes. spec.databaseServer.version is a bare PostgreSQL major, not three segments.

Field What runs it Kind that reads it
spec.version The orchestration cluster processes CamundaCluster
spec.connectors.version The connectors bundle image CamundaCluster
spec.elasticsearch.version The Elasticsearch nodes ElasticsearchCluster
spec.databaseServer.version The PostgreSQL instances, as a major such as 17 DatabaseServer

A cluster that runs connectors needs the bundle version from the release or from its own spec.

One release names the whole set:

apiVersion: core.camunda.io/v1
kind: CamundaRelease
metadata:
  name: camunda-8-9-4
spec:
  version: "8.9.4"
  connectors:
    version: "8.9.7"
  elasticsearch:
    version: "9.2.8"
  databaseServer:
    version: "17"

When you edit a release, every resource that references it rolls to the new version. Each kind keeps its own rule about a version it refuses:

  • A cluster whose brokers run a higher version refuses the move and reports Ready: False with reason VersionDowngradeRefused. The CamundaCluster page states the rule and the annotation that sanctions a downgrade.
  • A server whose data directory runs another PostgreSQL major refuses the change and reports Ready: False with reason VersionChangeRefused. It keeps the major it has. The DatabaseServer page states the rule.
  • Camunda 8.9 needs Elasticsearch 8.19 or later on major 8, or 9.2 or later on major 9. An ElasticsearchCluster on an earlier version reports Ready: False with reason InvalidReference.

Pinned images

spec.images accepts two entries. camunda is the image of every orchestration cluster process, because they all run one image. connectors is the image of the connectors runtime. Each value is a complete reference, tag or digest included, and the operator pulls it as it is:

apiVersion: core.camunda.io/v1
kind: CamundaRelease
metadata:
  name: camunda-8-9-4-cve-2026-0001
spec:
  version: "8.9.4"
  images:
    camunda: "mirror.example.com/camunda/camunda@sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"

A pinned image changes only what is pulled. The version gates, the downgrade rule, and the computed environment still read spec.version, not the image. Pin an image of the same version that you name, for example a digest of it or a patched build of it.

A pin belongs to the version of the release. A cluster that runs another version does not pull it. When spec.version on the cluster wins over the release, or a restore sets the version, the cluster pulls the normal repository at that version. The connectors pin follows connectors.version the same way.

A release pins no Elasticsearch or PostgreSQL image. Those take their tag from elasticsearch.version and databaseServer.version.

To pin an image for a few clusters only, create a second release with the pin. Then point the releaseRef of those clusters at it.

To rename every image of an environment to a mirror, PostgreSQL included, use spec.images on the CamundaPlatformConfig instead. A release pins one exact reference for the clusters that use this release. A platform config renames the repository for every cluster and lets the version supply the tag.

Environment

A version bump often needs a configuration change with it. A release carries extraEnv and extraEnvFrom at the top level, per component (zeebe, gateway, operate, tasklist, admin), and under connectors, so the two ship together:

apiVersion: core.camunda.io/v1
kind: CamundaRelease
metadata:
  name: camunda-8-9-4
spec:
  version: "8.9.4"
  extraEnv:
    - name: CAMUNDA_SOME_NEW_FLAG
      value: "true"
  zeebe:
    extraEnv:
      - name: JAVA_OPTS
        value: "-Xmx8g"

Deletion

A release owns nothing, so a delete removes nothing else. A resource that still names the deleted release reports Ready: False with reason InvalidReference and keeps running as it is. Move every resource to another release before you delete one.

Status

A release reports no status. kubectl get camundarelease shows the Camunda version and the age. kubectl get camundarelease -o wide adds the connectors, Elasticsearch, and PostgreSQL versions.

Problems appear on the resource that references the release. A missing release gives Ready: False with reason InvalidReference.

Spec reference

Every field, with its type, whether it is required, and its default:

apiVersion: core.camunda.io/v1
kind: CamundaRelease
metadata:
  # Cluster-scoped: no namespace.
  name: camunda-8-9-4
spec:
  # string. Required. Camunda version as x.y.z. The referencing cluster requires 8.9.0 or later.
  version: "8.9.4"
  # object. Optional. The connectors runtime of this release.
  connectors:
    # string. Optional. Version of the connectors bundle as x.y.z. Required for clusters that enable connectors, unless each cluster sets its own.
    version: "8.9.7"
    # []EnvVar. Optional. Environment variables of the connectors runtime.
    extraEnv: []
    # []EnvFromSource. Optional. Environment sources of the connectors runtime.
    extraEnvFrom: []
  # object. Optional. The Elasticsearch of this release.
  elasticsearch:
    # string. Optional. Elasticsearch version as x.y.z. The referencing cluster requires 8.19 or later on major 8, and 9.2 or later on major 9.
    version: "9.2.8"
  # object. Optional. The PostgreSQL server of this release.
  databaseServer:
    # string. Optional. PostgreSQL major version as a bare number. The referencing server requires 14 or later.
    version: "17"
  # object. Optional. Complete image references, pulled as they are. A pin applies only while the version of the release is the effective one, and the version stays what the operator believes the process runs.
  images:
    # string. Optional. Image of every orchestration cluster process.
    camunda: "mirror.example.com/camunda/camunda@sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
    # string. Optional. Image of the connectors runtime.
    connectors: "mirror.example.com/camunda/connectors-bundle:8.9.7"
  # []EnvVar. Optional. Environment variables of every workload. An entry replaces a preset entry with the same name, and a cluster entry replaces it.
  extraEnv:
    - name: CAMUNDA_SOME_NEW_FLAG
      value: "true"
  # []EnvFromSource. Optional. Environment sources of every workload. They come after the preset sources and before the cluster sources.
  extraEnvFrom: []
  # object. Optional. Environment of the brokers. The same shape as zeebe applies to gateway, operate, tasklist, and admin.
  zeebe:
    # []EnvVar. Optional. Environment variables of this process. An entry here wins over a top-level entry with the same name.
    extraEnv: []
    # []EnvFromSource. Optional. Environment sources of this process.
    extraEnvFrom: []

Validation rules

  • spec.version is required and must be of the form x.y.z. The referencing cluster requires 8.9.0 or later on the merged spec.
  • spec.connectors.version and spec.elasticsearch.version must be of the form x.y.z.
  • spec.databaseServer.version must be a bare number.
  • An extraEnv entry sets value or valueFrom, never both.

A production-shaped example

apiVersion: core.camunda.io/v1
kind: CamundaRelease
metadata:
  name: camunda-8-9-4
spec:
  version: "8.9.4"
  connectors:
    version: "8.9.7"
  elasticsearch:
    version: "9.2.8"
  databaseServer:
    version: "17"
  extraEnv:
    - name: CAMUNDA_SOME_NEW_FLAG
      value: "true"
  zeebe:
    extraEnv:
      - name: JAVA_OPTS
        value: "-Xmx8g"