Update handbook

Author: feiskyer

CHANGELOG.md

@@ -1,9 +1,10 @@
 # 变更历史
 
+- 2025.06.09 更新 Kubernetes v1.33 新功能特性和变更
+- ...
 - 2018.07.08 更新至 [Kubernetes v1.11](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md) 版本
 - 2018.04.07 更新至 [Kubernetes v1.10](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.10.md) 版本
 - 2018.02.07 更新至 [Kubernetes v1.9](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.9.md) 版本
 - 2017.12.09 更新至 [Kubernetes v1.8](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.8.md) 版本
 - 2017.09.11 更新至 [Kubernetes v1.7](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.7.md) 版本
 - 2017.06.29 更新至 [Kubernetes v1.6](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.6.md) 版本
-

SUMMARY.md

@@ -34,6 +34,7 @@
   * [CustomResourceDefinition](concepts/objects/customresourcedefinition.md)
   * [DaemonSet](concepts/objects/daemonset.md)
   * [Deployment](concepts/objects/deployment.md)
+  * [Gateway API](concepts/objects/gateway-api.md)
   * [Ingress](concepts/objects/ingress.md)
   * [Job](concepts/objects/job.md)
   * [LocalVolume](concepts/objects/local-volume.md)

apps/index/patterns.md

@@ -9,7 +9,7 @@
 * 不推荐生产环境镜像使用`latest`标签，但开发环境推荐使用并设置`imagePullPolicy`为`Always`
 * 推荐使用Readiness探针检测服务是否真正运行起来了
 * 使用`activeDeadlineSeconds`避免快速失败的Job无限重启
-* 引入Sidecar处理代理、请求速率控制和连接控制等问题
+* 引入多容器模式（Sidecar、Ambassador、Adapter等）处理代理、请求速率控制和连接控制等问题
 
 ## 分离构建和运行环境
 
@@ -57,10 +57,115 @@ root     14221  0.0  0.0   1188     4 ?        Ss   13:25   0:00 sleep 10000
 解决方法就是保证容器的init进程可以正确处理SIGTERM等退出信号，比如使用dumb-init
 
 ```bash
-$ docker run quay.io/gravitational/debian-tall /usr/bin/dumb-init /bin/sh -c "sleep 10000"
+docker run quay.io/gravitational/debian-tall /usr/bin/dumb-init /bin/sh -c "sleep 10000"
 ```
 
