基本框架

docs/04-13-nodejs-HPA.md

@@ -0,0 +1,53 @@
+# 04-13-nodejs-HPA
+
+> 为 `nodejs-demo` 配置 **HorizontalPodAutoscaler**，按 CPU/内存等指标在 `minReplicas`～`maxReplicas` 间自动伸缩。
+
+## 前置条件
+
+- 集群已安装 **metrics-server**（K3s 常默认启用；`kubectl top nodes` 可用即基本就绪）。
+- Deployment 已配置 **`resources.requests`**（CPU 指标 HPA 依赖 requests），见 [`04-05-nodejs-资源请求与限制.md`](04-05-nodejs-资源请求与限制.md)。
+- 建议已配置 **readinessProbe**（[`04-06-nodejs-探针与健康检查.md`](04-06-nodejs-探针与健康检查.md)），避免扩容出未就绪 Pod。
+
+## 清单路径（唯一真源）
+
+| 本篇完整清单（含 Deployment/Service/Ingress/PVC/CM + **HPA**） | [`ansible/files/nodejs-demo/04-13-nodejs-demo.yaml`](../ansible/files/nodejs-demo/04-13-nodejs-demo.yaml) |
+| 应用 | `kubectl apply -f ansible/files/nodejs-demo/04-13-nodejs-demo.yaml`（若用 `04-12`，需先有 TLS Secret） |
+
+## 场景说明（白话）
+
+- **HPA**：根据 CPU/内存等指标，**自动加减 Pod 个数**（在 `minReplicas`～`maxReplicas` 之间）。
+- **为什么要配 requests**：否则集群算不出「利用率百分比」，CPU 型 HPA 往往**不工作**。
+
+### 相对 `04-12` 的变更（原文 → 新文）
+
+| 位置 | 原文（`04-12`） | 新文（`04-13`） |
+|------|-----------------|-----------------|
+| 资源 | 无 HPA | 新增 `HorizontalPodAutoscaler` `nodejs-demo`，CPU 目标利用率 50%，`minReplicas: 1`，`maxReplicas: 5` |
+
+## 部署与验证
+
+```bash
+kubectl apply -f ansible/files/nodejs-demo/04-13-nodejs-demo.yaml
+kubectl get hpa -n default
+kubectl describe hpa nodejs-demo -n default
+```
+
+加压 Pod（例如在集群内对 Service 做短时压测）后观察 **REPLICAS** 是否上升；降压后是否回落（受 `--default-downscale-stabilization` 等控制器参数影响，可能有延迟）。
+
+## 删除 HPA
+
+```bash
+kubectl delete hpa nodejs-demo -n default
+```
+
+## 失败排查
+
+- **unknown / missing metrics**：metrics-server 未运行；Pod 无 `resources.requests`。
+- **不扩容**：当前利用率未达阈值；或 `maxReplicas` 已达上限。
+- **频繁抖动**：调高目标利用率或配置 behavior（`scaleDown`/`scaleUp` stabilizationWindow）。
+- `06-01-k3s-networkpolicy-故障排查.md`
+
+## 相关文档
+
+- [`04-11-nodejs-副本与滚动发布.md`](04-11-nodejs-副本与滚动发布.md)
+- [`05-05-prometheus与grafana.md`](05-05-prometheus与grafana.md)（自定义 metrics 进阶，本文不展开）