参数参考

KAFKA 角色刻意只公开 16 项持久参数。拓扑、Listener、安全实现、存储子目录、复制安全与 Exporter 放置等细节由角色统一推导，不能作为额外持久变量覆盖。

参数概览

kafka_cluster 与 kafka_seq 必须定义；kafka_role 有真实默认值。集群角色要么全部省略，要么全部显式声明。

身份与拓扑

kafka_cluster

必填的集群身份。必须以字母或数字开头，只能包含字母、数字、下划线和连字符：

kafka_cluster: kf-main

它用于发现完整集群成员、生成实例名和定位 Bootstrap Manifest。每次 kafka.yml 生命周期操作必须用精确 -l 选择该集群的全部成员。

kafka_seq

必填的非负整数，在同一 kafka_cluster 中唯一，直接成为 KRaft node.id：

10.10.10.11: { kafka_seq: 1 }

实例名派生为 ${kafka_cluster}-${kafka_seq}。节点格式化后不要修改或复用仍有关联数据的序号。

kafka_role

默认 combined，只接受：

集群所有成员都省略时一致使用 combined；只要任一成员显式设置，所有成员都必须显式设置。不提供旧角色别名。

kafka_cluster_id

默认未设置，仅用于接管或恢复时断言现有集群身份，必须是 22 字符 Kafka UUID：

kafka_cluster_id: MkU3OEVBNTcwNTJENDM2Qk

普通新建集群不要设置。角色会随机生成 Cluster ID，并写入 files/kafka/<kafka_cluster>/manifest.yml。该参数不会重新标记现有数据；与 Manifest 或 meta.properties 冲突时会失败关闭。

kafka_rack

可选的 Broker 故障域标签，渲染为 broker.rack：

10.10.10.21: { kafka_seq: 4, kafka_role: broker, kafka_rack: az-a }

所有 Broker-capable 节点必须全部声明或全部省略。纯 Controller 不使用该值。修改 Rack 属于静态变化，会进入严格滚动，但不会重新分配既有副本。

存储、JVM 与网络

kafka_data

数据根目录，默认 /data/kafka：

kafka_data: /data/kafka

角色固定派生 ${kafka_data}/data 与 ${kafka_data}/metadata。该路径必须是专用绝对路径，不能是 /、/data、/var、/etc、/opt、/usr、/home、/root 或 /pg。受保护清理会删除整个根目录，因此不要混放其他服务或业务文件。

kafka_heap_opts

Kafka JVM Heap，默认：

kafka_heap_opts: '-Xms1G -Xmx1G'

生产应根据负载与内存压测设置，通常保持 Xms 与 Xmx 相同，并为操作系统 Page Cache 与其他进程留出足够内存。

kafka_port

Broker/client 监听端口，默认 9092，只在 Broker-capable 节点监听。plaintext 模式使用 PLAINTEXT；scram 模式使用 SASL_SSL + SCRAM-SHA-512。

kafka_controller_port

KRaft Controller 监听端口，默认 9095，只在 Controller-capable 节点监听。默认避开 Pigsty Alertmanager 的 9093；目标属于 infra 分组时，角色会显式拒绝与 alertmanager_port 冲突。

四个公开端口必须在 1..65535 内且彼此不同。监听地址固定为 0.0.0.0，Broker advertised address 与 Controller bootstrap address 固定使用 inventory_hostname，不另设地址参数。

kafka_parameters

默认 {}，是唯一的 Kafka Broker 参数逃生舱，只渲染到 Broker-capable 节点：

kafka_parameters:
  num.partitions: 12
  num.network.threads: 6
  num.io.threads: 16
  log.retention.hours: 168
  log.segment.bytes: 1073741824

以下键或模式由角色拥有，不能通过该映射覆盖：

process.roles
node.id
controller.quorum.*
listeners
advertised.listeners
listener.security.protocol.map
inter.broker.listener.name
controller.listener.names
log.dirs
metadata.log.dir
min.insync.replicas
default.replication.factor
offsets.topic.replication.factor
transaction.state.log.replication.factor
transaction.state.log.min.isr
share.coordinator.state.topic.replication.factor
share.coordinator.state.topic.min.isr
broker.rack
authorizer.class.name
super.users
allow.everyone.if.no.acl.found
sasl.*
ssl.*
listener.*

