Skip to content
Druid icon
v1.4.0App: v38.0.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Apache Druid

Apache Druid is a high-performance, real-time analytics database designed for fast slice-and-dice analytics on large datasets. It is commonly used for user-facing analytic applications, BI dashboards, and real-time data exploration.

Features

  • Modular Druid architecture - coordinator, broker, and router by default, with optional overlord, historical, and middlemanager
  • Web console - router component serves the Druid web console
  • PostgreSQL subchart - bundled metadata store with option for external database
  • Bundled ZooKeeper - native ZooKeeper StatefulSet with option for external cluster
  • Deep storage - local or S3-compatible (MinIO, AWS S3)
  • Persistent volumes - segment cache (historical) and task storage (middlemanager)
  • Health probes - startup and liveness on /status/health, readiness on /status/selfDiscovered
  • Ingress support - configurable with ingressClassName (traefik, nginx, etc.)
  • Gateway API support - optional HTTPRoute for the router/web console
  • Dual-stack Services - optional ipFamilyPolicy / ipFamilies on every Druid Service
  • External Secrets Operator - optional ExternalSecret projection for metadata and S3 credentials
  • NetworkPolicy - optional ingress and egress controls for compatible CNIs
  • Per-component scaling - independent replica counts and JVM tuning

Security Scan

Security scan: druid

Framework Score
MITRE + NSA + SOC2 83.000000%

Security posture: acceptable.

The default scan keeps Druid writable paths and resource limits configurable instead of forcing a one-size-fits-all production profile. For hardened deployments, enable NetworkPolicy and set explicit CPU and memory requests and limits for every Druid component.

Install

Helm repository

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install druid helmforge/druid -f values.yaml

OCI registry

helm install druid oci://ghcr.io/helmforgedev/helm/druid --version <version> -f values.yaml

Architecture

flowchart LR
  client[Users and API clients] --> router[Router]
  router --> broker[Broker]
  broker --> historical[Historical]
  coordinator[Coordinator] --> historical
  overlord[Overlord] --> middle[MiddleManager]
  middle --> deep[(S3 deep storage)]
  historical --> deep
  roles[Druid roles] --> metadata[(PostgreSQL metadata)]
  roles --> zk[(ZooKeeper)]
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-----|---------|-------------| | global | {} | Helm ecosystem compatibility values | | commonAnnotations | {} | Annotations added to chart-owned resources; resource annotations take precedence | | image.repository | apache/druid | Druid container image | | image.tag | "38.0.0" | Image tag | | coordinator.enabled | true | Enable coordinator | | coordinator.replicaCount | 1 | Coordinator replicas | | coordinator.port | 8081 | Coordinator port | | coordinator.javaOpts | -Xms128m -Xmx256m | Coordinator JVM options | | overlord.enabled | false | Enable overlord for ingestion management | | overlord.port | 8090 | Overlord port | | broker.enabled | true | Enable broker | | broker.port | 8082 | Broker port | | broker.javaOpts | -Xms256m -Xmx512m | Broker JVM options | | router.enabled | true | Enable router (web console) | | router.port | 8888 | Router port | | historical.enabled | false | Enable historical segment serving | | historical.port | 8083 | Historical port | | historical.persistence.size | 10Gi | Segment cache volume size | | historical.persistence.retentionPolicy.whenDeleted | "" | PVC retention after StatefulSet deletion; Retain, Delete, or Kubernetes default | | historical.persistence.retentionPolicy.whenScaled | "" | PVC retention after scale-down; Retain, Delete, or Kubernetes default | | middleManager.enabled | false | Enable middle manager ingestion workers | | middleManager.port | 8091 | MiddleManager port | | middleManager.workerCapacity | 2 | Tasks per middle manager | | middleManager.persistence.size | 10Gi | Task storage volume size | | middleManager.persistence.retentionPolicy.whenDeleted | "" | PVC retention after StatefulSet deletion; Retain, Delete, or Kubernetes default | | middleManager.persistence.retentionPolicy.whenScaled | "" | PVC retention after scale-down; Retain, Delete, or Kubernetes default | | metadata.mode | subchart | Metadata mode: subchart or external | | zookeeperConfig.mode | subchart | ZooKeeper mode: subchart or external | | deepStorage.type | local | Deep storage: local or s3 | | service.type | ClusterIP | Router service type | | service.port | 80 | Router service port | | service.ipFamilyPolicy | omitted | Optional Kubernetes Service IP family policy | | service.ipFamilies | omitted | Optional ordered Service IP families | | serviceAccount.automountServiceAccountToken | false | Mount Kubernetes API credentials into workload Pods | | ingress.enabled | false | Enable ingress | | ingress.ingressClassName | traefik | Ingress class | | gatewayAPI.enabled | false | Enable Gateway API HTTPRoute for the router | | externalSecrets.enabled | false | Render ExternalSecret resources for secret material | | networkPolicy.enabled | false | Render NetworkPolicy resources | | podSecurityContext.fsGroup | 1000 | Shared filesystem group for Druid volumes | | securityContext.runAsNonRoot | true | Run Druid containers as a non-root user | | postgresql.enabled | true | Enable PostgreSQL subchart | | zookeeper.enabled | true | Enable bundled ZooKeeper | | zookeeper.persistence.retentionPolicy.whenDeleted | "" | PVC retention after StatefulSet deletion; Retain, Delete, or Kubernetes default | | zookeeper.persistence.retentionPolicy.whenScaled | "" | PVC retention after scale-down; Retain, Delete, or Kubernetes default |

