企业官网建设流程全解析

• 云原生
• 运维
• 可观测性

Litmus SDK 是 Litmus 混沌工程体系中面向实验开发者的脚手架工具：它只需一份描述实验属性的 attributes 文件，就能按 chaos 类别自动生成完整的实验代码骨架（含默认的 Pre/Post Chaos Checks），开发者随后填充业务逻辑、构建 go-runner 镜像、打包 charts 并发布到 ChaosHub，即可在集群中运行属于自己的混沌实验。本文以"创建 Pod CPU 压测实验并在目标 Pod 内执行 md5sum 命令"为贯穿案例，完整还原 SDK 使用流程，并结合当前仓库中的实验规范文档与配置示例，深入讲解生成产物的结构与底层原理。

一、Litmus SDK 是什么：为什么需要它

在 Litmus 中，一个可运行的混沌实验并不是一段孤立的脚本，而是一整套需要按约定组织的制品：实验代码（business logic）、辅助任务/utils、chaoslib（混沌注入库）、Kubernetes Job 清单、使用文档等。正如 CHAOS_EXPERIMENT_MATURITY.md 所定义的，一个合格的实验必须"符合标准 litmus 实验结构（business logic、auxiliary tasks/utils、chaoslib）"，并提供 Kubernetes Job 清单来执行实验。

手工搭建这套结构既繁琐又容易出错，而 Litmus SDK 正是为了解决这个问题而设计的。按照 demo/litmus-sdk/litmus-sdk.md 的官方说明，SDK 的核心定位是：

The Litmus SDK provides a simple way to bootstrap your experiment and helps create the aforementioned artifacts in the appropriate directory (i.e., as per the chaos-category) based on an attributes file provided as input by the chart-developer.

即：chart 开发者只需提供一个 attributes 文件，SDK 就会自动在正确的目录（按 chaos 类别划分）下创建实验所需的各类制品，其中包含可直接填充的占位符（placeholders），后续开发者按需填充即可。

二、SDK 的四大核心能力

围绕上述定位，SDK 提供了四项关键能力，这也是使用 SDK 时最能感受到的价值：

1. 按 chaos 类别自动落盘制品

attributes 文件作为输入，SDK 据此判断实验属于哪一类别（如 pods、nodes 等），并将生成的文件自动放置到对应类别目录中，避免开发者手工维护目录结构。

2. 生成带占位符的实验骨架

生成的 scaffolded 文件包含占位符（placeholders），开发者可以随后按需填充。这意味着 SDK 产出的不是"半成品示例"，而是一份结构完整、可继续开发的起点。

3. 默认附带 Pre & Post Chaos Checks

SDK 会自动生成带有默认前后置检查的自定义混沌实验，即AUT（Application Under Test，被测应用）与 Auxiliary Applications（辅助应用）的状态检查。这些检查确保在注入混沌前目标应用处于健康运行状态，并在混沌结束后验证其状态是否恢复，是实验可观测、可判定成败的基础。

4. 复用或新建 chaoslib

如果实验注入方式与现有 chaoslib 匹配，SDK 会直接复用仓库/chaoslib目录中已有的 chaoslib；如果没有现成的可用实现，则会在对应目录下自动创建新的 chaoslib 骨架。这一机制保证了不同实验之间注入逻辑可以共享、沉淀，避免重复造轮子。

三、完整实战流程：创建"Pod CPU 压测 + md5sum 校验"实验

官方演示视频以如下 UseCase 贯穿始终：创建一个 Pod CPU 压测实验，该实验会 exec 进入目标 Pod 并在其中运行md5sum命令。整条链路共 7 个步骤，从克隆代码库开始，一直到在集群中真正跑通实验：

步骤 1：克隆 litmus-go 仓库并进入 contribute/developer-guide 目录

Litmus 的 Go 版实验（litmus-go）独立维护在 litmus-go 仓库中（不在当前 litmus 仓库内），SDK 工具位于其contribute/developer-guide目录下。第一步是克隆该仓库并进入此目录，以便使用 SDK 生成实验代码。