+## 多容器设计模式
+
+### Sidecar 模式（边车模式）
+
+Sidecar 模式是最常用的多容器模式，通过在Pod中添加辅助容器来扩展主应用的功能，而无需修改主应用代码。
+
+**使用场景：**
+
+- 日志收集和转发
+- 监控指标收集
+- 网络代理和服务网格
+- 配置热更新
+- 安全扫描
+
+**优势：**
+
+- 职责分离，每个容器专注单一功能
+- 可以独立更新和扩展
+- 复用性强，可以跨多个应用使用
+
+### Ambassador 模式（大使模式）
+
+Ambassador 模式通过代理容器来简化主应用对外部服务的访问，处理服务发现、负载均衡、重试逻辑等。
+
+**使用场景：**
+
+- 数据库连接代理
+- 外部API访问代理
+- 服务发现和负载均衡
+- 连接池管理
+- 请求路由和熔断
+
+**优势：**
+
+- 简化应用代码，将网络复杂性抽象到代理层
+- 可以统一处理连接管理和错误重试
+- 便于实现横切关注点
+
+### Adapter 模式（适配器模式）
+
+Adapter 模式用于标准化应用输出，将应用的输出转换为统一的格式或协议。
+
+**使用场景：**
+
+- 监控指标格式转换
+- 日志格式标准化
+- 协议转换（HTTP到gRPC）
+- 数据格式适配
+
+**优势：**
+
+- 不修改应用代码即可适配不同的监控和日志系统
+- 提供统一的数据格式
+- 便于集成遗留系统
+
+### 配置助手模式
+
+通过专门的配置容器来管理应用配置，实现配置的动态更新和热加载。
+
+**使用场景：**
+
+- 从配置中心拉取配置
+- 密钥管理和轮换
+- 环境变量动态更新
+- 配置文件热重载
+
+**优势：**
+
+- 配置管理与业务逻辑分离
+- 支持配置热更新
+- 统一的配置管理策略
+
+### Sidecar 启动顺序控制最佳实践
+
+从 Kubernetes v1.29.0 开始，原生支持 Sidecar Init 容器，能够更好地控制容器启动顺序。在 v1.33.0 中达到稳定版本。
+
+**确保 Sidecar 优先启动的策略：**
+
+1. **使用 startupProbe（推荐）**：最可靠的方法，确保主应用等待 Sidecar 就绪
+   ```yaml
+   initContainers:
+   - name: sidecar
+     image: nginx
+     restartPolicy: Always
+     startupProbe:
+       httpGet:
+         path: /health
+         port: 8080
+       initialDelaySeconds: 5
+       periodSeconds: 3
+   ```
+
+2. **应用层依赖处理**：在应用代码中实现对 Sidecar 的容错和重试机制
+3. **postStart 钩子**：使用生命周期钩子实现自定义等待逻辑
+4. **避免错误做法**：不要依赖 readinessProbe 或 livenessProbe 来控制启动顺序
+
+### 最佳实践
+
+1. **合理选择模式**：根据实际需求选择合适的多容器模式，避免过度设计
+2. **资源管理**：为每个容器设置合适的资源限制，避免资源竞争
+3. **生命周期管理**：确保容器间的启动顺序和依赖关系
+4. **错误处理**：实现容器间的错误传播和重试机制
+5. **监控和日志**：为每个容器配置独立的监控和日志收集
+6. **启动依赖控制**：使用 startupProbe 确保 Sidecar 容器优先就绪
+7. **容错设计**：在应用层面实现对 Sidecar 服务的容错机制
+
 ## 参考文档
 
 * [Kubernetes Production Patterns](https://github.com/gravitational/workshop/blob/master/k8sprod.md)
-

concepts/architecture.md

@@ -24,7 +24,7 @@ Kubernetes 借鉴了 Borg 的设计理念，比如 Pod、Service、Labels 和单
 Kubernetes 主要由以下几个核心组件组成：
 
 * etcd 保存了整个集群的状态；
-* kube-apiserver 提供了资源操作的唯一入口，并提供认证、授权、访问控制、API 注册和发现等机制；
+* kube-apiserver 提供了资源操作的唯一入口，并提供认证、授权、访问控制、API 注册和发现等机制；从 v1.33 开始引入流式列表响应优化，显著降低大规模集群的内存消耗；
 * kube-controller-manager 负责维护集群的状态，比如故障检测、自动扩展、滚动更新等；
 * kube-scheduler 负责资源的调度，按照预定的调度策略将 Pod 调度到相应的机器上；
 * kubelet 负责维持容器的生命周期，同时也负责 Volume（CVI）和网络（CNI）的管理；

concepts/components/apiserver.md

@@ -142,6 +142,26 @@ kube-apiserver 提供了 Kubernetes 的 REST API，实现了认证、授权、
 
 ![](../../.gitbook/assets/kube-apiserver.png)
 
+### 流式列表响应 (Streaming List Responses)
+
+从 Kubernetes v1.33 开始，API Server 引入了流式列表响应机制，解决大规模集群中 List API 调用的内存消耗问题：
+
+**技术原理：**
+- 传统方式：将整个响应序列化为单个连续内存块，然后一次性传输
+- 流式编码：逐个处理和传输 "Items" 字段中的项目，允许内存在传输过程中逐步释放
+
+**性能优势：**
+- 显著降低 API Server 内存占用（基准测试显示内存使用从 70-80GB 降至 3GB，提升约 20 倍）
+- 减少大规模集群中出现内存不足 (OOM) 的风险
+- 提高资源利用率和系统稳定性
+- 保持与现有编码器的字节级兼容性，无需客户端修改
+
+**应用场景：**
+- 大规模集群（节点数 > 1000）的资源列表查询
+- 包含大量对象的命名空间列表操作
+- 监控系统的批量数据获取
+- CI/CD 系统的集群状态检查
+
 以 `/apis/batch/v2alpha1/jobs` 为例，GET 请求的处理过程如下图所示：
 
 ![img](../../.gitbook/assets/API-server-flow.png)

concepts/components/controller-manager.md

@@ -85,7 +85,7 @@ kube-controller-manager \
 kube-controller-manager 由一系列的控制器组成，这些控制器可以划分为三组
 
 1. 必须启动的控制器
-   * EndpointController
+   * EndpointController（已弃用，Kubernetes 1.33+，但仍需要维持兼容性）
    * ReplicationController
    * PodGCController
    * ResourceQuotaController
@@ -122,11 +122,29 @@ cloud-controller-manager 在 Kubernetes 启用 Cloud Provider 的时候才需要
 * RouteController
 * ServiceController
 
+### cloud-controller-manager 启动时序协调
+
+cloud-controller-manager 在集群启动过程中需要特别注意启动时序问题。由于 kubelet 启动时会给 Node 添加 `node.cloudprovider.kubernetes.io/uninitialized=NoSchedule` taint，而 cloud-controller-manager 负责移除该 taint，这可能导致启动时序冲突。
+
+#### 关键启动参数配置
+
+* `--leader-elect=true`: 启用多实例选主，确保高可用
+* `--node-status-update-frequency`: 与 kubelet 协调节点状态更新频率
+* `--node-monitor-period`: 监控节点状态的检查周期
+* `--use-service-account-credentials=true`: 使用单独的服务账号凭据
+
+#### 部署最佳实践
+
+1. **调度策略**: 使用 nodeSelector 将 cloud-controller-manager 调度到控制平面节点
+2. **容忍度配置**: 配置适当的 tolerations 以处理节点 taint
+3. **高可用性**: 使用 Deployment 或 DaemonSet 而非静态 Pod
+4. **网络模式**: 在某些环境下使用 `hostNetwork: true` 避免网络依赖
+
 ## 高可用
 
 在启动时设置 `--leader-elect=true` 后，controller manager 会使用多节点选主的方式选择主节点。只有主节点才会调用 `StartControllers()` 启动所有控制器，而其他从节点则仅执行选主算法。
 
-多节点选主的实现方法见 [leaderelection.go](https://github.com/kubernetes/client-go/blob/master/tools/leaderelection/leaderelection.go)。它实现了两种资源锁（Endpoint 或 ConfigMap，kube-controller-manager 和 cloud-controller-manager 都使用 Endpoint 锁），通过更新资源的 Annotation（`control-plane.alpha.kubernetes.io/leader`），来确定主从关系。
+多节点选主的实现方法见 [leaderelection.go](https://github.com/kubernetes/client-go/blob/master/tools/leaderelection/leaderelection.go)。它实现了多种资源锁（Endpoint、ConfigMap 或 Lease，kube-controller-manager 和 cloud-controller-manager 传统上使用 Endpoint 锁，但 Endpoint API 已弃用，新版本推荐使用 Lease 锁），通过更新资源的 Annotation（`control-plane.alpha.kubernetes.io/leader`），来确定主从关系。
 
 ## 高性能
 

concepts/components/kube-proxy.md

@@ -2,16 +2,21 @@
 
 每台机器上都运行一个 kube-proxy 服务，它监听 API server 中 service 和 endpoint 的变化情况，并通过 iptables 等来为服务配置负载均衡（仅支持 TCP 和 UDP）。
 
+> **注意**: 从 Kubernetes 1.33 开始，Endpoints API 已被弃用，kube-proxy 将逐步迁移到使用 EndpointSlices API 来获取更好的性能和功能支持。
+
 kube-proxy 可以直接运行在物理机上，也可以以 static pod 或者 daemonset 的方式运行。
 
 kube-proxy 当前支持以下几种实现
 
 * userspace：最早的负载均衡方案，它在用户空间监听一个端口，所有服务通过 iptables 转发到这个端口，然后在其内部负载均衡到实际的 Pod。该方式最主要的问题是效率低，有明显的性能瓶颈。
-* iptables：目前推荐的方案，完全以 iptables 规则的方式来实现 service 负载均衡。该方式最主要的问题是在服务多的时候产生太多的 iptables 规则，非增量式更新会引入一定的时延，大规模情况下有明显的性能问题
+* iptables：传统的负载均衡方案，完全以 iptables 规则的方式来实现 service 负载均衡。该方式最主要的问题是在服务多的时候产生太多的 iptables 规则，非增量式更新会引入一定的时延，大规模情况下有明显的性能问题
 * ipvs：为解决 iptables 模式的性能问题，v1.11 新增了 ipvs 模式（v1.8 开始支持测试版，并在 v1.11 GA），采用增量式更新，并可以保证 service 更新期间连接保持不断开
+* nftables：新推出的高性能模式（v1.29 开始支持 alpha 版，目前处于 beta 状态，预计 v1.33 GA），通过使用 "verdict map" 实现更高效的数据包路由，将包处理延迟从 O(n) 降低到大致 O(1)，显著减少了首包延迟，特别是在大规模集群中。需要 Linux 内核 5.13 或更新版本
 * winuserspace：同 userspace，但仅工作在 windows 节点上
 
-注意：使用 ipvs 模式时，需要预先在每台 Node 上加载内核模块 `nf_conntrack_ipv4`, `ip_vs`, `ip_vs_rr`, `ip_vs_wrr`, `ip_vs_sh` 等。
+注意：
+- 使用 ipvs 模式时，需要预先在每台 Node 上加载内核模块 `nf_conntrack_ipv4`, `ip_vs`, `ip_vs_rr`, `ip_vs_wrr`, `ip_vs_sh` 等。
+- 使用 nftables 模式时，需要 Linux 内核 5.13 或更新版本，可能与某些现有网络组件不完全兼容，目前还不是默认模式。
 
 ```bash
 # load module <module_name>
@@ -125,16 +130,61 @@ UDP  10.0.0.10:53 rr
 ## 启动 kube-proxy 示例
 
 ```bash
-kube-proxy --kubeconfig=/var/lib/kubelet/kubeconfig --cluster-cidr=10.240.0.0/12 --feature-gates=ExperimentalCriticalPodAnnotation=true --proxy-mode=iptables
+# iptables 模式（传统模式）
+kube-proxy --kubeconfig=/var/lib/kubelet/kubeconfig --cluster-cidr=10.240.0.0/12 --proxy-mode=iptables
+
+# ipvs 模式（高性能模式）
+kube-proxy --kubeconfig=/var/lib/kubelet/kubeconfig --cluster-cidr=10.240.0.0/12 --proxy-mode=ipvs
+
+# nftables 模式（最新高性能模式，需要内核 5.13+）
+kube-proxy --kubeconfig=/var/lib/kubelet/kubeconfig --cluster-cidr=10.240.0.0/12 --proxy-mode=nftables
 ```
 
 ## kube-proxy 工作原理
 
-kube-proxy 监听 API server 中 service 和 endpoint 的变化情况，并通过 userspace、iptables、ipvs 或 winuserspace 等 proxier 来为服务配置负载均衡（仅支持 TCP 和 UDP）。
+kube-proxy 监听 API server 中 service 和 endpoint（以及 EndpointSlices）的变化情况，并通过 userspace、iptables、ipvs、nftables 或 winuserspace 等 proxier 来为服务配置负载均衡（仅支持 TCP 和 UDP）。现代版本的 kube-proxy 优先使用 EndpointSlices API 而不是传统的 Endpoints API，以获得更好的性能和扩展性。
 
 ![](../../.gitbook/assets/kube-proxy%20%283%29.png)
 
 ## kube-proxy 不足
 
 kube-proxy 目前仅支持 TCP 和 UDP，不支持 HTTP 路由，并且也没有健康检查机制。这些可以通过自定义 [Ingress Controller](../../extension/ingress/) 的方法来解决。
 
+## nftables 模式详细说明
+
+nftables 模式是 kube-proxy 的最新代理模式，旨在解决 iptables 模式在大规模集群中的性能问题：
+
+### 性能优势
+
+1. **数据平面延迟优化**：使用 "verdict map" 进行更高效的数据包路由，将包处理时间从 O(n) 降低到大致 O(1)
+2. **控制平面延迟优化**：相比 iptables 模式提供更增量式的更新，更新大小仅与变更的 Services 和 endpoints 成比例
+3. **显著减少首包延迟**：特别是在大规模集群中表现突出
+4. **消除全局锁竞争问题**：避免了 iptables 模式的全局锁竞争
+
+### 使用要求和限制
+
+- 需要 Linux 内核 5.13 或更新版本
+- 与 iptables 模式不是 100% 兼容
+- 可能与某些现有网络组件不兼容
+- 目前还不是默认模式
+
+### 启用方法
+
+可以通过以下方式启用 nftables 模式：
+
+```bash
+# 直接启动 kube-proxy
+kube-proxy --proxy-mode nftables
+
+# 使用 kubeadm 集群
+kubeadm init --config kubeadm-config.yaml  # 需要在配置中指定 proxy-mode
+
+# 将现有集群从 iptables/ipvs 模式转换为 nftables 模式
+kubectl patch configmap kube-proxy -n kube-system --patch '{"data":{"config.conf":"mode: nftables"}}'
+```
+
+### 发展前景
+
+- 预计在 Kubernetes v1.33 版本中达到 GA 状态
+- 未来可能最终替代 IPVS 模式
+- iptables 模式将继续得到支持