PVC retention policies require Kubernetes 1.27 or later. On Kubernetes 1.26, enable the StatefulSetAutoDeletePVC feature gate on both the API server and controller manager.

Druid 38.0.0 upgrade notes

This chart tracks Apache Druid 38.0.0. Before upgrading persistent clusters, review the upstream release notes and upgrade notes.

Important upstream changes include:

  • Java 17 support was removed; the official image supplies a supported runtime.
  • The ZooKeeper-based remote task runner was removed. Existing overrides must use httpRemote or omit druid.indexer.runner.type to use its default.
  • ZooKeeper-based segment announcement and discovery were removed. Existing overrides must use druid.serverview.type=http or omit the property.
  • Druid 38 is the final release able to read legacy v0.4-v0.7 ZSTD frames.
  • Kafka streaming shard specs using the new dim_value_set type prevent a downgrade until those segments are compacted or the feature is removed.

External Metadata Storage

postgresql:
  enabled: false

metadata:
  mode: external
  external:
    type: postgresql
    host: postgres.example.com
    port: 5432
    name: druid
    username: druid
    password: my-password

External ZooKeeper

zookeeper:
  enabled: false

zookeeperConfig:
  mode: external
  external:
    hosts: "zk1.example.com:2181,zk2.example.com:2181,zk3.example.com:2181"

S3 Deep Storage

deepStorage:
  type: s3
  s3:
    bucket: my-druid-bucket
    baseKey: druid/segments
    region: us-east-1
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

For MinIO or S3-compatible storage:

deepStorage:
  type: s3
  s3:
    bucket: druid
    baseKey: segments
    region: us-east-1
    endpointUrl: http://minio.minio.svc:9000
    accessKey: minioadmin
    secretKey: minioadmin

Ingress

ingress:
  enabled: true
  ingressClassName: traefik  # or nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: druid.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: druid-tls
      hosts:
        - druid.example.com

Gateway API

Gateway API support is opt-in and renders an HTTPRoute to the router Service. The chart does not create a Gateway; reference a shared Gateway managed by your platform team.

gatewayAPI:
  enabled: true
  parentRefs:
    - name: shared-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - druid.example.com
  paths:
    - type: PathPrefix
      value: /

Dual-stack Services

Dual-stack fields are omitted by default so Kubernetes inherits the cluster defaults. Set service.ipFamilyPolicy when running in IPv6 or dual-stack clusters:

service:
  ipFamilyPolicy: PreferDualStack

External Secrets Operator

ExternalSecret rendering is opt-in. Set the chart's existingSecret field to the same Secret that External Secrets Operator will create, preventing drift between chart-managed and externally managed credentials.

metadata:
  mode: external
  external:
    existingSecret: druid-metadata

deepStorage:
  type: s3
  s3:
    bucket: druid-segments
    existingSecret: druid-s3

externalSecrets:
  enabled: true
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  metadata:
    enabled: true
    data:
      - secretKey: password
        remoteRef:
          key: druid/metadata
          property: password
  deepStorage:
    enabled: true
    data:
      - secretKey: access-key
        remoteRef:
          key: druid/s3
          property: access-key
      - secretKey: secret-key
        remoteRef:
          key: druid/s3
          property: secret-key