步骤 2：生成实验代码

准备描述实验属性的 attributes 文件，运行 SDK 生成命令，得到一整套按 chaos 类别归类的实验代码骨架。生成的代码中包含占位符，供下一步填充。

步骤 3：添加稳态检查与实验业务逻辑

这是实验开发的核心环节：

• 稳态检查（Steady-State Checks）：即 SDK 默认生成的 Pre/Post Chaos Checks，声明"什么状态才算应用健康"，例如 AUT 与 Auxiliary Applications 的 Pod 状态检查；
• 实验业务逻辑（Business Logic）：实现具体的混沌行为。在本例中，即 exec 进入目标 Pod 并执行md5sum命令，模拟 CPU 压测下文件校验任务的执行。

步骤 4：构建 go-runner 镜像

实验代码编写完成后，将其编译构建为 go-runner 镜像。go-runner是 Litmus 中承载实验二进制的主要运行时镜像，相关文档中大量实验均以litmuschaos/go-runner:latest作为默认实验镜像（参见 experiment-components.md 中的experimentImage说明）。开发者构建的正是这个镜像的自定义版本。

步骤 5：创建 charts 并加入 chaos-charts 仓库

实验运行不仅需要代码，还需要实验清单（ChaosExperiment/ChaosEngine YAML）、RBAC 权限清单和使用文档，这些被打包为 charts。charts 需要被提交到 chaos-charts 仓库（即 ChaosHub 的图表源），以便通过 ChaosHub 分发与安装。

步骤 6：创建新的 ChaosHub

在 Litmus ChaosCenter 中创建（或连接）一个 ChaosHub，将步骤 5 的 charts 作为该 Hub 的图表来源。此后，用户便可以从 ChaosHub 中浏览、选择并安装你发布的实验。

步骤 7：运行实验

通过 ChaosEngine 指定目标应用与实验参数，在目标命名空间创建混沌引擎，由 Litmus Chaos Operator 调度执行实验，最终通过 ChaosResult 查看实验判定结果（Pass/Fail）。

四、深入解读实验代码骨架：business logic、utils 与 chaoslib

SDK 生成的代码骨架遵循 Litmus 标准实验结构，这一点可以从 CHAOS_EXPERIMENT_MATURITY.md 中印证——任何成熟度级别的实验都必须"Conforms to the standard litmus experiment structure (business logic, auxiliary tasks/utils, chaoslib)"。三者职责如下：

SDK 的"复用或新建 chaoslib"逻辑正落在这层：若/chaoslib中已有可复用实现则直接引用，否则自动创建新的 chaoslib 骨架。

五、默认的 Pre/Post Chaos Checks 是如何工作的

SDK 默认生成的 AUT 与 Auxiliary Applications 状态检查，是 Litmus 实验稳态校验体系的一部分。其执行流程与结果表达可以从 ChaosResult 的规范中看到：

在 status-specification.md 中，ChaosResult 的.status.experimentStatus记录了实验的最终判定：

• verdict：实验结论，取值范围Awaited / Pass / Fail / Stopped，实验进行中为Awaited，结束时按检查结果判定为Pass或Fail；
• phase：实验当前阶段，取值范围Awaited / Running / Completed / Aborted；
• failStep：实验失败的具体步骤，便于快速定位问题；
• probesuccesspercentage：探针（probe）成功百分比，取值范围 1～100，为成功检查数占总探针数的比例。

也就是说，SDK 生成的默认检查（AUT 与 Auxiliary 状态检查）运行后，其成败会汇总为probesuccesspercentage并最终决定verdict。一个典型的执行结果（摘自上述文档）形如：

Status: Experiment Status: Fail Step: N/A Phase: Completed Probe Success Percentage: 100 Verdict: Pass History: Failed Runs: 1 Passed Runs: 1 Stopped Runs: 0 Targets: Chaos Status: targeted Kind: deployment Name: hello

