快速开始

本指南会使用 Helm 安装 Nantian Gateway，创建一个 demo 后端，绑定一个 HTTPRoute，并通过数据面发送一次请求。整个流程不依赖本地示例文件。

开始之前

你需要：

一个运行中的 Kubernetes 集群。
已配置到该集群的 kubectl。
helm。
可选的 curl，用于最后的请求测试。

以下命令使用 Helm chart 默认值。Helm 会创建名为 nantian-gw 的 GatewayClass；demo 清单会创建自己的 Gateway 和 HTTPRoute。

安装 Gateway API CRD

安装标准 Gateway API v1.5.1 CRD：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

这会让 Kubernetes 识别 Gateway、HTTPRoute、GRPCRoute 和 ReferenceGrant 等标准资源。

安装 Nantian Gateway

添加 chart 仓库，并安装到默认命名空间：

helm repo add nantian-gw https://chart.nantian.dev
helm repo update
helm install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace

该安装会创建控制面、数据面、dashboard、Service、RBAC、NetworkPolicy，以及默认的 GatewayClass。

等待 Gateway Pod

等待所有 Nantian Gateway Pod 就绪：

kubectl wait --for=condition=ready pod --all -n nantian-gw --timeout=180s
kubectl get pods -n nantian-gw

这一步证明 workload 已经被调度，并且 readiness probe 通过。如果 Pod 没有就绪，请查看日志：

kubectl logs -n nantian-gw deploy/nantian-gw-controlplane --tail=100
kubectl logs -n nantian-gw deploy/nantian-gw-dataplane --tail=100

验证 GatewayClass

查看 Helm chart 创建的 GatewayClass：

kubectl get gatewayclass nantian-gw

controller name 应该是 gateway.networking.k8s.io/nantian-gw。如果该 class 不存在，请确认 Helm release 安装成功，并且没有把 gatewayClass.enabled 设置为 false。

创建 Demo Route

使用一个 inline manifest 创建命名空间、echo 后端、Gateway 和 HTTPRoute：

kubectl create namespace nantian-demo --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -n nantian-demo -f - <<'YAML'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echo
  template:
    metadata:
      labels:
        app: echo
    spec:
      containers:
        - name: echo
          image: docker.io/ealen/echo-server:latest
          ports:
            - containerPort: 80
          env:
            - name: PORT
              value: "80"
---
apiVersion: v1
kind: Service
metadata:
  name: echo
spec:
  selector:
    app: echo
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nantian-demo
spec:
  gatewayClassName: nantian-gw
  listeners:
    - name: http
      protocol: HTTP
      port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo
spec:
  parentRefs:
    - name: nantian-demo
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /echo
      backendRefs:
        - name: echo
          port: 80
YAML

这一步证明 Kubernetes 可以接受标准 Gateway API 对象，并且 route 可以引用同命名空间内的 Service 后端。

查看 Route 状态

等待后端 Pod 就绪，并查看 Gateway API 资源：

kubectl wait --for=condition=ready pod -l app=echo -n nantian-demo --timeout=180s
kubectl get gateway,httproute -n nantian-demo
kubectl describe httproute echo -n nantian-demo

如果 route 没有 attached，请查看 kubectl describe httproute 输出中的 Parents 部分。常见原因包括缺少 GatewayClass、listener 不匹配，或者后端 Service 名称/端口不匹配。

通过数据面发送请求

打开一个终端，转发数据面运行时 HTTP 端口：

kubectl port-forward -n nantian-gw deploy/nantian-gw-dataplane 10080:10080

在另一个终端中，通过网关发送请求：

curl -i http://localhost:10080/echo

成功响应说明数据面已经收到运行时快照，并把请求路由到了 echo Service。

清理

删除 demo 命名空间和 Helm release：

kubectl delete namespace nantian-demo
helm uninstall nantian-gw -n nantian-gw
kubectl delete namespace nantian-gw

Gateway API CRD 是集群级依赖，不会被这些命令删除。

故障排查

如果 Pod 没有就绪，请查看控制面和数据面日志，并确认可以从 ghcr.io 拉取镜像。如果 GatewayClass 缺失或没有 accepted，请检查 Helm release values 和 controller name gateway.networking.k8s.io/nantian-gw。如果 route 没有 attached，请查看 kubectl describe httproute echo -n nantian-demo，并确认 Gateway 名为 nantian-demo、listener protocol 是 HTTP、后端 Service 名为 echo 且端口为 80。