Security context

Druid workload containers run as UID/GID 1000 by default with privilege escalation disabled, all Linux capabilities dropped, and the runtime default seccomp profile. The prepare-dirs init container runs as root only to create and chown writable Druid directories.

NetworkPolicy

NetworkPolicy is opt-in because enforcement depends on the cluster CNI. When enabled, ingress defaults to same-namespace traffic on Druid component ports. Egress rules are optional and can allow DNS, same-namespace dependencies, HTTP, HTTPS, and extra peers:

networkPolicy:
  enabled: true
  ingress:
    allowSameNamespace: true
  egress:
    enabled: true
    allowDNS: true
    allowSameNamespace: true
    allowHTTPS: true

Extra Runtime Properties

Each component supports extraProperties for additional Druid runtime configuration:

broker:
  extraProperties: |
    druid.broker.http.numConnections=20
    druid.server.http.numThreads=40

historical:
  extraProperties: |
    druid.segmentCache.locations=[{"path":"/opt/druid/var/druid/segment-cache","maxSize":10737418240}]

Configuration validation

The chart fails before resource creation when bundled and external dependency modes conflict, when external PostgreSQL or ZooKeeper endpoints are incomplete, when S3 mode lacks a bucket or credentials, or when Ingress and Gateway API routes do not have an enabled Router and required routing references.

Run the same render checks locally before an upgrade:

helm lint --strict charts/druid
helm template druid charts/druid -f values.yaml >/dev/null

Troubleshooting

List the role Pods and inspect rollout state:

kubectl get pods,svc -l app.kubernetes.io/instance=druid
kubectl get events --sort-by=.lastTimestamp

Inspect the Router and a selected Druid role when discovery or queries fail:

kubectl logs deployment/druid-druid-router --tail=200
kubectl logs statefulset/druid-druid-coordinator --tail=200

For dependency failures, verify that the configured PostgreSQL and ZooKeeper Services are reachable and that the referenced Secret contains the documented keys. For S3 failures, verify bucket access and the endpoint TLS trust chain.

Examples

Architecture Guides

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  client[Users and API clients] --> route[Ingress or HTTPRoute]
  route --> router[Router]
  router --> broker[Broker]
  broker --> historical[Historical]
  coordinator[Coordinator] --> historical
  overlord[Overlord] --> middle[MiddleManager]
  middle --> deep[(S3 deep storage)]
  historical --> deep
  roles[Druid roles] --> metadata[(PostgreSQL metadata)]
  roles --> zk[(ZooKeeper)]
  eso[External Secrets Operator] -. credentials .-> roles
Official Contractvalues.schema.json

Druid Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

168 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Common Annotations(1)

ParameterTypeDefaultDescription
commonAnnotationsobject-Annotations added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Druid container image repository
image.tagstring-Druid image tag. Defaults to appVersion.
image.pullPolicystring-Image pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Druid(2)

ParameterTypeDefaultDescription
druid.extraCommonPropertiesstring-Extra common runtime properties applied to all components
druid.extraEnvarray-Extra environment variables for all components

Metadata(9)

ParameterTypeDefaultDescription
metadata.modestring-Metadata storage mode
Allowed:subchartexternal
metadata.external.typestring-External metadata storage type
Allowed:postgresqlmysql
metadata.external.hoststring-External database host
metadata.external.portinteger-External database port
metadata.external.namestring-External database name
metadata.external.usernamestring-External database username
metadata.external.passwordstring-External database password
metadata.external.existingSecretstring-Existing secret with external database password
metadata.external.existingSecretPasswordKeystring-Key in existingSecret for password

Zookeeper Config(2)

ParameterTypeDefaultDescription
zookeeperConfig.modestring-ZooKeeper mode
Allowed:subchartexternal
zookeeperConfig.external.hostsstring-External ZooKeeper connection string

Deep Storage(10)

ParameterTypeDefaultDescription
deepStorage.typestring-Deep storage type
Allowed:locals3
deepStorage.s3.bucketstring-S3 bucket name
deepStorage.s3.baseKeystring-S3 base key (prefix)
deepStorage.s3.regionstring-S3 region
deepStorage.s3.endpointUrlstring-S3 endpoint URL (for MinIO or compatible)
deepStorage.s3.accessKeystring-S3 access key
deepStorage.s3.secretKeystring-S3 secret key
deepStorage.s3.existingSecretstring-Existing secret with S3 credentials
deepStorage.s3.existingSecretAccessKeyKeystring-Key in existingSecret for access key
deepStorage.s3.existingSecretSecretKeyKeystring-Key in existingSecret for secret key

