4. 环境准备：Kubernetes集群版本要求、Gateway API CRD安装、Gateway Controller部署

在开始使用 Gateway API 进行资源配额管理之前，必须确保底层环境满足 Gateway API 的运行时要求。本章将依次覆盖三个核心环节：集群版本校验、CRD 安装以及 Controller 部署。任何环节的缺失或版本错配都会导致后续配额模型无法生效。

4.1 Kubernetes 集群版本要求

Gateway API 依赖 Kubernetes 内置的 CRD 机制和网络功能，不同 API 版本对集群版本有明确的最低要求。下表列出了主流 Gateway API 版本与 Kubernetes 版本的兼容关系：

Gateway API 版本 最低 Kubernetes 版本 推荐 Kubernetes 版本 关键依赖特性
v1alpha2 (实验性) 1.20 1.22+ CRD v1、EndpointSlice
v1beta1 (Beta) 1.23 1.25+ Service IP 保留、IngressClassParams
v1 (GA) 1.25 1.27+ GRPCRoute、BackendTLSPolicy
版本检查命令：使用 kubectl version --short 确认集群版本。如果版本低于 1.23，建议先升级集群，否则 v1beta1 及以上版本的 CRD 可能无法正常注册。

4.2 Gateway API CRD 安装

CRD（Custom Resource Definition）是 Gateway API 的基石。安装 CRD 后，Kubernetes 才能识别 GatewayClass、Gateway、HTTPRoute 等资源类型。推荐使用官方 YAML 清单或 Helm Chart 进行安装。

4.2.1 安装方式对比

安装方式 命令/示例 适用场景
官方标准 YAML kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml 快速验证、CI/CD 环境
实验性 YAML kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/experimental-install.yaml 需要 GRPCRoute、BackendTLSPolicy 等实验特性
Helm Chart helm install gateway-api gateway-api/gateway-api --version 1.1.0 生产环境、版本管理

4.2.2 验证 CRD 安装

安装完成后，执行以下命令确认 CRD 已注册：

kubectl get crd | grep gateway.networking.k8s.io

预期输出应包含以下核心 CRD：

  • gatewayclasses.gateway.networking.k8s.io
  • gateways.gateway.networking.k8s.io
  • httproutes.gateway.networking.k8s.io
  • referencegrants.gateway.networking.k8s.io
版本锁定建议：在生产环境中，始终将 CRD 版本与 Controller 版本对齐。例如，使用 v1.1.0 的 CRD 时，Controller 也应选择支持 v1.1.0 的版本，避免 API 字段不兼容。

4.3 Gateway Controller 部署

CRD 安装完成后，需要部署一个 Gateway Controller 来实际处理 Gateway 和 Route 资源。Controller 负责监听资源变化、配置底层数据面（如 Envoy、HAProxy、Nginx）。

4.3.1 常见 Controller 选择

Controller 名称 数据面 部署复杂度 推荐场景
Istio Envoy 中 服务网格 + 网关统一管理
Contour Envoy 低 轻量级入口网关
nginx-gateway Nginx 低 Nginx 生态用户
Kong Kong Gateway 中 API 网关 + 插件扩展

4.3.2 部署步骤（以 Contour 为例）

以下步骤演示如何快速部署 Contour 作为 Gateway Controller：

  1. 安装 Contour
kubectl apply -f https://projectcontour.io/quickstart/contour-gateway.yaml
  1. 验证 Controller Pod 运行
kubectl get pods -n projectcontour -l app=contour
  1. 确认 GatewayClass 已注册
kubectl get gatewayclass

预期输出应包含一个名为 contour 的 GatewayClass，状态为 Accepted=True。

4.4 环境准备完整流程

下图展示了从集群检查到 Controller 就绪的完整流程，以及各步骤之间的依赖关系：

环境准备完整流程 1. 集群版本检查 kubectl version 2. CRD 安装 kubectl apply -f 3. Controller 部署 helm install / kubectl apply 验证 CRD 注册 kubectl get crd 验证 GatewayClass kubectl get gatewayclass 验证 Pod 运行 kubectl get pods 环境就绪 集群 + CRD + Controller 全部就绪

4.5 常见故障排查

环境准备阶段最容易出现以下三类问题，提前了解可大幅缩短调试时间：

故障 1：CRD 安装后资源无法创建
现象：kubectl apply -f httproute.yaml 报错 no matches for kind "HTTPRoute"。
原因：CRD 安装未完成或版本不匹配。
解决：重新执行 CRD 安装命令，并检查 CRD 的 spec.versions 是否包含你使用的 API 版本。
故障 2：GatewayClass 状态为 False
现象：kubectl get gatewayclass 显示 Accepted=False。
原因：Controller 未运行或无法连接到 API Server。
解决：检查 Controller Pod 日志 kubectl logs -n <namespace> <pod-name>，确认网络连通性和 RBAC 权限。
故障 3：Gateway 创建后处于 Pending 状态
现象：kubectl get gateway 显示 STATUS=Pending。
原因：Controller 未监听该 GatewayClass 或 Gateway 的 gatewayClassName 字段拼写错误。
解决：确认 GatewayClass 名称完全匹配，并检查 Controller 的启动参数中是否指定了 --gateway-class。

4.6 环境就绪检查清单

完成所有步骤后，使用以下清单进行最终确认：

  • 集群版本：≥ 1.23（推荐 1.27+）
  • CRD 注册：kubectl get crd | grep gateway.networking.k8s.io 返回至少 4 个 CRD
  • GatewayClass 就绪：kubectl get gatewayclass 显示 Accepted=True
  • Controller Pod 运行：kubectl get pods -n <controller-namespace> 显示 Running
  • 示例资源测试：创建一个简单的 HTTPRoute 并绑定到 Gateway，确认状态变为 Programmed=True
← 上一章 📖 返回目录 下一章 →