中文内容
使用 kind 试验 Gateway API
本文档将指导你在 kind 上搭建一个使用 Gateway API 的本地实验环境。此设置旨在用于学习和测试。它可以帮助你在没有生产环境复杂性的情况下理解 Gateway API 概念。
注意：
This is an experimentation learning setup, and should not be used for production. The components used on this document are not suited for production usage. Once you're ready to deploy Gateway API in a production environment, select an implementation that suits your needs.概述
在本指南中，你将：
- 使用 kind（Kubernetes in Docker）设置本地 Kubernetes 集群
- 部署 cloud-provider-kind，它同时提供 LoadBalancer 服务和 Gateway API 控制器
- 创建 Gateway 和 HTTPRoute，将流量路由到演示应用程序
- 在本地测试你的 Gateway API 配置
此设置非常适合学习、开发和试验 Gateway API 概念。
前提条件
开始之前，请确保你的本地机器上已安装以下内容：
- Docker - 运行 kind 和 cloud-provider-kind 所必需
- kubectl - Kubernetes 命令行工具
- kind - Docker 中的 Kubernetes
- curl - 测试路由所必需
创建 kind 集群
通过运行以下命令创建一个新的 kind 集群：
kind create cluster
这将创建一个在 Docker 容器中运行的单节点 Kubernetes 集群。
安装 cloud-provider-kind
接下来，你需要 cloud-provider-kind，它为此设置提供两个关键组件：
- 一个 LoadBalancer 控制器，用于为 LoadBalancer 类型的 Service 分配地址
- 一个 Gateway API 控制器，用于实现 Gateway API 规范
它还会在你的集群中自动安装 Gateway API 自定义资源定义（CRD）。
在创建 kind 集群的同一主机上，将 cloud-provider-kind 作为 Docker 容器运行：
VERSION="$(basename $(curl -s -L -o /dev/null -w '%{url_effective}' https://github.com/kubernetes-sigs/cloud-provider-kind/releases/latest))"
docker run -d --name cloud-provider-kind --rm --network host -v /var/run/docker.sock:/var/run/docker.sock registry.k8s.io/cloud-provider-kind/cloud-controller-manager:${VERSION}
注意：在某些系统上，你可能需要提升权限才能访问 Docker 套接字。
验证 cloud-provider-kind 是否正在运行：
docker ps --filter name=cloud-provider-kind
你应该会看到该容器被列出且处于运行状态。你也可以查看日志：
docker logs cloud-provider-kind
试用 Gateway API
现在你的集群已经设置完成，可以开始试用 Gateway API 资源。
cloud-provider-kind 会自动预置一个名为 cloud-provider-kind 的 GatewayClass。你将使用这个类来创建你的 Gateway。
值得注意的是，虽然 kind 不是云提供商，但该项目被命名为 cloud-provider-kind，因为它提供了模拟云环境的功能。
部署 Gateway
以下清单将：
- 创建一个名为 gateway-infra 的新命名空间
- 部署一个在端口 80 上监听的 Gateway
- 接受主机名匹配 *.exampledomain.example 模式的 HTTPRoutes
- 允许来自任何命名空间的路由附加到该 Gateway。注意：在真实集群中，建议在 allowedRoutes 的命名空间选择器字段上使用 Same 或 Selector 值，以限制附加。
应用以下清单：
---
apiVersion: v1
kind: Namespace
metadata:
name: gateway-infra
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: gateway
namespace: gateway-infra
spec:
gatewayClassName: cloud-provider-kind
listeners:
- name: default
hostname: "*.exampledomain.example"
port: 80
protocol: HTTP
allowedRoutes:
namespaces:
from: All
然后验证你的 Gateway 是否已正确编程并分配了地址：
kubectl get gateway -n gateway-infra gateway
预期输出：
NAME CLASS ADDRESS PROGRAMMED AGE
gateway cloud-provider-kind 172.18.0.3 True 5m6s
PROGRAMMED 列应显示 True，ADDRESS 字段应包含一个 IP 地址。
部署一个演示应用程序
接下来，部署一个简单的 echo 应用程序，以帮助你测试 Gateway 配置。此应用程序：
- 监听端口 3000
- 回显请求详情，包括路径、标头和环境变量
- 在名为 demo 的命名空间中运行
应用以下清单：
apiVersion: v1
kind: Namespace
metadata:
name: demo
---
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/name: echo
name: echo
namespace: demo
spec:
ports:
- name: http
port: 3000
protocol: TCP
targetPort: 3000
selector:
app.kubernetes.io/name: echo
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/name: echo
name: echo
namespace: demo
spec:
selector:
matchLabels:
app.kubernetes.io/name: echo
template:
metadata:
labels:
app.kubernetes.io/name: echo
spec:
containers:
- env:
- name: POD_NAME
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.name
- name: NAMESPACE
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.namespace
image: registry.k8s.io/gateway-api/echo-basic:v20251204-v1.4.1
name: echo-basic
创建一个 HTTPRoute
现在创建一个 HTTPRoute，将流量从你的 Gateway 路由到 echo 应用。此 HTTPRoute 将：
- 响应主机名 some.exampledomain.example 的请求
- 将流量路由到 echo 应用
- 附加到 gateway-infra 命名空间中的 Gateway
应用以下清单：
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: echo
namespace: demo
spec:
parentRefs:
- name: gateway
namespace: gateway-infra
hostnames: ["some.exampledomain.example"]
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: echo
port: 3000
测试你的路由
最后一步是使用 curl 测试你的路由。你将使用主机名 some.exampledomain.example 向 Gateway 的 IP 地址发起请求。以下命令仅适用于 POSIX shell，可能需要根据你的环境进行调整：
GW_ADDR=$(kubectl get gateway -n gateway-infra gateway -o jsonpath='{.status.addresses[0].value}')
curl --resolve some.exampledomain.example:80:${GW_ADDR} http://some.exampledomain.example
你应该会收到类似这样的 JSON 响应：
{
"path": "/",
"host": "some.exampledomain.example",
"method": "GET",
"proto": "HTTP/1.1",
"headers": {
"Accept": [
"*/*"
],
"User-Agent": [
"curl/8.15.0"
]
},
"namespace": "demo",
"ingress": "",
"service": "",
"pod": "echo-dc48d7cf8-vs2df"
}
如果你看到这个响应，恭喜！你的 Gateway API 设置正在正常工作。
故障排除
如果某些内容未按预期工作，你可以通过检查资源状态来进行故障排除。
检查 Gateway 状态
首先，检查你的 Gateway 资源：
kubectl get gateway -n gateway-infra gateway -o yaml
查看 status 部分中的 conditions。你的 Gateway 应具有：
- Accepted: True - Gateway 已被控制器接受
- 已编程：True - Gateway 已成功配置
- .status.addresses 已填充 IP 地址
检查 HTTPRoute 状态
接下来，检查你的 HTTPRoute：
kubectl get httproute -n demo echo -o yaml
检查 status.parents 部分中的 conditions。常见问题包括：
- ResolvedRefs 设置为 False，原因为 BackendNotFound；这意味着后端 Service 不存在或名称错误
- Accepted 设置为 False；这意味着该路由无法附加到 Gateway（请检查命名空间权限或主机名匹配）
后端未找到时的示例错误：
status:
parents:
- conditions:
- lastTransitionTime: "2026-01-19T17:13:35Z"
message: backend not found
observedGeneration: 2
reason: BackendNotFound
status: "False"
type: ResolvedRefs
controllerName: kind.sigs.k8s.io/gateway-controller
检查控制器日志
如果资源状态未显示问题，请检查 cloud-provider-kind 日志：
docker logs -f cloud-provider-kind
这将显示来自 LoadBalancer 和 Gateway API 控制器的详细日志。
清理
完成实验后，可以清理资源：
移除 Kubernetes 资源
删除命名空间（这将移除其中的所有资源）：
kubectl delete namespace gateway-infra
kubectl delete namespace demo
停止 cloud-provider-kind
停止并移除 cloud-provider-kind 容器：
docker stop cloud-provider-kind
由于该容器是使用 --rm 标志启动的，因此停止后会被自动移除。
删除 kind 集群
最后，删除 kind 集群：
kind delete cluster
后续步骤
既然你已经在本地试用了 Gateway API，现在可以继续探索适用于生产环境的实现：
- 生产部署：查看 Gateway API 的实现，寻找符合你生产需求的控制器
- 了解更多：查阅 Gateway API 文档，了解 TLS、流量拆分和标头操作等高级功能
- 高级路由：按照 Gateway API 用户指南，试验基于路径的路由、标头匹配、请求镜像和其他功能
最后提醒一句
这种设置仅用于开发和学习。对于实际工作负载，请始终使用生产级 Gateway API 实现。
- ← 上一页
- 下一步 →