主题
附录 速查表与检查清单
本附录是全书的"口袋卡片"：命令速查、指标阈值、配置参数、内核参数、端口清单、容量公式、学习路线图。
使用建议：打印一份放在工位，on-call 时对照执行；所有命令在真实环境执行前，请先在测试集群验证路径与版本差异（不同 RKE2 版本的证书/二进制路径可能不同）。
A.1 RKE2 大规模运维命令速查
A.1.1 etcd 操作
bash
# ---- 环境变量（RKE2 自带 etcdctl 路径，按实际版本调整）----
export ETCDCTL_API=3
ETCDCTL="/var/lib/rancher/rke2/bin/etcdctl"
ETCD_ARGS="--cacert /var/lib/rancher/rke2/server/tls/etcd/server-ca.crt \
--cert /var/lib/rancher/rke2/server/tls/etcd/server-client.crt \
--key /var/lib/rancher/rke2/server/tls/etcd/server-client.key \
--endpoints https://127.0.0.1:2379"
# 成员与健康
$ETCDCTL $ETCD_ARGS member list -w table
$ETCDCTL $ETCD_ARGS endpoint status -w table # 重点看 DB SIZE / DB SIZE IN USE / RAFT INDEX
$ETCDCTL $ETCD_ARGS endpoint health --cluster -w table
$ETCDCTL $ETCD_ARGS endpoint status --cluster -w json | jq '.[].Status.header.revision'
# 快照（手动）
$ETCDCTL $ETCD_ARGS snapshot save /backup/etcd-snapshot-$(date +%Y%m%d%H%M).db
$ETCDCTL snapshot status /backup/etcd-snapshot-*.db -w table
# RKE2 自带快照管理（推荐）
rke2 etcd-snapshot save --name manual-$(date +%Y%m%d%H%M)
rke2 etcd-snapshot list
# 从快照恢复（单节点急救）
rke2 server --cluster-reset --cluster-reset-restore-path=/var/lib/rancher/rke2/server/db/snapshots/<快照名>
# compact + defrag（逐台执行，follower 先、leader 后）
REV=$($ETCDCTL $ETCD_ARGS endpoint status --write-out="json" | jq '.[0].Status.header.revision')
$ETCDCTL $ETCD_ARGS compact $REV
$ETCDCTL $ETCD_ARGS --endpoints https://<成员IP>:2379 defrag
# 移除失效成员（quorum 恢复场景，详见 k8s-issues/rke2-disaster-recovery-control-plane-quorum-loss.md）
$ETCDCTL $ETCD_ARGS member remove <MEMBER_ID>
# 强制单节点恢复：编辑 /var/lib/rancher/rke2/server/db/etcd/config 追加 force-new-cluster: trueA.1.2 节点批量操作
bash
# 批量查看状态/分组统计
kubectl get nodes -o wide | awk '{print $2}' | sort | uniq -c
kubectl get nodes --no-headers | grep NotReady | awk '{print $1}' > /tmp/notready.txt
# 批量 cordon / drain（务必分批！）
for n in $(cat /tmp/batch1.txt); do kubectl cordon $n; done
for n in $(cat /tmp/batch1.txt); do
kubectl drain $n --ignore-daemonsets --delete-emptydir-data --grace-period=120 --timeout=10m
done
# 批量 uncordon
for n in $(cat /tmp/batch1.txt); do kubectl uncordon $n; done
# 批量打标签/污点
kubectl label nodes -l node-pool=gpu disk=ssd --overwrite
kubectl taint nodes -l node-role.kubernetes.io/control-plane= node-role.kubernetes.io/control-plane=:NoSchedule --overwrite
# 批量远程执行（配合 ansible/pdsh）
ansible agents -m shell -a "systemctl restart rke2-agent" --forks=20
ansible agents -m shell -a "cat /proc/sys/net/netfilter/nf_conntrack_count" --forks=50 | sort
# 按条件导出节点（证书巡检示例）
ansible all -m shell -a "openssl x509 -in /var/lib/rancher/rke2/agent/client-kubelet.crt -noout -enddate" --forks=50A.1.3 升级相关
bash
# 查看当前版本与可用升级计划
rke2 --version
kubectl get plans -n system-upgrade
kubectl get jobs -n system-upgrade
# system-upgrade-controller 波次控制
kubectl patch plan rke2-agent -n system-upgrade --type=merge -p '{"spec":{"concurrency":10}}'
# 手工升级单节点（金丝雀）
curl -sfL https://get.rke2.io | INSTALL_RKE2_VERSION=v1.30.x+rke2r1 sh -
systemctl restart rke2-agent # agent 节点
systemctl restart rke2-server # control-plane 节点（逐台！）
# 升级后验证
kubectl get nodes -o wide | awk '{print $5}' | sort | uniq -c
rke2 etcd-snapshot save --name pre-upgrade-$(date +%F) # 升级前必做A.1.4 证书相关
bash
# 查看各类证书有效期
openssl x509 -in /var/lib/rancher/rke2/server/tls/server-ca.crt -noout -dates
openssl x509 -in /var/lib/rancher/rke2/agent/client-kubelet.crt -noout -dates
for f in /var/lib/rancher/rke2/server/tls/etcd/*.crt; do
echo "== $f"; openssl x509 -in $f -noout -enddate
done
# RKE2 证书轮换（control-plane）
rke2 certificate rotate
systemctl restart rke2-server
# CSR 批量批准（轮换积压时）
kubectl get csr -o name | xargs -I{} kubectl certificate approve {}
# 查看 Pending CSR
kubectl get csr --sort-by=.metadata.creationTimestamp | grep PendingA.1.5 性能诊断（pprof 与现场取证）
bash
# apiserver pprof（需 admin kubeconfig，端口 6443）
go tool pprof --seconds 30 https://localhost:6443/debug/pprof/profile # CPU
go tool pprof --inuse_space https://localhost:6443/debug/pprof/heap # 内存
curl -ks https://localhost:6443/debug/pprof/goroutine?debug=2 > goroutine.txt
# etcd pprof（端口 2381 metrics / 通过 --enable-pprof）
curl -s http://127.0.0.1:2381/debug/pprof/heap > etcd-heap.pb.gz
# kubelet 指标与 pprof（节点本地 10250）
curl -ks --cert /var/lib/rancher/rke2/agent/client-kubelet.crt \
--key /var/lib/rancher/rke2/agent/client-kubelet.key \
https://127.0.0.1:10250/metrics | head -50
# containerd / crictl 现场
crictl ps -a | wc -l
crictl images | wc -l
crictl stats | sort -k3 -h | tail # 内存 Top 容器
ctr -n k8s.io containers ls | wc -l
# 节点级取证三板斧
dmesg -T | grep -iE "oom|conntrack|xfs|ext4" | tail -30
ss -s # socket/连接统计
sar -n DEV 1 5 # 网卡吞吐（sysstat 包）A.2 关键指标速查表（指标 → 含义 → 告警阈值建议）
A.2.1 kube-apiserver
| 指标 | 含义 | 告警阈值建议 |
|---|---|---|
apiserver_current_inflight_requests | 当前 inflight 请求数（readOnly/mutating） | ≥ 上限 80% 持续 5min |
apiserver_request_duration_seconds_bucket | 请求延迟分布 | P99(verb=LIST) > 5s；P99(总体) > 1s |
apiserver_request_total{code=~"5.."} | 5xx 错误率 | > 1% 持续 5min |
apiserver_dropped_requests_total | 被丢弃请求 | rate > 0 持续 5min |
apiserver_storage_objects | 各资源对象数量 | 环比突增 50%（event 风暴侦测） |
apiserver_request_total{verb="LIST"} | LIST 请求速率与来源 | 无 selector 全量 LIST 出现即告警 |
apiserver_flowcontrol_current_executing_requests | APF 执行中请求 | 持续顶满某 PriorityLevel |
process_resident_memory_bytes{job="apiserver"} | apiserver 内存 | > 节点内存 60% 或环比突增 |
etcd_request_duration_seconds_bucket(apiserver 视角) | apiserver→etcd 延迟 | P99 > 500ms |
A.2.2 etcd
| 指标 | 含义 | 告警阈值建议 |
|---|---|---|
etcd_mvcc_db_total_size_in_bytes | DB 物理大小 | / quota > 80% |
etcd_mvcc_db_total_size_in_use_in_bytes | DB 逻辑在用大小 | 与物理大小差值（碎片率）> 50% |
etcd_server_quota_backend_bytes | 配额 | 基线参考，用于算水位 |
etcd_disk_backend_commit_duration_seconds_bucket | 后端提交延迟 | P99 > 250ms（趋势恶化也告警） |
etcd_disk_wal_fsync_duration_seconds_bucket | WAL 刷盘延迟 | P99 > 100ms（查磁盘） |
etcd_server_leader_changes_seen_total | leader 切换次数 | > 3 次/小时 |
etcd_server_has_leader | 是否有 leader | = 0 立即 Pager |
etcd_network_peer_round_trip_time_seconds_bucket | peer 间 RTT | P99 > 100ms |
etcd_server_proposals_failed_total | 提案失败数 | rate > 0 持续 10min |
etcd_mvcc_put_total / etcd_mvcc_range_total | 读写 QPS | 基线偏离 ±50% |
A.2.3 kubelet / 节点
| 指标 | 含义 | 告警阈值建议 |
|---|---|---|
kubelet_node_config_error | 节点配置错误 | = 1 |
kubelet_running_pods | 运行中 Pod 数 | 接近单节点上限 80% |
kubelet_runtime_operations_duration_seconds_bucket | 运行时操作延迟 | P99 > 2s |
kubelet_pleg_relist_duration_seconds_bucket | PLEG relist 延迟 | P99 > 1s（kubelet 忙） |
kubelet_certificate_manager_client_ttl_seconds | client 证书剩余有效期 | < 30 天 |
node_nf_conntrack_entries / ..._limit | conntrack 水位 | > 80% |
node_filefd_allocated / node_filefd_maximum | FD 水位 | > 80% |
node_filesystem_avail_bytes | 磁盘可用 | < 15%（含 imagefs/varlog） |
node_memory_MemAvailable_bytes | 可用内存 | < 10% |
container_cpu_cfs_throttled_seconds_total | CPU 节流 | 核心应用 rate 持续 > 0.1 |
A.2.4 kube-scheduler
| 指标 | 含义 | 告警阈值建议 |
|---|---|---|
scheduler_pending_pods | 待调度 Pod 数（unschedulable/backoff） | > 100 持续 10min |
scheduler_pod_scheduling_attempts_total | 调度尝试速率 | 环比突增（升级 storm 侦测） |
scheduler_scheduling_attempt_duration_seconds_bucket | 调度延迟 | P99 > 1s |
scheduler_unschedulable_pods | 不可调度 Pod 数 | > 0 持续 30min（查资源碎片） |
scheduler_framework_extension_point_duration_seconds_bucket | 插件耗时 | 单插件 P99 > 100ms（查自研插件） |
A.3 关键配置参数速查表（参数 → 作用 → 大规模推荐值）
A.3.1 /etc/rancher/rke2/config.yaml 顶层
| 参数 | 作用 | 大规模推荐值 |
|---|---|---|
cluster-cidr / service-cidr | Pod/Service 网段 | 按 3 倍余量规划，如 10.12.0.0/16 |
system-default-registry | 默认镜像仓库 | 指向私有 Harbor/代理缓存 |
etcd-snapshot-schedule-cron | etcd 自动快照 | "0 */6 * * *"（每 6 小时） |
etcd-snapshot-retention | 快照保留份数 | 5 以上，配合异地备份 |
tls-san | apiserver 证书 SAN | 含 VIP/域名/全部 control-plane IP |
disable | 禁用内置组件 | 按需禁用 rke2-ingress-nginx 等自替代组件 |
kube-proxy-arg | kube-proxy 参数 | ["proxy-mode=ipvs"]（Service > 5000 强制） |
A.3.2 kubelet-arg
| 参数 | 作用 | 大规模推荐值 |
|---|---|---|
max-pods | 单节点 Pod 上限 | 按节点规格 110~250，显式设置勿用默认 |
image-gc-high-threshold / image-gc-low-threshold | 镜像 GC 水位 | 90 / 80（大磁盘 GPU 节点可更高） |
rotate-certificates / rotate-server-certificates | 证书自动轮换 | true / true（严禁关闭！） |
serialize-image-pulls | 串行拉镜像 | false（并发拉取，配合 registry 容量） |
registry-qps / registry-burst | 拉镜像限流 | 10 / 20（惊群防护，预热场景可调高） |
kube-api-qps / kube-api-burst | kubelet→apiserver QPS | 大节点 50 / 100 |
node-status-update-frequency | 心跳频率 | 默认 10s；超大集群可 20s 降 apiserver 压力 |
eviction-hard | 硬驱逐阈值 | memory.available<500Mi,nodefs.available<10% |
system-reserved / kube-reserved | 资源预留 | 按节点规格预留 5%~10%，必配 |
cluster-dns | 集群 DNS | 启用 NodeLocal 后指向 169.254.20.10 |
A.3.3 kube-apiserver-arg
| 参数 | 作用 | 大规模推荐值 |
|---|---|---|
max-requests-inflight | 非变更类 inflight 上限 | 800（默认 400） |
max-mutating-requests-inflight | 变更类 inflight 上限 | 400（默认 200） |
enable-priority-and-fairness | APF 开关 | true（必开） |
event-ttl | Event 保留时长 | 30m（配合 event 导出系统） |
audit-log-mode | 审计写模式 | batch（严禁 blocking） |
audit-log-maxsize / -maxbackup / -maxage | 审计轮转 | 200 / 10 / 7 |
audit-policy-file | 审计策略 | 分级策略：读记 Metadata，写记 Request |
enable-admission-plugins | 准入插件链 | 含 PodSecurity、ResourceQuota、LimitRanger |
encryption-provider-config | secrets 静态加密 | 生产必配（aescbc/kms） |
watch-cache-sizes | watch 缓存大小 | 大对象资源按需调大，如 pods#2000 |
A.3.4 etcd 参数（etcd-arg）
| 参数 | 作用 | 大规模推荐值 |
|---|---|---|
quota-backend-bytes | DB 配额 | 8589934592（8GB），上限勿超 16GB |
heartbeat-interval | 心跳间隔(ms) | 同机房 100；跨机房 500 |
election-timeout | 选举超时(ms) | 保持心跳 10 倍：1000 / 5000 |
auto-compaction-mode / auto-compaction-retention | 自动压缩 | periodic / 8h（RKE2 默认已开） |
snapshot-count | 触发快照的提案数 | 默认 10000；高写入集群可降至 5000 |
max-request-bytes | 单请求大小上限 | 默认 1.5MB；大 ConfigMap 场景 ≤ 10MB |
A.4 内核参数速查表（参数 → 作用 → 推荐值）
写入
/etc/sysctl.d/90-rke2-large-scale.conf后sysctl --system生效；全部参数应纳入节点基线并监控水位（见 A.2.3）。
| 参数 | 作用 | 推荐值（大规模） | 默认值的坑 |
|---|---|---|---|
net.netfilter.nf_conntrack_max | conntrack 表上限 | 4194304 | 默认 26 万，高 QPS 节点几天打满 |
net.netfilter.nf_conntrack_tcp_timeout_established | ESTABLISHED 连接老化 | 600（秒） | 默认 5 天，僵尸连接占表 |
net.netfilter.nf_conntrack_udp_timeout / _stream | UDP 老化时间 | 60 / 180 | DNS 大流量下必须收紧 |
kernel.pid_max | 系统最大 PID | 4194304 | 默认 32768，高密度节点不够 |
fs.file-max | 系统级 FD 上限 | 20971520 | 配合 systemd LimitNOFILE |
fs.nr_open | 单进程 FD 上限 | 20971520 | 默认 1048576，大型应用不够 |
fs.inotify.max_user_watches | inotify 监控数 | 1048576 | 日志采集 agent 刚需 |
fs.inotify.max_user_instances | inotify 实例数 | 8192 | 同上 |
vm.max_map_count | 进程内存映射数 | 262144 | ES/存储类应用刚需 |
net.core.somaxconn | listen backlog | 32768 | 高并发接入层 |
net.ipv4.tcp_max_syn_backlog | SYN 队列 | 32768 | 防 SYN 突发丢包 |
net.ipv4.ip_local_port_range | 临时端口范围 | 1024 65535 | 大量出向连接节点 |
net.ipv4.tcp_tw_reuse | TIME_WAIT 复用 | 1（仅出向为主节点） | 谨慎评估 NAT 场景 |
net.ipv4.neigh.default.gc_thresh3 / 2 / 1 | ARP 表 GC 阈值 | 81920 / 32768 / 4096 | 大二层网络 ARP 表溢出 |
net.core.rmem_max / wmem_max | socket 缓冲上限 | 134217728 | 大带宽节点 |
vm.swappiness | swap 倾向 | 1（K8s 要求关 swap） | RKE2 默认要求 swap off |
vm.overcommit_memory | 内存超卖策略 | 1 | 防 fork 失败误报 |
kernel.panic / kernel.panic_on_oops | 内核崩溃行为 | 10 / 1 | 配合自动重启自愈 |
systemd 配套（/etc/systemd/system/rke2-agent.service.d/override.conf）：
ini
[Service]
LimitNOFILE=1048576
TasksMax=infinityA.5 端口与协议清单（RKE2 全组件，防火墙放行用）
A.5.1 control-plane 节点
| 端口 | 协议 | 组件/用途 | 放行来源 |
|---|---|---|---|
| 6443 | TCP | kube-apiserver | 全部节点、运维跳板机、LB |
| 9345 | TCP | RKE2 supervisor API（节点加入） | 全部节点 |
| 2379 | TCP | etcd client | control-plane 节点之间 |
| 2380 | TCP | etcd peer | control-plane 节点之间 |
| 2381 | TCP | etcd metrics | 监控节点 |
| 10250 | TCP | kubelet API | control-plane（metrics-server/exec/logs）、监控 |
| 10257 | TCP | kube-controller-manager | localhost / 监控 |
| 10259 | TCP | kube-scheduler | localhost / 监控 |
| 10249 | TCP | kube-proxy metrics | localhost / 监控 |
| 9099 | TCP | Canal/Calico 健康检查 | localhost |
| 179 | TCP | Calico BGP | 全部节点（Calico 模式） |
| 4789 | UDP | VXLAN（Canal/Flannel） | 全部节点 |
| 51820 | UDP | WireGuard（Calico 加密） | 全部节点（启用时） |
A.5.2 agent（worker）节点
| 端口 | 协议 | 组件/用途 | 放行来源 |
|---|---|---|---|
| 10250 | TCP | kubelet API | control-plane、监控 |
| 10249 | TCP | kube-proxy metrics | localhost / 监控 |
| 10256 | TCP | kube-proxy 健康检查 | LB（如需） |
| 8472 | UDP | Canal/Flannel VXLAN（部分版本） | 全部节点 |
| 4789 | UDP | VXLAN | 全部节点 |
| 179 | TCP | Calico BGP | 全部节点（Calico 模式） |
| 30000-32767 | TCP/UDP | NodePort 范围 | 业务流量来源 / LB |
| 169.254.20.10:53 | TCP/UDP | NodeLocal DNSCache（本地地址） | 本机 Pod |
| 53 | TCP/UDP | CoreDNS Service | 全部节点 |
注：CNI 不同端口不同（Cilium 用 8472/VXLAN 或 4240 健康检查），以实际选型为准；控制平面与节点之间建议内网全互信 + 外网边界白名单，明细表用于安全组/防火墙收敛。
A.6 容量估算公式卡（节点数 → 控制平面规格 → etcd 规格）
A.6.1 快速速查表
| 节点规模 | apiserver 副本 × 规格 | etcd 规格 | 控制平面总内存 | kubelet max-pods | 备注 |
|---|---|---|---|---|---|
| ≤ 500 | 3 × (8C/16G) | 3 × (4C/8G, 100G SSD) | 48G | 110 | 默认参数微调即可 |
| 500~1500 | 3 × (16C/32G) | 3 × (8C/16G, 200G NVMe) | 96G | 110~150 | 调 inflight、event-ttl |
| 1500~3000 | 3 × (32C/64G) | 3 × (16C/32G, 400G NVMe) | 192G | 150~200 | APF、ipvs、NodeLocal 全上 |
| 3000~5000 | 3 × (48C/96G) + 可选只读分流 | 3 × (16C/64G, 400G NVMe 企业级) | 288G+ | 200~250 | 接近单集群极限，全面调优 |
| > 5000 | 拆多集群 | — | — | — | 单集群硬上限约 5000 节点/15 万 Pod |
A.6.2 计算公式
text
# apiserver 内存（粗算）
apiserver_mem ≈ 8GB + Pod总数 × 1MB + (ConfigMap+Secret 总量 GB) × 2 + watch连接数 × 0.5MB
示例：10 万 Pod + 20GB 对象 + 5 万 watch ≈ 8 + 100 + 40 + 25 ≈ 173GB / 3 副本 ≈ 每副本 60~64G
# etcd 磁盘 IO（IOPS 需求）
etcd_iops ≈ 写入QPS × 2（WAL + backend 双写）
估算写入QPS ≈ Pod总数 × 0.01（常态） + 变更高峰 × 3
10 万 Pod 集群高峰写入 ≈ 3000 QPS → 需要 6000+ IOPS，必须 NVMe
# etcd DB 大小预估
db_size ≈ 对象总数 × 平均对象大小 × (1 + 碎片率 30%)
28 万 Pod(2KB) + 其他对象 ≈ 800MB 逻辑 → 物理约 1.2GB；quota 设 8GB 足够
# CoreDNS 副本数
coredns_replicas ≈ 峰值QPS / 单副本承载QPS(约 5000~10000/核) × 3（冗余）
峰值 20 万 QPS → 至少 15~20 副本（每副本 2 核）+ NodeLocal 削减 70%
# registry 带宽（镜像分发）
bandwidth ≈ 镜像大小 × 并发拉取节点数 / 目标拉取时长
2GB × 500 节点 / 5min = 33Gbps → 必须 P2P 或预热，裸 registry 不可行
# 调度器吞吐参考
默认配置约 50~100 Pod/s；批量重建场景所需吞吐 = 单波次驱逐 Pod 数 / 可接受恢复时长
升级 concurrency=10、每节点 40 Pod、要求 2 分钟恢复 → 400/120 ≈ 3.3 Pod/s（富余）
若 concurrency=100 → 33 Pod/s（逼近极限，需扩 scheduler 并调 percentageOfNodesToScore）A.7 全书学习路线图回顾表
| 阶段 | 对应部分 | 目标 | 检验标准 |
|---|---|---|---|
| 入门 | 第一部分 | 理解大规模集群架构决策与容量规划方法 | 能独立产出一份 3000 节点集群的容量规划书 |
| 基础 | 第二部分 | 掌握 RKE2 配置体系与自动化部署 | 30 分钟内自动化扩容 100 节点 |
| 进阶 | 第三部分 | 建立变更、备份、证书、升级运维体系 | 设计并演练一次全量升级（含回滚） |
| 进阶 | 第四部分 | 搭建 SLI/SLO 驱动的可观测性体系 | 配齐 A.2 全部告警阈值并接入值班 |
| 高级 | 第五部分 | 掌握各组件性能调优手段 | 压测定位并解决一个真实性能瓶颈 |
| 实战 | 第六部分 | 建立故障直觉与处置能力 | 对照 15 个案例写出本集群的 runbook |
| 随身 | 附录 | 速查与应急 | 不看笔记完成 etcd defrag / 证书轮换 / quorum 恢复演练 |
推荐动手实验清单（按周推进）
| 周 | 实验 | 对应章节 |
|---|---|---|
| W1 | 搭建 3 control-plane + 10 worker 的 RKE2 基线集群 | 第二部分 |
| W2 | 配置 etcd 快照 + 完成一次 snapshot restore 演练 | 第三部分/A.1.1 |
| W3 | 部署 Prometheus + 配齐 A.2 核心告警 | 第四部分 |
| W4 | 压测 apiserver（k6/kube-burner），观察 inflight/APF 行为 | 第五部分 |
| W5 | 故障注入：kill 两台 control-plane，演练 force-new-cluster 恢复 | 第六部分案例三 |
| W6 | 故障注入：制造 event 风暴 / 大 list，验证告警与限流 | 第六部分案例六/八 |
| W7 | kube-proxy iptables → ipvs 切换并对比同步延迟 | 第六部分案例十三 |
| W8 | 部署 NodeLocal DNSCache 并做 ndots 治理 | 第六部分案例十二 |
附录使用箴言：速查表的价值不在"查"，在于把阈值、参数、端口这些容易记混的东西从大脑卸载到纸上，把宝贵的注意力留给真正需要判断的故障现场。