使用 Helm 在 Kubernetes 上部署 Apache Druid：完整配置与实战指南

Apache Druid 是一款高性能的实时分析数据库，本指南基于本仓库incubator/druid目录下的 Helm Chart，系统讲解如何在 Kubernetes 集群中安装、配置和运维 Druid。通过阅读本文，你将掌握 Druid 六大核心组件（Overlord、Broker、Coordinator、Historical、Middle Manager、Router）的部署方式、全部可配置参数的作用与默认值，以及如何通过环境变量、ConfigMap、Ingress 和持久化存储实现生产级部署。

一、仓库与 Chart 概览

本仓库的incubator/druid目录包含一个完整的 Apache Druid Helm Chart（Chart 版本0.2.18，对应应用版本0.19.0），用于将 Druid 部署到 Kubernetes 集群。Chart 结构如下：

• Chart.yaml：Chart 元数据（名称、版本、描述、关键字 olap/database/analytics）
• values.yaml：所有可配置参数及其默认值（values.yaml）
• requirements.yaml：依赖声明（Zookeeper、MySQL、PostgreSQL）
• templates/：Kubernetes 资源模板，按组件分目录组织
• README.md：官方使用文档（README.md）

从 Chart.yaml 可以看到，该 Chart 声明了deprecated: true，这是仓库归档后的标记。注意：本仓库自 2020 年 11 月起停止更新，Chart 已被标记为弃用，仅适用于学习参考或兼容旧版本场景，不建议用于新项目生产部署。

Chart 通过 requirements.yaml 声明了三个可选依赖：

二、快速安装：一条命令拉起 Druid

2.1 安装 Chart

helm install --namespace "druid" --name "druid" incubator/druid

该命令会在druid命名空间中创建一个名为druid的 release。安装成功后：

# 查看 release 状态 helm status "druid"

如需删除整个部署（连同 PVC 一起清除）：

helm delete --purge "druid"

2.2 访问 Druid 控制台

安装完成后，Chart 自带的 NOTES.txt 会根据router.serviceType的类型给出访问提示。默认serviceType为ClusterIP，此时可以通过端口转发访问：

export POD_NAME=$(kubectl get pods --namespace druid -l "app=druid,release=druid" -o jsonpath="{.items[0].metadata.name}") kubectl port-forward $POD_NAME 8080:8888

然后访问http://127.0.0.1:8080即可打开 Druid Router 控制台。

如果设置了router.serviceType为NodePort或LoadBalancer，对应访问方式如下：

# NodePort 方式 export NODE_PORT=$(kubectl get --namespace druid -o jsonpath="{.spec.ports[0].nodePort}" services druid-router) export NODE_IP=$(kubectl get nodes --namespace druid -o jsonpath="{.items[0].status.addresses[0].address}") echo http://$NODE_IP:$NODE_PORT # LoadBalancer 方式（IP 可能需要几分钟才能就绪） kubectl get svc -w druid-router export SERVICE_IP=$(kubectl get svc --namespace druid druid-router -o jsonpath='{.status.loadBalancer.ingress[0].ip}') echo http://$SERVICE_IP:8888

三、核心架构：六个可部署组件

Druid 采用"查询节点、摄取节点、协调节点分离"的分布式架构，本 Chart 默认将其中六个核心服务打包为独立工作负载：

每个组件的源码模板位于templates/<component>/目录下，例如 templates/broker/、templates/historical/。

3.1 无状态组件与有状态组件的取舍

从模板结构可以清晰看出两类组件的差异：

• Deployment（无状态）：Broker、Coordinator、Overlord、Router 使用 Deployment。它们的核心状态（元数据、数据段信息）存储在外部依赖（ZooKeeper + 元数据库）中，因此可以随时扩缩容、滚动更新。查看 broker/deployment.yaml 可知，容器启动参数为args: [ "broker" ]，通过broker.config注入 JVM 与处理线程等私有配置。

