---
url: /courses/kubernetes-cluster/13-helm-delivery/index.md
---
# 第十三节 Helm 平台交付与重建验收

::: tip 本课目标
为虚构业务“云帆商城”使用锁定版本的 Helm Chart 交付 MariaDB 主从架构；完成渲染审查、安装、升级、回滚与最终重建验收，形成不含真实凭据的可复现交付包。
:::

## 13.1 接单：从“命令跑通”升级为“版本可复现”

Helm 用 Chart 模板和 values 生成 Kubernetes 清单，并把一次安装或升级记录为 release revision。

本课锁定：

```text
Chart 仓库：Bitnami
Chart：mariadb
Chart 版本：26.2.0
目标架构：1 个 primary + 1 个 secondary
```

版本号是交付输入的一部分。只写 `helm install bitnami/mariadb` 会随仓库更新得到不同结果，不能满足复现要求。

## 13.2 交付目录

```text
yunfan-platform/
├── cluster/
│   └── kind-config.yaml
├── manifests/
│   ├── 04-governance/
│   ├── 06-deployment/
│   ├── 08-service/
│   ├── 09-probes/
│   ├── 10-storage/
│   ├── 11-scheduling/
│   └── 12-hpa/
├── helm/
│   └── mariadb-values.yaml
├── evidence/
│   ├── release-history.txt
│   ├── workload-status.txt
│   └── rebuild-checklist.md
└── README.md
```

Secret 实例、真实口令、kubeconfig 和终端历史不能进入交付包。

## 13.3 values：声明架构与资源边界

values 文件名是 **mariadb-values.yaml**。Chart 26.2.0 的 `existingSecret` 需要 Secret 包含 `mariadb-root-password`、`mariadb-replication-password` 和 `mariadb-password`。

先核对本地容量：

```bash
kubectl get nodes
kubectl describe nodes | sed -n '/Allocatable:/,/Events:/p'
kubectl get storageclass
```

若内存不足，先记录容量风险并调低实验资源，不能删除 requests 来掩盖调度问题。

## 13.4 凭据与安装：先渲染，再改变集群

先把密码读入当前终端，不回显、不写入 values：

```bash
printf 'MariaDB root password: '
IFS= read -rs YUNFAN_ROOT_PASSWORD
printf '\nMariaDB app password: '
IFS= read -rs YUNFAN_APP_PASSWORD
printf '\nMariaDB replication password: '
IFS= read -rs YUNFAN_REPL_PASSWORD
printf '\n'

kubectl create namespace yunfan-db
kubectl create secret generic yunfan-db-auth \
  -n yunfan-db \
  --from-literal=mariadb-root-password="$YUNFAN_ROOT_PASSWORD" \
  --from-literal=mariadb-password="$YUNFAN_APP_PASSWORD" \
  --from-literal=mariadb-replication-password="$YUNFAN_REPL_PASSWORD" \
  --dry-run=client \
  -o yaml | kubectl apply -f -

unset YUNFAN_ROOT_PASSWORD YUNFAN_APP_PASSWORD YUNFAN_REPL_PASSWORD
```

::: warning 凭据边界
不要截图密码输入，不要执行 `kubectl get secret -o yaml` 留证，也不要把 shell 历史或 Secret 导出文件放进交付包。
:::

Chart 版本参数是 **--version**。

`helm template` 暴露渲染结果，server-side dry-run 检查 API 接受度，`--atomic` 让失败安装自动回滚已创建资源。三者解决的问题不同。

## 13.5 验收主从、服务与存储

```bash
helm list -n yunfan-db
helm status yunfan-db -n yunfan-db
helm get values yunfan-db -n yunfan-db
helm history yunfan-db -n yunfan-db
kubectl get statefulset,pod,service,pvc -n yunfan-db -o wide
kubectl get events -n yunfan-db \
  --sort-by=.metadata.creationTimestamp
helm test yunfan-db -n yunfan-db --logs
```

验收必须同时证明：

1. release 为 `deployed`，Chart 版本是 26.2.0。
2. primary 与 secondary Pod Ready。
3. 两侧 PVC 均为 Bound。
4. 服务名称、端口和角色与渲染结果一致。
5. 测试 Pod 成功，事件中无持续性拉取、调度或挂载故障。

## 13.6 升级与回滚

使用一个低风险、可观察的 Service 会话保持变更：

```bash
helm upgrade yunfan-db bitnami/mariadb \
  --namespace yunfan-db \
  --version 26.2.0 \
  -f helm/mariadb-values.yaml \
  --reuse-values \
  --set primary.service.sessionAffinity=ClientIP \
  --atomic \
  --wait \
  --timeout 10m

helm history yunfan-db -n yunfan-db
kubectl get service yunfan-db -n yunfan-db \
  -o jsonpath='{.spec.sessionAffinity}{"\n"}'
```

确认 revision 号后回滚到上一版本：

```bash
helm rollback yunfan-db 1 \
  --namespace yunfan-db \
  --wait \
  --timeout 10m
helm history yunfan-db -n yunfan-db
kubectl get service yunfan-db -n yunfan-db \
  -o jsonpath='{.spec.sessionAffinity}{"\n"}'
```

实际环境若 revision 1 不是目标版本，应以 `helm history` 的结果替换，不能机械执行。

## 13.7 最终重建验收

完整重建顺序：

```text
前置检查
  → kind 集群配置
  → 命名空间与治理规则
  → Web 工作负载、Service 与探针
  → 存储、配置与 Secret
  → 调度与 HPA 前置组件
  → Helm MariaDB release
  → 自动检查与人工证据
```

重建清单至少记录：

| 检查点 | 命令或证据 | 通过标准 |
| --- | --- | --- |
| 集群 | `kubectl get nodes` | 预期节点 Ready |
| Web | rollout、Service、EndpointSlice | 副本就绪且端点存在 |
| 健康 | 探针故障演练 | 摘流量与重启动作正确 |
| 数据 | PVC 重建实验 | 数据跨 Pod 保留 |
| 调度 | Pod 位置与事件 | 约束结果可解释 |
| 弹性 | HPA 时间线 | 指标变化触发扩缩容 |
| 数据库 | Helm 状态、Pod、PVC、test | release 完整可用 |
| 安全 | 文件扫描与人工复核 | 无真实凭据、kubeconfig |

删除集群会清除本地实验数据。只有在已确认没有需要保留的数据、交付证据已复制且目标集群名称确实为 `yunfan` 时，才执行：

```bash
kind get clusters
kind delete cluster --name yunfan
```

然后完全按 README 重建并计时。成功标准不是“记得怎么做”，而是另一台满足前置条件的电脑可以按文件和说明得到同样的验收结果。

## 13.8 最终交付

1. 锁定版本的 values、集群配置和全部声明式清单。
2. Helm 安装、升级、回滚与 test 证据。
3. 从空集群开始的重建步骤、耗时和异常记录。
4. 安全检查、限制说明和下一步生产化建议。
5. 一段五分钟个人答辩：架构、关键取舍、故障证据和改进方向。

{{reflection-checkpoint:helm-delivery-check}}

## 本章小测

{{assessment:helm-delivery}}

## 本章小结

* Chart 版本、values 和外部 Secret 共同构成可复现输入。
* 渲染、server-side dry-run、原子安装、验收和回滚形成发布闭环。
* Helm revision 记录 release 变更，但不能替代数据库备份。
* 最终交付以“从空环境可重建、故障可解释、变更可回退、凭据不泄露”为标准。