Skip to content

ElasticsearchClusterPreset

ElasticsearchClusterPreset is a cluster-scoped baseline configuration for ElasticsearchCluster resources. You create it, or another tool creates it for you.

A preset holds one Elasticsearch sizing as data: node count, resources, storage, scheduling, and more. Each ElasticsearchCluster that references it stays small and consistent. A platform team can publish a set of presets, for example small, standard, and large, and each team picks one. What runs on that shape, the Elasticsearch version, lives in a CamundaRelease, so a version roll never edits a preset.

A preset creates nothing and reports no status. An ElasticsearchCluster uses it through spec.presetRef.

The smallest preset sets a node count and a volume size:

apiVersion: core.camunda.io/v1
kind: ElasticsearchClusterPreset
metadata:
  name: standard
spec:
  cluster:
    replicas: 3
    storageSize: "64Gi"

graph LR
    ESC[ElasticsearchCluster] -.->|presetRef| ESCP[ElasticsearchClusterPreset]
    ESC -.->|releaseRef| CR[CamundaRelease]
Hold "Alt" / "Option" to enable pan & zoom

Merge rules

spec.cluster of the preset is the baseline. The CamundaRelease of releaseRef merges over it, and the cluster spec merges over both. A field set on the ElasticsearchCluster replaces the value of the layer below for that field. A field left unset on the cluster comes from the layer below.

Every object, list, and map is replaced as a whole, never merged field by field or key by key. This includes resources, serviceAccount, scheduling, monitoring, persistentVolumeClaimRetentionPolicy, secureSettings, extraEnv, extraEnvFrom, podLabels, and podAnnotations. A cluster that sets its own scheduling block drops every scheduling rule of the preset. A cluster that sets one pod label drops every pod label of the preset.

An empty list or map (for example extraEnv: [] or podLabels: {}) counts as unset, so it does not remove the value of the preset. To remove it, set the value that you want on the cluster. Or reference a preset without that field.

Fleet settings

A preset can set snapshotStorageRef, serviceAccount, secureSettings, and monitoring. So one preset can put every cluster that references it on one snapshot bucket. Each cluster writes its snapshots under its own path in that bucket. The preset can also give each cluster its <name>-es ServiceAccount and turn on metrics scraping.

apiVersion: core.camunda.io/v1
kind: ElasticsearchClusterPreset
metadata:
  name: standard
spec:
  cluster:
    replicas: 3
    storageSize: "64Gi"
    snapshotStorageRef: "my-backup-bucket"
    monitoring:
      serviceMonitor:
        enabled: true

snapshotStorageRef names an ObjectStorageConfig in the namespace of each cluster. Each namespace that uses the preset needs an ObjectStorageConfig of that name.

Changes

An edit of a preset reaches every ElasticsearchCluster that references it. A lower storageSize in the preset does not shrink a running cluster. That cluster keeps its current size and records a Warning event with reason StorageShrinkIgnored. A new cluster uses the new baseline.

A change of storageClassName reaches only the clusters that do not have an ECK resource yet. A suspended cluster takes it for its new volumes when it resumes. A cluster with an ECK resource keeps its class and records the Warning event StorageClassChangeIgnored. Volumes that a suspension or whenDeleted: Retain kept keep their class.

Deletion

Deleting a preset removes no cluster. Each ElasticsearchCluster that references it reports Ready False with reason InvalidReference.

Status

A preset has no status. It reports no conditions and no status.observedGeneration. A problem with a preset shows on the Ready condition of the ElasticsearchCluster that references it. Examples are a presetRef that names no preset, or a merge that lacks a required field.

Spec reference

spec.cluster has the same type as the spec of ElasticsearchCluster. The fields presetRef, releaseRef, secondaryStorageConfig, and suspend belong to one cluster and must stay unset in a preset. Validation rules has the rule for version. Every other field is inheritable.

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

apiVersion: core.camunda.io/v1
kind: ElasticsearchClusterPreset
metadata:
  name: standard