Coordinator(8)

ParameterTypeDefaultDescription
coordinator.enabledboolean-Enable coordinator
coordinator.replicaCountinteger-Number of coordinator replicas
coordinator.portinteger-Coordinator port
coordinator.javaOptsstring-JVM options
coordinator.extraPropertiesstring-Extra runtime properties
coordinator.resourcesobject-Resource requests and limits
coordinator.podLabelsobject-Pod labels
coordinator.podAnnotationsobject-Pod annotations

Overlord(8)

ParameterTypeDefaultDescription
overlord.enabledboolean-Enable overlord
overlord.replicaCountinteger-Number of overlord replicas
overlord.portinteger-Overlord port
overlord.javaOptsstring-JVM options
overlord.extraPropertiesstring-Extra runtime properties
overlord.resourcesobject-Resource requests and limits
overlord.podLabelsobject-Pod labels
overlord.podAnnotationsobject-Pod annotations

Broker(8)

ParameterTypeDefaultDescription
broker.enabledboolean-Enable broker
broker.replicaCountinteger-Number of broker replicas
broker.portinteger-Broker port
broker.javaOptsstring-JVM options
broker.extraPropertiesstring-Extra runtime properties
broker.resourcesobject-Resource requests and limits
broker.podLabelsobject-Pod labels
broker.podAnnotationsobject-Pod annotations

Router(8)

ParameterTypeDefaultDescription
router.enabledboolean-Enable router
router.replicaCountinteger-Number of router replicas
router.portinteger-Router port
router.javaOptsstring-JVM options
router.extraPropertiesstring-Extra runtime properties
router.resourcesobject-Resource requests and limits
router.podLabelsobject-Pod labels
router.podAnnotationsobject-Pod annotations

Historical(13)

ParameterTypeDefaultDescription
historical.enabledboolean-Enable historical
historical.replicaCountinteger-Number of historical replicas
historical.portinteger-Historical port
historical.javaOptsstring-JVM options
historical.extraPropertiesstring-Extra runtime properties
historical.persistence.enabledboolean-Enable persistence
historical.persistence.sizestring-PVC size
historical.persistence.storageClassstring-Storage class
historical.persistence.accessModesarray-Access modes
historical.persistence.retentionPolicyany-Chart configuration parameter
historical.resourcesobject-Resource requests and limits
historical.podLabelsobject-Pod labels
historical.podAnnotationsobject-Pod annotations

Middle Manager(14)

ParameterTypeDefaultDescription
middleManager.enabledboolean-Enable middle manager
middleManager.replicaCountinteger-Number of middle manager replicas
middleManager.portinteger-MiddleManager port
middleManager.javaOptsstring-JVM options
middleManager.workerCapacityinteger-Number of task workers per middle manager
middleManager.extraPropertiesstring-Extra runtime properties
middleManager.persistence.enabledboolean-Enable persistence
middleManager.persistence.sizestring-PVC size
middleManager.persistence.storageClassstring-Storage class
middleManager.persistence.accessModesarray-Access modes
middleManager.persistence.retentionPolicyany-Chart configuration parameter
middleManager.resourcesobject-Resource requests and limits
middleManager.podLabelsobject-Pod labels
middleManager.podAnnotationsobject-Pod annotations

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestring-Service type
service.portinteger-Service port
service.annotationsobject-Service annotations
service.ipFamilyPolicystringnull-Service IP family policy. One of SingleStack, PreferDualStack, RequireDualStack. Omit for cluster default.
Allowed:SingleStackPreferDualStackRequireDualStacknull
service.ipFamiliesarray-Ordered list of IP families for the Service. Each entry is IPv4 or IPv6. Omit for cluster default.

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Enable ingress
ingress.ingressClassNamestring-Ingress class name
ingress.annotationsobject-Ingress annotations
ingress.hostsarray-Ingress hosts
ingress.tlsarray-Ingress TLS

Gateway API(5)

ParameterTypeDefaultDescription
gatewayAPI.enabledboolean-Enable Gateway API HTTPRoute
gatewayAPI.parentRefsarray-Parent Gateway references
gatewayAPI.hostnamesarray-HTTPRoute hostnames
gatewayAPI.pathsarray-HTTPRoute path matches
gatewayAPI.annotationsobject-HTTPRoute annotations