身份、监听器、安全、存储与复制策略必须保持单一权威；包含保留键时预检会直接失败。

可观测性

kafka_jmx_exporter_enabled

默认 true。启用后，每个 Kafka JVM 注入 JMX Exporter Java Agent，并注册为 job=kafka。关闭只降低可观测性；生命周期健康门禁仍使用角色自有 Kafka CLI/metadata 通道，不依赖 JMX。

kafka_jmx_exporter_port

JMX Exporter HTTP 端口，默认 9404。Infra 监控节点必须可以访问。该端点不因 kafka_security: scram 自动启用 HTTPS，应通过监控网络和防火墙保护。

kafka_exporter_port

协议型 kafka_exporter HTTP 端口，默认 9308。角色只在按 kafka_seq 排序后的前两个 Broker-capable 节点运行与注册；单 Broker 集群只运行一个，未被选择的节点会移除 Unit、环境文件、CA 副本和 Target。

Exporter 使用的 Kafka 协议版本、TLS/SCRAM 参数和副本放置均为角色内部约定，没有额外公开开关或 options 参数。

安全与资源

kafka_security

默认 plaintext，只接受：

scram 同时配置 Pigsty CA 签发的节点证书、角色自有管理/监控/内部身份、TLS/SCRAM 与 ACL 启用顺序。安全模式写入 Bootstrap Manifest；集群格式化后，普通重跑不能把 plaintext 切换成 scram，也不能反向切换。

kafka_users

默认 []，仅允许在 scram 模式声明。每个对象只接受 name、password、acls、quota：

kafka_users:
  - name: order-service
    password: "{{ vault_kafka_order_password }}"
    acls:
      - resource: topic
        name: order.
        pattern: prefixed
        operations: [Read, Write, Describe]
      - resource: group
        name: order.
        pattern: prefixed
        operations: [Read]
      - resource: transactional_id
        name: order.
        pattern: prefixed
        operations: [Write, Describe]
    quota:
      producer_byte_rate: 10485760
      consumer_byte_rate: 20971520

约束：

• name 在列表中唯一；password 必填且至少 12 个字符，应引用秘密管理系统；
• ACL resource 为 topic、group、transactional_id、cluster；
• pattern 为 literal（默认）或 prefixed；
• 操作为 Read、Write、Create、Delete、Alter、Describe、ClusterAction、DescribeConfigs、AlterConfigs、IdempotentWrite；
• Quota 键为 producer_byte_rate、consumer_byte_rate、request_percentage、controller_mutation_rate。

角色为声明用户收敛 SCRAM 密码、完整 ACL 集合与显式给出的 Quota 字段。移除用户条目不会隐式删除 Principal 或凭据；删除/撤权需要独立受审操作。

kafka_topics

默认 []。每个对象只接受 name、partitions、replication_factor、config：

kafka_topics:
  - name: order.events
    partitions: 12
    replication_factor: 3
    config:
      min.insync.replicas: 2
      cleanup.policy: delete
      retention.ms: 604800000

name 在列表中唯一；Partition 与 RF 都必须至少为 1，RF 不能超过当前 Broker 数。收敛语义是：

• Topic 不存在时幂等创建；
• Partition 只允许增加，减少会失败；
• RF 与现场不同时拒绝普通收敛，并要求显式 Reassignment；
• 只更新 config 中声明的键；
• 从列表中移除 Topic 永远不会删除 Topic。

临时受保护运维变量

以下变量只通过命令行 -e 用于一次性受保护动作，不属于 16 项持久 API，也不应写入 pigsty.yml：

两种轮换动作互斥。清理会删除数据、节点安全状态、监控 Target、Manifest 与角色自有 Secret/PKI，必须执行显式确认与备份核验。命令与完整保护条件见 预置剧本。