# demo/kafka

> 四节点 dynamic KRaft 示例：单节点明文开发集群与三节点 TLS/SCRAM 高可用基线

---

LLMS index: [llms.txt](/llms.txt)

---

`demo/kafka` 在四个节点上声明两套 Kafka 4.x dynamic KRaft 集群：单节点明文开发集群 `kf-meta`，以及三节点 TLS/SCRAM/ACL 演示集群 `kf-test`。


--------

## 配置概览

- 配置名称：`demo/kafka`
- 节点数量：4 个
- `kf-meta`：单节点 combined Broker/Controller，明文模式
- `kf-test`：3 个 combined 节点，TLS/SCRAM/ACL，Topic 副本数 3、`min.insync.replicas=2`
- 模块状态：KAFKA BETA

```bash
./configure -c demo/kafka -s
./deploy.yml
./kafka.yml -l kf-meta
./kafka.yml -l kf-test
```

`deploy.yml` 只部署核心链路，并不会自动执行 KAFKA 剧本。每次 `kafka.yml` 运行都应选择一个完整的 Kafka 集群；角色会拒绝只选中部分成员的收敛操作。


--------

## 配置内容

源文件地址：[`pigsty/conf/demo/kafka.yml`](https://github.com/pgsty/pigsty/blob/main/conf/demo/kafka.yml)

<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">#==============================================================#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># File      :   kafka.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Desc      :   pigsty: 4 node kafka demo (dynamic KRaft)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Ctime     :   2026-07-17</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Mtime     :   2026-07-17</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Docs      :   https://pigsty.io/docs/kafka</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># License   :   Apache-2.0 @ https://pigsty.io/docs/about/license/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Copyright :   2018-2026  Ruohang Feng / Vonng (rh@vonng.com)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">#==============================================================#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># One pass installation with:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># ./deploy.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># ./kafka.yml -l kf-main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># ./kafka.yml -l kf-test</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">#==============================================================#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># 1.  kf-meta-1 @ 10.10.10.10:9092   single-node dev cluster (plaintext)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># 2.  kf-test-1 @ 10.10.10.11:9092 \</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># 3.  kf-test-2 @ 10.10.10.12:9092 --- 3-node secure HA demo baseline (scram)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># 4.  kf-test-3 @ 10.10.10.13:9092 /   dynamic KRaft, TLS/SCRAM/ACL, RF=3/minISR=2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">#==============================================================#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># kafka clients are cluster-aware and connect to every broker directly:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># bootstrap with e.g. 10.10.10.11:9092,10.10.10.12:9092,10.10.10.13:9092</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">all</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">children</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># infra cluster for proxy, monitor, alert, etc..</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">infra</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">10.10.10.10</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">infra_seq</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w"> </span>}<span class="w"> </span>}<span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># single-node kafka dev cluster: combined broker/controller, plaintext</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">kf-meta</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">hosts</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">10.10.10.10</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">kafka_seq</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">vars</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">kafka_cluster</span><span class="p">:</span><span class="w"> </span><span class="l">kf-meta</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">kafka_topics</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- {<span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="nt">quickstart.events ,partitions</span><span class="p">:</span><span class="w"> </span><span class="nt">1 ,replication_factor</span><span class="p">:</span><span class="w"> </span><span class="nt">1 ,config</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">retention.ms</span><span class="p">:</span><span class="w"> </span><span class="m">86400000</span><span class="w"> </span>}<span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># 3-node secure HA demo baseline: dynamic KRaft, TLS/SCRAM/ACL, RF=3/minISR=2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">kf-test</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">hosts</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">10.10.10.11</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">kafka_seq</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">10.10.10.12</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">kafka_seq</span><span class="p">:</span><span class="w"> </span><span class="m">2</span><span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">10.10.10.13</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">kafka_seq</span><span class="p">:</span><span class="w"> </span><span class="m">3</span><span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">vars</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">kafka_cluster</span><span class="p">:</span><span class="w"> </span><span class="l">kf-test</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">kafka_security</span><span class="p">:</span><span class="w"> </span><span class="l">scram</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">kafka_heap_opts</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;-Xms512M -Xmx512M&#39;</span><span class="w"> </span><span class="c"># 2GiB demo nodes cannot safely spare the 1GiB production default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">kafka_users</span><span class="p">:</span><span class="w">               </span><span class="c"># app principal with prefixed topic/group acls</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">test-app</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l">KafkaApp.Test</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">acls</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span>- {<span class="w"> </span><span class="nt">resource</span><span class="p">:</span><span class="w"> </span><span class="nt">topic   ,name</span><span class="p">:</span><span class="w"> </span><span class="nt">&#39;test.&#39;       ,pattern</span><span class="p">:</span><span class="w"> </span><span class="nt">prefixed ,operations</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="l">Read, Write, Describe ] }</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span>- {<span class="w"> </span><span class="nt">resource</span><span class="p">:</span><span class="w"> </span><span class="nt">group   ,name</span><span class="p">:</span><span class="w"> </span><span class="nt">&#39;test.&#39;       ,pattern</span><span class="p">:</span><span class="w"> </span><span class="nt">prefixed ,operations</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="l">Read ] }</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span>- {<span class="w"> </span><span class="nt">resource</span><span class="p">:</span><span class="w"> </span><span class="nt">cluster ,name</span><span class="p">:</span><span class="w"> </span><span class="nt">kafka-cluster ,operations</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="l">Describe, IdempotentWrite ] }</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">kafka_topics</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">test.events</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">partitions</span><span class="p">:</span><span class="w"> </span><span class="m">3</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">replication_factor</span><span class="p">:</span><span class="w"> </span><span class="m">3</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">config</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">min.insync.replicas</span><span class="p">:</span><span class="w"> </span><span class="nt">2 ,cleanup.policy</span><span class="p">:</span><span class="w"> </span><span class="nt">delete ,retention.ms</span><span class="p">:</span><span class="w"> </span><span class="m">604800000</span><span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">vars</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l">v4.5.0                  </span><span class="w"> </span><span class="c"># pigsty version string</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">admin_ip</span><span class="p">:</span><span class="w"> </span><span class="m">10.10.10.10</span><span class="w">             </span><span class="c"># admin node ip address</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">region</span><span class="p">:</span><span class="w"> </span><span class="l">default                  </span><span class="w"> </span><span class="c"># upstream mirror region: default|china|europe</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">infra_portal</span><span class="p">:</span><span class="w">                     </span><span class="c"># infra services exposed via portal</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">home </span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">domain</span><span class="p">:</span><span class="w"> </span><span class="l">i.pigsty }    </span><span class="w"> </span><span class="c"># default domain name</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># kafka &amp; java packages are required in the local repo for the kafka module (if using local repo)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">repo_extra_packages</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="l">kafka-stack ,java-runtime ]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># PASSWORD : https://pigsty.io/docs/setup/security/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">grafana_admin_password</span><span class="p">:</span><span class="w"> </span><span class="l">pigsty</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">grafana_view_password</span><span class="p">:</span><span class="w"> </span><span class="l">DBUser.Viewer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">...</span><span class="w">
</span></span></span></code></pre></div>


--------

## 配置解读

- `kf-meta` 创建 `quickstart.events`，用于单机开发与连通性测试。
- `kf-test` 创建 `test-app` SCRAM 用户、前缀 ACL 与 `test.events` 三副本 Topic。
- 在线安装时由平台映射安装 `kafka-stack` 与 `java-runtime`；若只使用本地仓库，必须先把这两个包组完整纳入仓库。
- 模板中的地址和密码均为演示值，部署前应按实际拓扑与安全要求修改。

更多操作、安全与扩缩容约束参见 [KAFKA 模块](/docs/kafka/)。