spec:
  # object (ElasticsearchCluster spec type). Required. The baseline that clusters inherit.
  cluster:
    # integer. Optional. Number of Elasticsearch nodes, at least 1.
    replicas: 3
    # object (corev1.ResourceRequirements). Optional. CPU and memory of each Elasticsearch node.
    resources:
      requests: { cpu: "1", memory: "2Gi" }
      limits: { memory: "2Gi" }
    # string (resource quantity). Optional. Size of the data volume of each node.
    storageSize: "64Gi"
    # string. Optional, default: the default StorageClass of the Kubernetes cluster. StorageClass of the data volumes.
    storageClassName: "ssd"
    # string. Optional. Name of an ObjectStorageConfig in the namespace of each cluster that holds the snapshot bucket. See ElasticsearchCluster.
    snapshotStorageRef: "my-backup-bucket"
    # list of objects. Optional. Secrets that ECK loads into the keystore of every node. See ElasticsearchCluster.
    secureSettings: []
    # list (corev1.EnvVar). Optional. Extra environment variables for every Elasticsearch node.
    extraEnv: []
    # list (corev1.EnvFromSource). Optional. Extra environment sources (ConfigMaps, Secrets) for every node.
    extraEnvFrom: []
    # map[string]string. Optional. Extra labels on the Elasticsearch pods.
    podLabels: {}
    # map[string]string. Optional. Extra annotations on the Elasticsearch pods.
    podAnnotations: {}
    # object. Optional. Scheduling constraints. A cluster that sets its own scheduling block replaces this one as a whole.
    scheduling:
      # object (corev1.NodeAffinity). Optional. Node affinity rules.
      nodeAffinity: {}
      # object (corev1.PodAffinity). Optional. Pod affinity rules.
      podAffinity: {}
      # list (corev1.Toleration). Optional. Tolerations of the pods.
      tolerations: []
    # object. Optional. ServiceAccount of the Elasticsearch pods. See ElasticsearchCluster.
    serviceAccount:
      # string. Optional, default: <cluster name>-es. Name of the ServiceAccount.
      name: ""
      # boolean. Optional, default: true. With false, you manage the ServiceAccount.
      create: true
      # map[string]string. Optional. Annotations for workload identity.
      annotations: {}
    # object. Optional. Prometheus scraping. A cluster that sets its own monitoring block replaces this one as a whole.
    monitoring:
      serviceMonitor:
        # boolean. Optional, default: false. Runs the elasticsearch_exporter and creates a ServiceMonitor.
        enabled: false
        # map[string]string. Optional. Extra labels on the ServiceMonitor.
        labels: {}
        # map[string]string. Optional. Extra annotations on the ServiceMonitor.
        annotations: {}
      exporter:
        # string. Optional, default: the exporter image that the operator pins. Exporter image.
        image: ""
        # object (corev1.ResourceRequirements). Optional. CPU and memory of the exporter container.
        resources: {}
    # object. Optional. What happens to the data volumes when the cluster is deleted.
    persistentVolumeClaimRetentionPolicy:
      # string (Retain | Delete). Optional, default: Delete. Delete removes the data volumes with the cluster. Retain keeps them.
      whenDeleted: Delete

Validation rules

  • spec.cluster must not set presetRef, releaseRef, secondaryStorageConfig, or suspend. An empty presetRef, an empty releaseRef, and suspend: false count as unset, so templated YAML that renders zero values still applies. An empty secondaryStorageConfig is rejected by the name pattern. Omit the field instead.
  • version is rejected in spec.cluster with version belongs to a CamundaRelease and must not be set in a preset. Move the version to a CamundaRelease, and point every cluster at it with releaseRef. An empty version is rejected by the three-segment pattern. Omit the field instead.
  • The no-shrink rule of ElasticsearchCluster for storageSize does not bind a preset. You can lower the baseline at any time.
  • Whether the merged configuration is complete is checked on the ElasticsearchCluster, not on the preset.
  • Every other rule of the ElasticsearchCluster schema applies to spec.cluster: replicas at least 1, and valid resource names.

A production-shaped example

apiVersion: core.camunda.io/v1
kind: ElasticsearchClusterPreset
metadata:
  name: large
spec:
  cluster:
    replicas: 5
    resources:
      requests: { cpu: "4", memory: "8Gi" }
      limits: { memory: "8Gi" }
    storageSize: "256Gi"
    storageClassName: "ssd"
    snapshotStorageRef: "my-backup-bucket"
    scheduling:
      tolerations:
        - key: dedicated
          operator: Equal
          value: elasticsearch
          effect: NoSchedule
    monitoring:
      serviceMonitor:
        enabled: true
        labels:
          release: prometheus
    persistentVolumeClaimRetentionPolicy:
      whenDeleted: Retain