Helm 安装

Helm chart 是安装 Nantian Gateway 的推荐方式。它把控制面、数据面、dashboard、RBAC、NetworkPolicy、Service、ConfigMap 和默认 GatewayClass 打包到同一个 release。

前提条件

先安装 Gateway API standard CRD：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml
kubectl get crd gateways.gateway.networking.k8s.io

你还需要 Helm 3.x，以及能访问目标集群的 kubectl。

添加 Chart 仓库

使用当前 chart 仓库地址：

helm repo add nantian-gw https://chart.nantian.dev
helm repo update

不要使用旧的复数形式 chart host。

默认搜索只显示稳定 chart 版本。每个 commit 生成的 snapshot chart 会以 0.2.3-<git-sha> 这类 prerelease 版本发布；需要查看或安装这些版本时加上 --devel：

helm search repo nantian-gw/nantian-gw --versions --devel

推荐 Helm 工作流

在可重复的环境里，更推荐先渲染、再安装的工作流，并把长期配置收敛到 values 文件：

helm show values nantian-gw/nantian-gw > values-reference.yaml
helm template nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  -f my-values.yaml > rendered.yaml
helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  -f my-values.yaml

即使是第一次部署，也建议直接使用 helm upgrade --install，这样首装和后续升级可以复用同一条命令。对于要长期保留的修改，优先使用分层 values 文件，而不是堆很长的 --set 参数链。

当你调整 CRD 归属、TLS、admin 鉴权或 NetworkPolicy 时，先渲染清单再上线更稳妥。关于 values 文件的组织方式，请继续阅读 Helm Values 指南。

使用默认值安装

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace

默认 release 会创建命名空间 nantian-gw、2 个控制面副本、2 个数据面副本、1 个 dashboard 副本、安装概述中列出的固定 Service，以及名为 nantian-gw 的 GatewayClass。

安装前可以先预览渲染结果：

helm template nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw > rendered.yaml
helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  --dry-run

关键默认值

以下片段与当前 chart 默认值一致。

功能模式与 Gateway API CRD

featureMode: standard
gatewayAPI:
  installCRDs: false
  channel: standard

featureMode 控制 Nantian Gateway 自身的运行时功能开关。gatewayAPI.installCRDs 控制本 Chart 是否渲染官方 Gateway API CRD。生产默认值保持 standard 运行时模式，并要求安装网关前已由平台层准备 Gateway API CRD。

全局与 GatewayClass

global:
  imageRegistry: "ghcr.io"
  imagePullSecrets: []
  commonLabels: {}

gatewayClass:
  enabled: true
  controllerName: "gateway.networking.k8s.io/nantian-gw"

Chart 会根据 controller name 推导默认 GatewayClass 名称，因此 gateway.networking.k8s.io/nantian-gw 会变成 nantian-gw。

控制面

controlplane:
  enabled: true
  replicas: 2
  image:
    repository: "nantian-gw/nantian-controlplane"
    tag: "latest"
    pullPolicy: IfNotPresent
  config:
    grpcAddr: ":18080"
    adminAddr: ":18081"
    metricsAddr: ":18082"
    healthProbeAddr: ":18083"
    features:
      enableExperimentalGateway: false
      enableAiGateway: false

当前 chart 默认使用不可变的发布 tag（v2026.06.0）并采用 pullPolicy: IfNotPresent。生产环境请在 values 文件里改成特定发布 tag 或镜像 digest。

控制面 Service 拆分如下：

Service	端口
nantian-gw-controlplane-grpc	18080
nantian-gw-controlplane-admin	18081
nantian-gw-controlplane-metrics	18082

数据面

dataplane:
  enabled: true
  replicas: 2
  image:
    repository: "nantian-gw/dataplane"
    tag: "latest"
    pullPolicy: IfNotPresent
  resources:
    requests:
      cpu: "1000m"
      memory: "256Mi"
    limits:
      cpu: "2000m"
      memory: "1Gi"
  config:
    adminAddr: "0.0.0.0:19080"
    runtime:
      httpListenAddr: "0.0.0.0:80"
  accessLogVolume:
    enabled: true
    name: access-logs
    mountPath: /var/log/nantian-gw
    sizeLimit: 256Mi

数据面 Service 是 nantian-gw-dataplane-admin 和 nantian-gw-dataplane-metrics，两者 Service port 都是 19080。运行时 HTTP 流量由配置中的监听地址 0.0.0.0:80 处理。

在 Kubernetes 安装场景下，Chart 会把 Pod metadata.name 注入到 NANTIAN_GW_NODE_ID，因此即使 dataplane.config.nodeId 仍以 dp-kubernetes 作为兜底值，每个副本也会得到唯一的运行时 nodeId。如果你使用旧版清单部署，请确认没有再用固定值覆盖它，也不要继续使用已经废弃的 PGW_NODE_ID。

