---
tags: [microservice, kubernetes, k8s, container-orchestration]
create time: 2026-05-05 18:30
---

# Kubernetes — 参考手册

## 概述

Kubernetes (K8s) 是微服务架构的事实标准编排引擎。它将容器化的服务组织成声明式的资源对象，自动处理部署、扩展、故障恢复。

本文档是总入口：顶层概念、决策矩阵、速查表见本页；详细教程和实操指南在子文档中。

```mermaid
graph TB
    subgraph CLUSTER["K8s Cluster"]
        Master["控制面<br/>API Server / Scheduler / Controller Manager / etcd"]
        
        subgraph NODES["工作节点"]
            N1["Node A<br/>kubelet + kube-proxy"]
            N2["Node B<br/>kubelet + kube-proxy"]
        end
        
        Master --> N1
        Master --> N2
        
        subgraph APPS["应用层"]
            Order["Order Service Deployment"]
            Pay["Payment Service Deployment"]
        end
        
        N1 --> Order
        N2 --> Order
        N1 --> Pay
        N2 --> Pay
    end
    
    SVC["Service (ClusterIP)"] -->|Load Balance| Order
    Ingress["Ingress (HTTP Routing)"] --> SVC
    
    style Master fill:#e3f2fd
    style N1 fill:#fff3e0
    style N2 fill:#fff3e0
```

## 快速导航

| 主题 | 定位 | 文档 |
|------|------|------|
| 核心概念与 Deployment | **教程**：Pod/Deployment/Probe、滚动更新 | [[02-Kubernetes/01-核心概念与Deployment]] |
| 配置管理 | **操作手册**：ConfigMap/Secret 注入、热更新 | [[02-Kubernetes/02-配置管理]] |
| 网络与服务发现 | **教程**：Service 类型、Ingress、Headless | [[02-Kubernetes/03-网络与服务发现]] |
| 扩缩容与有状态应用 | **教程**：HPA / VPA / StatefulSet | [[02-Kubernetes/04-扩缩容与有状态应用]] |
| 调度控制 | **进阶**：Affinity/Taint/TopologySpread | [[02-Kubernetes/05-调度控制]] |
| 资源与安全管控 | **安全**：Quota/LimitRange/NetworkPolicy | [[02-Kubernetes/06-资源与安全管控]] |
| 运维排查 | **速查**：上线清单、诊断命令、FAQ | [[02-Kubernetes/07-运维排查]] |

## 核心概念速查

| K8s 对象 | 用途 | 类比 |
|---------|------|------|
| **Pod** | 最小部署单元，包含一个或多个容器 | 应用实例 |
| **Deployment** | 管理 Pod 的副本数和滚动更新 | 应用的"模板" |
| **Service** | 稳定的网络入口，负载均衡 | 内部 VIP → [[02-Kubernetes/03-网络与服务发现]] |
| **Ingress** | HTTP/HTTPS 路由规则 | 外部网关 → [[02-Kubernetes/03-网络与服务发现]] |
| **ConfigMap** | 配置注入（明文） → [[02-Kubernetes/02-配置管理]] |
| **Secret** | 敏感配置注入（base64）→ [[02-Kubernetes/02-配置管理]] |
| **HPA** | 根据指标自动扩缩容 → [[02-Kubernetes/04-扩缩容与有状态应用]] |
| **StatefulSet** | 有状态应用的有序管理 | DB、ZK → [[02-Kubernetes/04-扩缩容与有状态应用]] |

## 部署驱动模式对比

| 维度 | 传统 CI/CD (Push) | GitOps (Pull) |
|------|------------------|---------------|
| 部署驱动 | CI 服务器主动推送 | Git 仓库变动触发拉取 |
| 状态源 | CI pipeline 历史 | Git commit history |
| 漂移检测 | 通常无 | 持续比对，自动修复 |
| 安全边界 | CI 需直连 K8s | ArgoCD 集群内运行 |
| 回滚方式 | 回到上一次的 pipeline | `git revert` + 自动同步 |
| 代表工具 | Jenkins, GitHub Actions | ArgoCD, Flux |

> **选型建议**：团队规模 < 20 人时 Push 模式足够。≥ 50 人或多环境场景建议迁移到 GitOps → [[../03-CICD与GitOps]]

## Secret 管理方案对比

| 方案 | 适用场景 | 优点 | 缺点 |
|------|---------|------|------|
| K8s 原生 Secret | 小规模内部团队 | 零成本，开箱即用 | etcd 明文存储 |
| ESO (External Secrets) | 已有 Vault / AWS SSM | Git 中无密文 | 需维护额外组件 |
| SOPS + sealed-secrets | ArgoCD 用户 | 加密文件可提交到 Git | 需管理 PKI |
| 云厂商 Secret Manager | 深度绑定单一云平台 | 审计完善 | 平台锁定 |

> **渐进路径**：K8s Secret → 接入云厂商 Secret Manager → 引入 ESO 实现多云解耦。

## 编排工具选型

| 服务规模 | 推荐方案 | 理由 |
|----------|---------|------|
| < 10 个服务 | Kustomize / 裸 YAML | 复杂度高于收益 |
| 10~50 个服务 | Helm | 模板复用价值明显 |
| > 50 个服务 | Helm + Kustomize overlays | Helm 管模板，Kustomize 管环境差异 |

## 关键决策流程图

### 安全选型决策

```mermaid
flowchart TD
    START["开始选型"] --> SIZE["团队 < 20人?"]
    SIZE -- 是 --> K8SSECRET["✅ K8s 原生 Secret"]
    SIZE -- 否 --> CLOUD["深度绑定云厂商?"]
    CLOUD -- 是 --> SECRETMGR["✅ Cloud Secret Manager"]
    CLOUD -- 否 --> GITOPS["使用 ArgoCD?"]
    GITOPS -- 是 --> SOPS["✅ SOPS + sealed-secrets"]
    GITOPS -- 否 --> ESO["✅ External Secrets Operator"]
    
    style K8SSECRET fill:#e8f5e9
    style SECRETMGR fill:#e3f2fd
    style SOPS fill:#fff3e0
    style ESO fill:#f3e5f5
```

## 附录：常用命令速查

### kubectl 基础
```bash
kubectl set image deployment/order-service \
  order=registry.example.com/order-service:v1.2.3 -n production

kubectl rollout status deployment/order-service -n production --timeout=120s
kubectl rollout undo deployment/order-service -n production
```

### 关联笔记

- [[02-Kubernetes/01-核心概念与Deployment]] — Deployment 完整示例与 Probe 选择
- [[hhs/MS/05-部署运维/01-容器化]] — Docker 镜像是 K8s Pod 的基础单元
- [[hhs/MS/05-部署运维/03-CICD与GitOps]] — GitOps ArgoCD 操作 K8s manifest
- [[hhs/MS/05-部署运维/04-SRE实践]] — SLO/Error Budget 在 K8s 中的落地
- [[hhs/MS/02-服务治理/04-服务发现]] — K8s Service 是服务端发现模式的代表
- [[hhs/MS/02-服务治理/08-流量治理]] — Istio VirtualService 在 K8s 上的高级路由