verdict: Pass意味着 AUT 与 Auxiliary 应用在混沌注入前后均满足稳态条件，实验按预期完成。

六、让自定义实验可配置：ChaosExperiment 与 ChaosEngine 关键参数

SDK 生成骨架后，实验的可配置性由两个 CRD 共同承担。理解它们，才能真正"填充占位符"填得专业。

6.1 ChaosExperiment：定义实验本身

ChaosExperiment 描述实验的定义，其spec.definition下包含镜像、入口与权限等关键字段。依据 component-specification.md，核心字段如下：

一份典型的 ChaosExperiment 定义（pod-delete 示例，取自 env.yaml）关键片段如下：

apiVersion: litmuschaos.io/v1alpha1 kind: ChaosExperiment metadata: name: pod-delete spec: definition: scope: Namespaced image: "litmuschaos/go-runner:latest" imagePullPolicy: Always args: - -c - ./experiments -name pod-delete command: - /bin/bash env: - name: TOTAL_CHAOS_DURATION value: '15' - name: RAMP_TIME value: '' - name: FORCE value: 'true' - name: CHAOS_INTERVAL value: '5' - name: PODS_AFFECTED_PERC value: '' - name: LIB value: 'litmus' - name: SEQUENCE value: 'parallel'

注意args的写法：./experiments -name pod-delete正是 litmus-go 单二进制多实验模式的核心用法，SDK 生成的代码也应遵循此约定。

6.2 ChaosEngine：定义运行时的实验参数

ChaosEngine 描述"对哪个应用、注入什么实验、用什么参数"，其.spec.experiments[].spec.components下的env可覆盖 ChaosExperiment 中定义的默认值。依据 experiment-tunable-specification.md，tunable 本质上是以环境变量形式传给实验 Pod 的参数数组。

SDK 生成实验后，配套发布的文档中应列出该实验的mandatory（必填）与 optional（可选）env，开发者据此在 ChaosEngine 中覆盖。以本文案例（Pod CPU 压测）为例，结合 pod-cpu-hog.md，常用 tunable 包括：

同时，common-tunables-for-all-experiments.md 明确了所有实验通用的公共 tunable，SDK 生成的默认骨架通常也会包含：

• TOTAL_CHAOS_DURATION：混沌持续时间（秒）；
• RAMP_TIME：注入前后等待期（秒）；
• SEQUENCE：多目标执行顺序，默认parallel；
• LIB：使用的混沌库名称；
• INSTANCE_ID：用户自定义字符串，作为后缀追加在 ChaosResult 名称中（例如04-05-2020-9-00），用于区分多次运行；
• LIB_IMAGE：helper Pod 使用的镜像。

一个带参数覆盖的 ChaosEngine 示例（对应本文案例）形如：

apiVersion: litmuschaos.io/v1alpha1 kind: ChaosEngine metadata: name: engine-nginx spec: engineState: "active" annotationCheck: "false" appinfo: appns: "default" applabel: "app=nginx" appkind: "deployment" chaosServiceAccount: pod-cpu-hog-sa experiments: - name: pod-cpu-hog spec: components: env: - name: CPU_CORES value: '1' - name: TOTAL_CHAOS_DURATION value: '60'

6.3 更细粒度的组件配置：experiment components 与 runner components

除了env，ChaosEngine 还在.spec.experiments[].spec.components下支持对实验 Pod 的细粒度定制，SDK 开发者应熟悉这些字段以完善实验文档。依据 experiment-components.md：

对应的，ChaosEngine 的.spec.components.runner可定制 chaos-runner Pod（runner-components.md），包括runner.image（默认可通过 operator 环境变量CHAOS_RUNNER_IMAGE全局指定）、runner.imagePullPolicy（默认IfNotPresent）、runner.args/runner.command（自定义调试 runner）、runner.configMaps/runner.secrets、runner.nodeSelector/runner.tolerations/runner.resources等。