• StatefulSet（有状态）：Historical 和 Middle Manager 使用 StatefulSet，且默认开启持久化。因为它们需要在本地磁盘缓存/写入数据段（segment），持久卷保证了节点重启后数据不丢失。每个 Pod 会获得稳定的网络标识与独立的 PVC，见 historical/statefulset.yaml。

以 historical/statefulset.yaml 为例，其持久化通过volumeClaimTemplates实现：

volumeClaimTemplates: - metadata: name: data spec: accessModes: - "ReadWriteOnce" resources: requests: storage: "4Gi"

数据挂载点为/opt/druid/var/druid/。若设置historical.persistence.enabled: false，则改用emptyDir临时卷。

四、Chart 前缀与命名规范

Chart 前缀：为避免多个 release 或组件之间资源名冲突，本 Chart 会自动以 release 名称作为前缀拼接所有资源名。命名逻辑定义在 _helpers.tpl：

• 全局资源名：{{ release-name }}-{{ chart-name }}（例如druid-druid会被自动去重为druid）
• 组件资源名：{{ fullname }}-{{ component.name }}（例如druid-broker、druid-historical、druid-middleManager）

这些名称会作为 Pod 标签（app、component、release、chart、heritage）被注入到所有资源中，方便通过 label 进行选择和运维。

五、URL 前缀：六个对外端点

本 Chart 暴露 6 个 HTTP 端点，分别对应六大组件：

• Druid Overlord（8081）
• Druid Broker（8082）
• Druid Coordinator（8081）
• Druid Historical（8083）
• Druid Middle Manager（8091）
• Druid Router（8888）

每个组件都配套了Service与可选的Ingress模板。Service 默认类型为ClusterIP，可通过各组件的serviceType调整为NodePort或LoadBalancer。

5.1 配置 Ingress

每个组件都支持独立的 Ingress 配置，例如 Broker：

broker: ingress: enabled: false annotations: {} # kubernetes.io/ingress.class: nginx # kubernetes.io/tls-acme: "true" path: / hosts: - chart-example.local tls: [] # - secretName: chart-example-tls # hosts: # - chart-example.local

参数说明：

• enabled：是否创建 Ingress 资源，默认false
• annotations：Ingress 注解，例如指定 Ingress Controller 类型或启用 Let's Encrypt 自动签发 TLS 证书（kubernetes.io/tls-acme: "true"）
• path：API 的访问路径，默认/
• hosts：域名列表，默认[ "chart-example.local" ]，需替换为实际域名
• tls：TLS 证书配置，可引用已创建的 Secret

Ingress 模板实现在各组件的ingress.yaml中，例如 broker/ingress.yaml。

六、Druid 配置的两种注入方式

6.1 全局配置：ConfigMap（configVars）

Chart 会将configVars中的键值对渲染为一个 ConfigMap（模板见 configmap.yaml），并通过envFrom.configMapRef注入到所有组件的容器环境中。默认内容如下：

configVars: # DRUID env vars DRUID_USE_CONTAINER_IP: "true" ## Druid Common Configurations druid_extensions_loadList: '["druid-histogram", "druid-datasketches", "druid-lookups-cached-global", "postgresql-metadata-storage"]' druid_metadata_storage_type: postgresql druid_metadata_storage_connector_connectURI: jdbc:postgresql://postgres:5432/druid druid_metadata_storage_connector_user: druid druid_metadata_storage_connector_password: druid druid_storage_type: local druid_indexer_logs_type: file druid_indexer_logs_directory: /opt/data/indexing-logs ## Druid Emitting Metrics druid_emitter: noop druid_emitter_logging_logLevel: debug druid_emitter_http_recipientBaseUrl: http://druid_exporter_url:druid_exporter_port/druid

这些键值对应 Druid 的配置规范（Druid 会将环境变量名中的_转换为.后作为配置属性）。要点：