External Secrets(12)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Render ExternalSecret resources
externalSecrets.apiVersionstring-ExternalSecret API version
externalSecrets.refreshIntervalstring-ExternalSecret refresh interval
externalSecrets.secretStoreRef.namestring-SecretStore or ClusterSecretStore name
externalSecrets.secretStoreRef.kindstring-Secret store kind
Allowed:SecretStoreClusterSecretStore
externalSecrets.target.creationPolicystring-ExternalSecret target creation policy
Allowed:OwnerOrphanMergeNone
externalSecrets.metadata.enabledboolean-Manage metadata database password Secret
externalSecrets.metadata.dataarray-ExternalSecret data entries
externalSecrets.metadata.dataFromarray-ExternalSecret dataFrom entries
externalSecrets.deepStorage.enabledboolean-Manage S3 credential Secret
externalSecrets.deepStorage.dataarray-ExternalSecret data entries
externalSecrets.deepStorage.dataFromarray-ExternalSecret dataFrom entries

Network Policy(10)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Enable NetworkPolicy resources
networkPolicy.ingress.allowSameNamespaceboolean-Allow same-namespace ingress
networkPolicy.ingress.extraFromarray-Additional ingress peers
networkPolicy.egress.enabledboolean-Enable egress policy rules
networkPolicy.egress.allowDNSboolean-Allow DNS egress to kube-system
networkPolicy.egress.allowSameNamespaceboolean-Allow same-namespace egress
networkPolicy.egress.allowHTTPSboolean-Allow HTTPS egress
networkPolicy.egress.allowHTTPboolean-Allow HTTP egress
networkPolicy.egress.extraToarray-Additional egress peers
networkPolicy.egress.extraEgressarray-Additional complete egress rules appended to the NetworkPolicy

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Create a ServiceAccount
serviceAccount.namestring-ServiceAccount name
serviceAccount.annotationsobject-ServiceAccount annotations
serviceAccount.automountServiceAccountTokenboolean-Mount Kubernetes API credentials into Druid and ZooKeeper Pods

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContextobject-Pod-level security context

Container Security(1)

ParameterTypeDefaultDescription
securityContextobject-Container-level security context

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Termination grace period in seconds

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Extra volumes

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Extra volume mounts

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra Kubernetes manifests to deploy

Postgresql(4)

ParameterTypeDefaultDescription
postgresql.enabledboolean-Enable PostgreSQL subchart
postgresql.auth.databasestring-PostgreSQL database name
postgresql.auth.usernamestring-PostgreSQL username
postgresql.auth.passwordstring-PostgreSQL password

Zookeeper(22)

ParameterTypeDefaultDescription
zookeeper.enabledboolean-Enable bundled ZooKeeper
zookeeper.image.repositorystring-ZooKeeper image repository
zookeeper.image.tagstring-ZooKeeper image tag
zookeeper.image.pullPolicystring-ZooKeeper image pull policy
Allowed:AlwaysIfNotPresentNever
zookeeper.replicaCountinteger-Number of ZooKeeper replicas
zookeeper.clientPortinteger-ZooKeeper client port
zookeeper.peerPortinteger-ZooKeeper peer port
zookeeper.electionPortinteger-ZooKeeper election port
zookeeper.tickTimeinteger-ZooKeeper tick time in milliseconds
zookeeper.initLimitinteger-ZooKeeper init limit
zookeeper.syncLimitinteger-ZooKeeper sync limit
zookeeper.fourLetterWordWhiteliststring-ZooKeeper 4-letter command whitelist
zookeeper.resourcesobject-ZooKeeper resources
zookeeper.podSecurityContextobject-ZooKeeper pod security context
zookeeper.securityContextobject-ZooKeeper container security context
zookeeper.podAnnotationsobject-ZooKeeper pod annotations
zookeeper.podLabelsobject-ZooKeeper pod labels
zookeeper.persistence.enabledboolean-Enable ZooKeeper persistence
zookeeper.persistence.sizestring-ZooKeeper data volume size
zookeeper.persistence.storageClassstring-ZooKeeper storage class
zookeeper.persistence.accessModesarray-ZooKeeper access modes
zookeeper.persistence.retentionPolicyany-Chart configuration parameter