七、运行实验与验证结果

实验创建完成后，以kubectl apply -f engine.yaml方式创建 ChaosEngine（或通过 ChaosCenter/工作流编排），Litmus Chaos Operator 会创建 chaos-runner Pod；runner 再为每个实验创建一个实验 Pod（Job）执行实验业务逻辑，并管理其生命周期。执行完成后，通过以下命令查看结果：

kubectl get chaosresult -n <namespace> kubectl describe chaosresult <engine-name>-<experiment-name> -n <namespace>

依据 status-specification.md，重点观察：

• experimentStatus.verdict：Pass表示前后置检查均通过、实验按预期执行；Fail表示稳态条件被破坏或实验异常；
• experimentStatus.failStep：实验失败的具体步骤，用于快速排障；
• experimentStatus.probesuccesspercentage：探针成功百分比；
• history：累计的 Passed/Failed/Stopped 运行次数，以及目标应用的name、kind、chaosStatus（targeted / injected / reverted）。

对于本文案例而言，若实验在目标 Pod 内执行md5sum的同时施加 CPU 压测，且前后 AUT 状态检查均通过，则 ChaosResult 会呈现verdict: Pass，证明应用在 CPU 资源被争抢的场景下仍能保持稳态。

八、从"能跑"到"成熟"：对齐 Litmus 实验成熟度准则

SDK 能快速产出可运行的实验，但一个高质量的实验还需要满足 Litmus 的成熟度分级标准。依据 CHAOS_EXPERIMENT_MATURITY.md：

• Alpha 级：能在任一标准 Kubernetes 平台（如 GKE、EKS、DOKS、vSphere）注入预期混沌；有明确的进入（初始状态）与退出（弹性）判定标准；符合标准实验结构（business logic、auxiliary utils、chaoslib）；提供 Kubernetes Job 清单；附带包含前置条件、tunables 与执行步骤的使用文档。
• Beta 级：能成功逆转混沌、集群恢复健康；明确区分应用级/基础设施级混沌；无论成败均无残留（清理执行期间创建的资源）；具备足够调试日志；优先复用基础 chaoslib 与公共 utils；至少支持两个标准 Kubernetes 平台；附带演示视频；能通过 ChaosExperiment CR 由 Operator 执行；对实验使用的清单/资源规格做模板化。
• GA 级：支持全部 4 个标准 Kubernetes 平台；ChaosResult CR 中包含足够的实验关键步骤状态与结果信息。

SDK 生成的默认前后置检查、标准目录结构与 chaoslib 复用机制，恰好覆盖了 Alpha/Beta 级的大部分要求——这正体现了 SDK"引导开发者写出规范实验"的设计意图。SDK 生成代码后，建议对照该准则补齐文档、日志、清理与跨平台验证，逐步将实验推向成熟。

九、小结

Litmus SDK 把"开发一个规范混沌实验"的门槛从手工搭建整套制品结构，降低为"提供 attributes 文件 + 填充占位符 + 构建镜像 + 发布 charts"。通过本文的 7 步流程，开发者可以基于 SDK 快速生成带默认 Pre/Post Chaos Checks 的实验骨架，结合 ChaosExperiment/ChaosEngine 的配置规范（镜像、入口、tunables、组件挂载与调度控制）打磨出可配置、可观测的自定义实验，并通过 ChaosResult 验证结果，最终遵循实验成熟度准则发布到 ChaosHub 供团队使用。

进一步的参考资料，均可在当前仓库中按需查阅：

• Litmus SDK 官方说明
• 实验成熟度准则
• ChaosExperiment 组件规范
• ChaosExperiment tunable 规范
• ChaosEngine 实验组件配置
• ChaosEngine runner 组件配置
• ChaosResult 状态规范
• 公共 tunable 说明
• pod-cpu-hog 实验文档（本文案例对应实验）

• 云原生
• 运维
• 可观测性