• DRUID_USE_CONTAINER_IP: "true"：让 Druid 使用容器 IP 进行节点间通信（Kubernetes 环境必需）
• druid_extensions_loadList：指定要加载的扩展，默认加载druid-histogram（直方图）、druid-datasketches（近似聚合）、druid-lookups-cached-global（全局缓存查找）以及元数据存储扩展
• druid_metadata_storage_type与连接参数：元数据存储连接信息。该值会被下方 6.3 的依赖配置逻辑按需覆盖
• druid_storage_type: local：segment 深度存储类型
• druid_emitter: noop：指标发射器，可按需改为logging或http

6.2 组件私有配置：config

每个组件的config字段只对该组件生效，用于覆盖全局配置，典型如 JVM 堆参数与处理线程数：

broker: config: DRUID_XMX: 512m DRUID_XMS: 512m DRUID_MAXDIRECTMEMORYSIZE: 400m druid_processing_buffer_sizeBytes: '50000000' druid_processing_numMergeBuffers: 2 druid_processing_numThreads: 1

在 Deployment/StatefulSet 模板中，组件私有配置以普通env注入（优先级高于envFrom的 ConfigMap），例如 broker/deployment.yaml：

env: - name: DRUID_XMX value: "512m" envFrom: - configMapRef: name: druid

Druid Docker 入口点会读取这些环境变量并将其转换为 Druid 的 JVM/运行时配置，因此修改config即可完成 JVM 堆、直接内存、处理缓冲等调优，无需修改镜像。

6.3 依赖组件自动注入的配置

configmap.yaml 会根据依赖开关自动生成对应的元数据连接配置：

• 当zookeeper.enabled: true时，自动设置druid_zk_service_host: <release>-zookeeper-headless:2181；否则使用zkHosts自定义值
• 当postgresql.enabled: true时，自动覆盖元数据存储类型为postgresql，并注入连接串jdbc:postgresql://<release>-postgresql:5432/druid、用户名与密码
• 当mysql.enabled: true时，自动覆盖为mysql类型，并注入jdbc:mysql://<release>-mysql:3306/druid连接串

七、完整的配置参数表

以下参数表完整继承自 README.md，并结合 values.yaml 补充了实际默认值，供部署时直接参考。

7.1 镜像与全局配置

7.2 Broker（默认启用）

7.3 Coordinator（默认启用）

7.4 Overlord（默认禁用）

7.5 Historical（默认启用，StatefulSet）

7.6 Middle Manager（默认启用，StatefulSet）

7.7 Router（默认启用）

八、深入源码：组件如何被实例化

8.1 统一的环境变量注入模式

所有组件的模板都遵循同一套模式：容器启动参数（args）指定 Druid 服务类型，私有配置走env，全局配置走envFrom.configMapRef，健康检查统一为/status/health探针。以 router/deployment.yaml 为例：

containers: - name: druid image: "apache/druid:0.19.0" args: [ "router" ] env: - name: DRUID_XMX value: "128m" envFrom: - configMapRef: name: druid livenessProbe: initialDelaySeconds: 60 httpGet: path: /status/health port: 8888

探针延迟 60 秒启动，是为了等待 Druid JVM 完成初始化，避免误判。

8.2 Middle Manager 的 HPA 自动扩缩容

Middle Manager 是唯一支持水平自动扩缩容的组件（摄取负载通常波动较大）。HPA 模板见 middleManager/hpa.yaml，默认定义了两个指标：CPU 与内存平均利用率达 60% 时触发扩容，副本范围 2~5：

autoscaling: enabled: false minReplicas: 2 maxReplicas: 5 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 60 - type: Resource resource: name: memory target: type: Utilization averageUtilization: 60

启用时需确保集群部署了 metrics-server 或等效指标源。

8.3 反亲和与滚动更新

Historical 与 Middle Manager 的 StatefulSet 支持antiAffinity参数（soft/hard），实现逻辑见 historical/statefulset.yaml：