当数据面副本数大于 1 时，不要依赖运行时自动生成的会话密钥，而应显式配置稳定的 session-persistence Secret：

dataplane:
  sessionPersistence:
    existingSecret: nantian-gw-dataplane-session-persistence
    secretKey: session-persistence

dataplane.sessionPersistence.sharedSecret 适合快速测试，生产环境更建议使用 existingSecret。设置任一方式后，Chart 会挂载对应 Secret，并自动把数据面运行时的 sessionPersistence.secretKeyFile 接线好。

Dashboard

dashboard:
  enabled: true
  replicas: 2
  image:
    repository: "nantian-gw/dashboard"
    tag: "latest"
    pullPolicy: IfNotPresent

当前 chart 默认对 controlplane、dataplane 和 dashboard 都使用 v2026.06.0 发布 tag。生产环境仍应在 values 文件里显式固定特定发布 tag 或 digest。

不需要 Web UI 时可以关闭 dashboard：

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  --set dashboard.enabled=false

HPA、ServiceMonitor 与 NetworkPolicy

hpa:
  enabled: false

serviceMonitor:
  enabled: false

networkPolicies:
  enabled: true

只有在集群已安装 Prometheus Operator CRD 时，才开启 serviceMonitor.enabled。HPA 默认关闭；启用前请确认集群有 metrics-server，并且已经验证过数据面的资源 requests。

常见覆盖

需要保留的修改请写入 values 文件：

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  -f my-values.yaml

私有镜像仓库和副本数覆盖示例：

global:
  imageRegistry: "registry.example.com"
  imagePullSecrets:
    - name: registry-credentials

dataplane:
  replicas: 4

常见安装场景

平台统一管理 Gateway API CRD

当平台已经在集群引导阶段统一安装 CRD 时，使用：

gatewayAPI:
  installCRDs: false
  channel: standard

这样应用 release 就不会再次碰集群级 CRD，职责边界更清晰。

Chart 管理 Standard Gateway API CRD

当你希望由 chart 负责安装 standard Gateway API CRD bundle 时，使用：

gatewayAPI:
  installCRDs: true
  channel: standard

这对一次性测试集群和小型环境很方便，但要记住 CRD 属于集群级资源。

关闭 Dashboard

如果你只需要控制面和数据面，可以关闭 dashboard 工作负载：

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  --set dashboard.enabled=false

Experimental Gateway Runtime 与 AI Gateway

实验性 Gateway runtime 行为由 featureMode 控制。AI Gateway 仍是显式的控制面功能，并且需要 experimental 模式：

featureMode: experimental
gatewayAPI:
  installCRDs: true
  channel: experimental
controlplane:
  config:
    features:
      enableAiGateway: true

gatewayAPI.installCRDs 和 gatewayAPI.channel 只控制 CRD 渲染。当需要由 Chart 渲染官方 experimental Gateway API CRD bundle 时，使用 gatewayAPI.channel: experimental。

完整的启动、CRD 和验证流程见实验功能。

Helm Test 与清理行为

chart 默认会渲染 Helm test hook：

tests:
  enabled: true
  image:
    repository: "public.ecr.aws/docker/library/busybox"
    tag: "1.36.1"
    pullPolicy: IfNotPresent

在安装或升级后执行：

helm test nantian-gw --namespace nantian-gw

这个 hook 会使用托管在 Amazon ECR Public 上的轻量 BusyBox 镜像去检查网关健康端点。如果你的集群不能直接拉这个公共镜像源，请通过 tests.image.repository、tests.image.tag 和 tests.image.pullPolicy 覆盖到内网镜像源或其他兼容镜像。

chart 的 hook 策略会在重新创建前删除旧测试 Pod，并在测试成功或失败后自动清理。因此重复执行 helm test、卸载 release 或重新尝试时，不应遗留陈旧的失败 hook Pod。

验证 Release

kubectl get pods -n nantian-gw
kubectl get gatewayclass nantian-gw
kubectl get svc -n nantian-gw
helm status nantian-gw -n nantian-gw
helm test nantian-gw --namespace nantian-gw

如果数据面没有就绪，请检查它是否能连接 nantian-gw-controlplane-grpc:18080；如果启用了 xDS TLS，还要确认相关 TLS 配置一致；然后再查看控制面和数据面日志。

升级与卸载

升级已有 release：

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  -f my-values.yaml

删除 release：

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

Helm uninstall 会删除 chart 管理的资源。Gateway API CRD 和你在 chart 外创建的应用资源不会被 chart uninstall 删除。