Kafka KRaft 模式 Kubernetes 部署手册StatefulSet apache/kafka 官方镜像https://blog.csdn.net/qq_34777982/article/details/166831220?sharetypeblogdetailsharerId166831220sharereferPCsharesourceqq_34777982spm1011.2480.3001.8118目标用Apache 官方镜像apache/kafka:4.3.1在 Kubernetes 上以StatefulSet方式部署KRaft无 ZooKeeper集群。随本手册交付 3 个可直接kubectl apply的清单文件kafka-kraft-combined.yaml主方案、kafka-kraft-isolated.yaml角色分离、kafka-kraft-external-access.yaml可选外部访问。一、方案概览项目选择说明镜像apache/kafka:4.3.1Apache 官方 JVM 镜像自 3.7.0 起提供另有实验性的apache/kafka-nativeGraalVM官方明确仅建议本地开发测试使用元数据KRaft4.x 已完全移除 ZooKeeper 依赖不需要部署 ZK工作负载StatefulSet需要稳定的 Pod 名称、DNS 与独占存储服务发现Headless Servicekafka-0.kafka-headless.kafka.svc.cluster.local等稳定域名存储volumeClaimTemplates每个 Pod 一块独立 PVC模式Combined默认/ Isolated备选Combined brokercontroller 合一3 节点Isolated 3 controller 3 broker文件清单文件内容适用kafka-kraft-combined.yamlNamespace Headless/ClusterIP Service 3 节点 StatefulSet PDB中小规模生产、测试/预发kafka-kraft-isolated.yamlNamespace controller/broker 两套 StatefulSet各 3 副本 Service PDB生产环境角色分离kafka-kraft-external-access.yaml每 Pod 一个 NodePort Service需要集群外客户端接入时两个部署文件二选一不要同时 apply。二、前置条件Kubernetes 集群≥ 1.24StatefulSet、policy/v1PDB 均可用能正常执行kubectl。集群中已有可用的StorageClasskubectl get sc且支持ReadWriteOnce。节点有足够资源Combined 3 节点建议 ≥ 4C8G/节点Isolated 建议 controller 1C2G、broker 4C8G 起。节点能拉取apache/kafka:4.3.1内网环境请先同步到私有镜像仓库并替换清单中的 image 地址。时区/时钟同步正常KRaft 对时钟敏感节点需有 NTP。三、关键设计说明为什么这么写1. 为什么必须podManagementPolicy: ParallelKRaft 的 controller quorum 需要 3 个成员同时在线才能选举出 leader。若用默认的OrderedReadykafka-0会一直等 quorum 而不 Readykafka-1、kafka-2就永远不会被创建 —— 直接死锁。2. 为什么 Headless Service 要开publishNotReadyAddresses: true同理Pod 之间要靠 DNS 互相解析才能组 quorum。若 DNS 记录只在 Pod Ready 之后才注册就会陷入要 Ready 先要互相解析、要互相解析先要 Ready的循环。3. 为什么用 bash 包一层启动命令官方镜像的启动命令是/etc/kafka/docker/run在 Dockerfile 中由CMD指定不是ENTRYPOINT因此可以被覆盖。而这两个值每个 Pod 都不同无法用静态环境变量写死node.idKAFKA_NODE_ID由 Pod 名后缀推导kafka-0→ 0advertised.listenersKAFKA_ADVERTISED_LISTENERS必须是客户端能连到本 Pod的地址用 Pod 的稳定 DNS。exportKAFKA_NODE_ID${POD_NAME##*-}exportKAFKA_ADVERTISED_LISTENERSPLAINTEXT://${POD_NAME}.kafka-headless.kafka.svc.cluster.local:9092exec/etc/kafka/docker/runPOD_NAME来自 Downward APIfieldRef: metadata.name比依赖容器内HOSTNAME变量更稳。4. 官方镜像的配置注入规则镜像支持三种配置方式优先级从低到高内置默认配置 → 挂载文件/mnt/shared/config/*.properties→ 环境变量。环境变量命名规则.→_、_→__、-→___再加前缀KAFKA_配置项环境变量node.idKAFKA_NODE_IDlog.dirsKAFKA_LOG_DIRSoffsets.topic.replication.factorKAFKA_OFFSETS_TOPIC_REPLICATION_FACTORabc-defKAFKA_ABC___DEFabc_defKAFKA_ABC__DEFKAFKA_HEAP_OPTS、KAFKA_OPTS、KAFKA_LOG4J_*等属于脚本特殊处理变量不遵循上述映射。5. 集群 ID 与自动格式化镜像内置了一个默认CLUSTER_ID未设置时自动使用启动时会调用kafka.docker.KafkaDockerWrapper setup把默认配置 挂载配置 KAFKA_*环境变量合并写入/opt/kafka/config/server.properties并在数据目录未格式化时自动格式化已格式化则跳过并打印already formatted。实践建议显式设置CLUSTER_ID用kafka-storage.sh random-uuid生成同一集群所有节点保持一致。集群 ID 只在首次格式化时写入meta.properties后期更换必须清空数据卷重新格式化。6. 权限官方镜像内建用户appuseruid1000 / gid1000数据目录/var/lib/kafka/data。清单中固定securityContext:runAsUser:1000runAsGroup:1000runAsNonRoot:truefsGroup:1000# 关键让 PVC 对 appuser 可写注意镜像运行过程中需要写/opt/kafka/config生成最终配置文件因此不要开启readOnlyRootFilesystem: true否则启动会报/opt/kafka/config/ file not writable。7. 探针只用startupProbereadinessProbe不配livenessProbeKafka 启动慢且绝大多数启动失败quorum 不完整、存储权限、集群 ID 不一致重启无法自愈配了 liveness 只会陷入反复重启。Broker 用kafka-broker-api-versions.sh --bootstrap-server localhost:9092探测能响应 API 请求才算真就绪controller 用 9093 端口 TCP 探测。四、部署步骤第 1 步生成集群 IDkubectl create namespace kafka kubectl-nkafka run kafka-cluster-id--rm-it--restartNever\--imageapache/kafka:4.3.1 -- /opt/kafka/bin/kafka-storage.sh random-uuid输出形如4L6g3nShT-eMCtK--X86sw。把它填进清单里的CLUSTER_IDCombined 清单只有一处Isolated 清单有 controller、broker 两处必须一致。第 2 步按环境修改清单storageClassName改成集群实际存在的 StorageClassstorage数据盘容量生产建议 ≥ 50Gi并预留扩容能力resourcesCPU/内存按实际调整KAFKA_HEAP_OPTS的堆大小取容器内存 limits 的约 1/2image内网环境改成私有仓库地址。第 3 步部署# 主方案Combined 3 节点kubectl apply-fkafka-kraft-combined.yaml# 或者角色分离Isolated 3 controller 3 broker# kubectl apply -f kafka-kraft-isolated.yaml# 可选需要集群外访问时再应用# kubectl apply -f kafka-kraft-external-access.yaml第 4 步等待就绪kubectl-nkafka get pods-owide-wkubectl-nkafka get pvc预期Combined 模式下kafka-0/1/2全部Running且READY 1/1每个 Pod 各有一块Bound的 PVC。五、验证1. 看日志确认进程启动kubectl-nkafka logs kafka-0|tail-n40应能看到Kafka Server started首次启动还会有格式化数据目录的相关输出重启后则显示already formatted并跳过。2. 起一个客户端 Pod 做功能验证kubectl-nkafka run kafka-client--imageapache/kafka:4.3.1--restartNever --tail-f/dev/null kubectl-nkafkaexec-itkafka-client --bash容器内依次执行Isolated 模式同样可用kafka-bootstrap指向 broker# 1) 查看 KRaft 元数据 quorum 状态应看到 3 个 voter其中一个为 Leader/opt/kafka/bin/kafka-metadata-quorum.sh --bootstrap-server kafka-bootstrap:9092 describe--status# 2) 建 topic副本因子 3/opt/kafka/bin/kafka-topics.sh --bootstrap-server kafka-bootstrap:9092\--create--topicdemo--partitions3--replication-factor3# 3) 确认分区分布3 个分区应分别以 kafka-0/1/2 为 leader/opt/kafka/bin/kafka-topics.sh --bootstrap-server kafka-bootstrap:9092--describe--topicdemo# 4) 生产/opt/kafka/bin/kafka-console-producer.sh --bootstrap-server kafka-bootstrap:9092--topicdemo# 输入几行文本后 CtrlC 退出# 5) 消费/opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server kafka-bootstrap:9092\--topicdemo --from-beginning --max-messages53. 故障演练可选删掉一个 broker Pod观察 topic 仍可读写、quorum 仍正常kubectl-nkafka delete pod kafka-1 kubectl-nkafka get pods-w六、客户端接入集群内应用bootstrap 地址所有 Pod 都是入口任填一个或全部地址用途kafka-bootstrap.kafka.svc.cluster.local:9092常规入口ClusterIP负载到任一 brokerkafka-0.kafka-headless.kafka.svc.cluster.local:90921、2 同理指定 Pod 直连排查问题时用跨命名空间访问时用 FQDN 即可。注意客户端拿到的是advertised.listeners中的 Pod DNS因此客户端必须能解析集群内的 Pod 域名把应用部署在同一集群内最省事。集群外应用见kafka-kraft-external-access.yaml头部注释需要额外加一个EXTERNAL监听9094并把每个 Pod 的对外地址写进advertised.listeners再为每个 Pod 配一个固定nodePort的 Service。安全提醒PLAINTEXT暴露到公网等于无认证无加密生产必须改用SASL_SSL/SSL镜像支持把证书与 JAAS 配置挂到/etc/kafka/secrets再用KAFKA_OPTS指向 JAAS 文件。七、扩缩容与日常运维Combined 模式扩容注意本清单是静态 quorumbroker 与 controller 是同一批 Pod增加副本数会同时增加一个 controller因此不是改一下replicas就行。本手册的清单显式配置了KAFKA_CONTROLLER_QUORUM_VOTERS属于静态 quorum扩容 controller 必须同步更新所有节点看到的成员列表把新节点的nodeIdPod FQDN:9093加进KAFKA_CONTROLLER_QUORUM_VOTERS所有节点包括新节点自己replicas相应调整controller 数量建议保持奇数3 → 5 更合适4 个 controller 的容错能力并不优于 3 个apply后 StatefulSet 会滚动重启全部 Pod期间集群有短暂不可用 —— 安排在维护窗口执行并先确认 topic 副本因子 ≥ 3、min.insync.replicas2。想避免改 voters 就要全量滚动重启需要在集群首次格式化时就建立动态 quorum不配controller.quorum.voters改配controller.quorum.bootstrap.servers并在格式化时带--initial-controllers。此后即可用kafka-metadata-quorum.sh ... add-controller/remove-controller在线增删 controller。判断当前属于哪种 quorum/opt/kafka/bin/kafka-features.sh --bootstrap-controller\kafka-0.kafka-headless.kafka.svc.cluster.local:9093 describekraft.version为0或字段不存在 静态 quorum≥ 1 动态 quorum。注意官方镜像的自动格式化默认得到静态 quorum要动态 quorum 需自行控制格式化流程。Isolated 模式扩容broker 层可以直接扩kubectl-nkafka scale statefulset kafka-broker--replicas5因为 broker 的node.id由 Pod 名推导kafka-broker-N→N3新增 Pod 会自动获得不冲突的 ID且 broker 不在 quorum voters 列表中无需改动 controller 配置。controller 数量建议保持奇数3 或 5。缩容与下线先用kafka-reassign-partitions.sh把待下线 broker 上的分区副本迁移走controller 节点动态 quorum 下先用kafka-metadata-quorum.sh ... remove-controller移出 quorum 再停机静态 quorum 下则要从所有节点的KAFKA_CONTROLLER_QUORUM_VOTERS中移除该节点并滚动重启再scale或删除 PodPVC 不会随 Pod 删除而释放需要手动清理kubectl -n kafka delete pvc>滚动重启 / 升级改镜像版本或环境变量会触发 StatefulSet 滚动更新。配合 PDBmaxUnavailable: 1可保证一次只动一个 Pod生产建议在低峰期执行并先确认 topic 副本因子 ≥ 3、min.insync.replicas2。磁盘扩容StorageClass 支持在线扩容时改volumeClaimTemplates的storage后需逐个kubectl -n kafka edit pvc>八、生产加固清单副本与一致性default.replication.factor3、min.insync.replicas2、unclean.leader.election.enablefalse生产者的acksall。自动建 Topic 关闭auto.create.topics.enablefalse清单已设置避免误建单副本 topic。资源与 JVMKAFKA_HEAP_OPTS取容器内存 limits 的约 1/2其余留给页缓存limits 过小会被 OOMKill。存储使用 SSD/本地盘类高性能 StorageClass磁盘写满会导致 broker 不可用务必配置磁盘使用率告警。反亲和把preferredDuringSchedulingIgnoredDuringExecution改成requiredDuringSchedulingIgnoredDuringExecution强制 3 副本分散到不同节点跨可用区用topologySpreadConstraints。监控开启 JMXKAFKA_JMX_PORT并配 JMX Exporter sidecar或部署 kafka-exporter重点指标UnderReplicatedPartitions、OfflinePartitionsCount、ActiveControllerCount、请求延迟、磁盘使用率。安全启用 SASL/SSL/etc/kafka/secrets挂载证书与 JAAS用 NetworkPolicy 限制 9092/9093 的来源。日志与保留log.retention.hours、log.segment.bytes按业务量调整避免磁盘无限增长。备份与容灾跨集群用 MirrorMaker 2 复制关键 topic 单独设置保留策略。时钟同步节点必须 NTP 同步。九、常见问题排查现象常见原因处理kafka-1/kafka-2迟迟不被创建podManagementPolicy不是Parallel改回Parallel后重新 applyPod Running 但不 Ready日志反复解析失败Headless Service 未开publishNotReadyAddresses开启后重建 Service日志KAFKA_ADVERTISED_LISTENERS is not supported on a KRaft controller.后退出controller-only 节点设置了该变量从 controller 的 env 中删除Isolated 清单已规避日志/opt/kafka/config/ file not writable开启了只读根文件系统或 Docker 20.10.4关闭readOnlyRootFilesystem升级容器运行时Permission denied写/var/lib/kafka/data缺fsGroup: 1000补上 securityContext更换CLUSTER_ID后启动失败 / 集群 ID 不一致数据目录已格式化meta.properties里是旧 ID清空对应 PVC 后重新启动PVC 一直PendingStorageClass 不存在、无可用 PV、容量超限检查kubectl get sc/kubectl describe pvc客户端连上后超时或反复重连advertised.listeners地址客户端不可达跨集群、NAT、NodePort 配错核对客户端网络能否解析/直连 Pod DNS 或节点 IP:nodePortbroker 起不来、日志报 quorum 相关错误KAFKA_CONTROLLER_QUORUM_VOTERS中 node.id 与各 Pod 实际KAFKA_NODE_ID不匹配或 DNS 写错逐项核对 voters 列表与 Pod 名升级/重启后部分分区副本不同步单 Pod 停机时间过长、副本因子不足用kafka-topics.sh --describe看 ISR必要时kafka-reassign-partitions.sh修复常用排查命令kubectl-nkafka get pods,pvc,svc kubectl-nkafka describe pod kafka-0 kubectl-nkafka logs kafka-0--previouskubectl-nkafkaexec-itkafka-0 --cat/opt/kafka/config/server.properties kubectl-nkafkaexec-itkafka-0 --ls-l/var/lib/kafka/data十、参考来源Apache Kafka 官方 Docker 页面镜像版本与拉取方式https://kafka.apache.org/43/getting-started/docker/Apache Kafka 官方 Docker 镜像使用指南环境变量命名规则、集群 ID、挂载配置、SASL/SSLhttps://github.com/apache/kafka/blob/trunk/docker/examples/README.md官方多节点示例Combined / Isolated 的完整环境变量清单https://github.com/apache/kafka/tree/trunk/docker/examples/docker-compose-files/clusterApache Kafka 4.3.1 发布公告https://kafka.apache.org/blog/2026/06/25/apache-kafka-4.3.1-release-announcement/KRaft 运维文档动态调整 controller quorum、add/remove-controllerhttps://kafka.apache.org/43/operations/kraft/Docker Hubapache/kafkahttps://hub.docker.com/r/apache/kafka附清单参数速查环境变量作用本手册取值CLUSTER_IDKRaft 集群 ID需自行生成KAFKA_NODE_ID节点 ID由 Pod 名推导0/1/2broker 从 3 起KAFKA_PROCESS_ROLES角色broker,controllerKAFKA_CONTROLLER_QUORUM_VOTERS控制器 quorum 成员idPod FQDN:9093KAFKA_LISTENERS监听地址PLAINTEXT://:9092,CONTROLLER://:9093KAFKA_ADVERTISED_LISTENERS对外通告地址每个 Pod 不同Pod FQDN:9092KAFKA_LOG_DIRS数据目录/var/lib/kafka/dataKAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR内部 topic 副本数3单机测试改 1