• soft（默认）：preferredDuringSchedulingIgnoredDuringExecution，调度器尽量将同组件 Pod 分散到不同节点，但不强制
• hard：requiredDuringSchedulingIgnoredDuringExecution，以kubernetes.io/hostname为拓扑键强制分散，保证数据副本分布在不同的物理节点上，避免单点故障

同时二者均支持podDisruptionBudget（默认关闭，maxUnavailable: 1）与RollingUpdate更新策略，保障节点维护或升级期间服务的可用性。

8.4 命名辅助函数

_helpers.tpl 定义了druid.name、druid.fullname、druid.chart以及各组件专属的druid.<component>.fullname模板函数。所有名称都被截断至 63 字符，满足 Kubernetes DNS 命名规范，从而保证集群内服务发现（如<release>-zookeeper-headless:2181）可用。

九、生产部署实践建议

9.1 依赖选型

默认部署会附带 ZooKeeper（zookeeper.enabled: true）和 PostgreSQL（postgresql.enabled: true）两个子 Chart。对于生产环境，通常建议：

• 元数据存储：默认使用 PostgreSQL（druid_metadata_storage_type: postgresql）。若已有外部元数据库，可关闭postgresql.enabled并通过configVars或zkHosts手动指定连接地址
• ZooKeeper：Druid 依赖 ZooKeeper 进行节点协调与任务分发，若已有外部 ZooKeeper 集群，设置zookeeper.enabled: false并配置zkHosts
• 深度存储：默认druid_storage_type: local配合 PVC；大规模场景可改为 HDFS 或 S3 等分布式存储

9.2 资源规划

默认配置中的 JVM 参数偏向小规模验证（Broker 512m、Coordinator 256m、Historical 512m、Middle Manager 64m、Router 128m）。生产环境请结合数据量、查询并发和摄取吞吐量，通过各组件的config与resources合理上调，尤其注意 Historical 和 Middle Manager 的DRUID_MAXDIRECTMEMORYSIZE与处理缓冲参数需要匹配内存配额。

9.3 Google Cloud Storage 集成

若使用 GCS 作为深度存储，可启用：

gCloudStorage: enabled: true secretName: google-cloud-key

开启后，Chart 会：

• 在 ConfigMap 中注入GOOGLE_APPLICATION_CREDENTIALS: /var/secrets/google/key.json
• 创建 Secret（模板见 secrets.yaml），将google.gcsAPIKey中的凭据写入key.json
• 在 StatefulSet 中以 Secret 卷方式挂载到/var/secrets/google（见 historical/statefulset.yaml）

十、故障排查与运维提示

• 查看健康状态：所有组件均暴露/status/health端点，可用于存活与就绪探针。kubectl get pods看到Ready状态即代表组件通过健康检查
• 端口转发访问控制台：Router 默认ClusterIP，使用kubectl port-forward即可在本地访问 Druid Web 控制台
• 配置热更新：修改configVars后helm upgrade会更新 ConfigMap，但环境变量注入只在容器启动时生效，需要滚动重启 Pod 使配置生效
• 归档说明：本 Chart 及仓库已停止维护，若在生产环境使用，请关注 Apache Druid 官方镜像与 Kubernetes 生态的后续演进

十一、总结

通过本 Chart，你可以用一条helm install命令在 Kubernetes 上完整拉起 Apache Druid 的六大核心组件，并通过values.yaml精细控制每个组件的镜像、端口、副本数、JVM 参数、持久化、亲和性、自动扩缩容与 Ingress 暴露方式。其核心设计——全局 ConfigMap + 组件私有环境变量——使得 Druid 的复杂配置体系得以在 Helm 的声明式框架下被清晰管理，是学习 Druid 分布式架构与 Helm 编排的最佳参考实现之一。

进一步阅读：完整的默认配置注释见 values.yaml，资源模板见 templates/ 目录。