Gateway API Helm 公网入口 Runbook

最后更新：2026-05-11

本文档说明如何为 Helm in-cluster 部署启用 publicAccess.provider=gatewayapi。

当前范围覆盖：

Phase 1：vCluster control plane 替代入口
- shared Gateway + TLSRoute 控制面 passthrough
Phase 2：KubeBYON 平台 API 替代入口（可选）
- 独立 platform Gateway + HTTPRoute
- 默认路由 /api 前缀与 /healthz
Phase 3：KubeBYON web / Next.js 控制台 in-cluster Helm 部署（可选）
- 与平台 API 复用同一个 hostname
- /api 前缀与 /healthz 继续转发到 API
- / 转发到 web Service（3000）
Phase 4B：workload edge shared Gateway（可选）
- 独立 workload Gateway
- kubebyon-api 内的 runtime syncer 会为每个 cluster 维护 HTTPRoute + Service + EndpointSlice
- 默认优先走 Gateway -> shim Service -> EndpointSlice -> ingress controller PodIP:80
- 若当前宿主拓扑或可达性不满足 PodIP 直连条件，再自动回退到宿主节点 IP + NodePort
Phase 5：workload edge HTTPS + cert-manager（可选）
- Helm chart 只保留 workload Gateway 基础对象与 HTTP:80 listener
- kubebyon-api 内的 runtime syncer 负责动态维护 workload HTTPS listener / redirect / Certificate
- platform-managed hostname 继续走共享 Certificate
- self-managed 外部 hostname 可选走独立 Certificate，并支持单独 issuerRef override
- dedicated self-managed HTTPS route 会在转发前把 Host 改写回 cluster 级 managed_workload_ingress_cname_target

当前仍不覆盖：

控制台站点、平台 API 与 control plane 共用同一个 Gateway 对象
controller-specific 的共享地址 / 共享 data plane 调优
更完整的证书可视化、配额与策略产品化

1. 为什么需要额外前置条件

当你把 Helm values 切到：

publicAccess:
  provider: gatewayapi

chart 会：

不再部署 haproxy sidecar
不再挂载 runtime/haproxy 与 start-haproxy.sh
为 kubebyon-api 注入 Gateway API 相关 env（多机时 kubebyon-worker 也会收到 control-plane shared Gateway 基础 env）
创建一个 control plane shared Gateway（gateway.networking.k8s.io/v1）
如启用 gatewayAPI.platform.enabled=true，再额外创建 platform Gateway + HTTPRoute
如再启用 web.enabled=true，会额外创建 web Deployment + Service，并在 platform HTTPS listener 上新增 / 路由
如再启用 gatewayAPI.workload.enabled=true，会额外创建独立 workload Gateway
如同时启用 gatewayAPI.workload.tls.enabled=true，chart 仍只渲染基础 HTTP:80 listener；kubebyon-api runtime syncer 会在同一 Gateway 上动态维护 HTTPS listener
如再启用 gatewayAPI.workload.certManager.enabled=true，runtime syncer 会在 gateway namespace 动态维护 platform-managed 共享 Certificate，并可选为 self-managed 外部 hostname 维护独立 Certificate

但 Gateway controller / CRD 本身不由 KubeBYON chart 安装，需要你预先准备。

此外，control plane passthrough 依赖 TLSRoute，因此通常需要 Gateway API experimental bundle。

2. 安装 Gateway API CRD

官方 Gateway API 文档当前（2026-04-29）给出的 experimental bundle 示例：

kubectl apply --server-side -f \
  https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml

安装后确认至少存在：

kubectl get crd gateways.gateway.networking.k8s.io
kubectl get crd httproutes.gateway.networking.k8s.io
kubectl get crd tlsroutes.gateway.networking.k8s.io

说明：Gateway / HTTPRoute 属于标准资源，但当前 provider 仍依赖 TLSRoute 承接 control plane passthrough，所以这里继续推荐 experimental bundle。

3. 安装 Gateway controller（推荐 Envoy Gateway）

推荐示例使用 Envoy Gateway。

官方 Envoy Gateway 文档中的 Helm 安装示例（截至 2026-04-29）：

helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.7.1 \
  -n envoy-gateway-system \
  --create-namespace

等待 controller Ready：

kubectl wait --timeout=5m \
  -n envoy-gateway-system \
  deployment/envoy-gateway \
  --for=condition=Available

确认默认 GatewayClass：

kubectl get gatewayclass

常见情况下可以看到：

eg

如果你的 controller 暴露方式不是默认 eg，请在 Helm values 里覆盖 gatewayAPI.gatewayClassName，或单独覆盖 gatewayAPI.platform.gatewayClassName / gatewayAPI.workload.gatewayClassName。

如果集群没有 LoadBalancer 实现，Envoy Gateway 官方 quickstart 也建议先准备一个可分配地址的方案，例如 MetalLB。

3.1 安装 cert-manager（仅在启用 workload HTTPS / 自动签发时需要）

如果你计划启用：

gatewayAPI.workload.tls.enabled=true
gatewayAPI.workload.certManager.enabled=true 或
gatewayAPI.workload.certManager.selfManaged.enabled=true

则需要预先安装 cert-manager，并自行准备好对应的 Issuer / ClusterIssuer。

示例：

helm repo add jetstack https://charts.jetstack.io --force-update
helm repo update

helm install cert-manager jetstack/cert-manager \
  -n cert-manager \
  --create-namespace \
  --set crds.enabled=true

然后确认：

kubectl -n cert-manager get pods
kubectl get crd certificates.cert-manager.io
kubectl get clusterissuer,issuer -A

当前这份 chart 不会替你安装 Issuer / ClusterIssuer，也不会替你写 DNS provider 凭据。

当前 workload HTTPS 的 cert-manager 模式分两类：

platform-managed：由 kubebyon-api runtime syncer 动态维护一个共享 Certificate，把 cluster 级 managed_workload_ingress_cname_target 与落在 managed_workload_ingress_base_domain 下的 hostname bindings 聚合进 SAN

self-managed：可选为外部 hostname 维护独立 Certificate；若 selfManaged.issuerRef 留空，则回退到 gatewayAPI.workload.certManager.issuerRef

因此如果你的 issuer 需要 DNS provider 凭据（常见于 DNS-01），仍需你自行准备。

4. 在 KubeBYON Helm values 中启用 provider

4.1 单机 chart：仅启用 control plane 替代

publicAccess:
  provider: gatewayapi

gatewayAPI:
  gatewayClassName: eg
  namespace: ""
  name: ""
  listenerName: control-plane
  syncIntervalSeconds: 10

4.2 单机 chart：额外启用平台 API Gateway（Phase 2 兼容）

publicAccess:
  provider: gatewayapi

gatewayAPI:
  gatewayClassName: eg
  listenerName: control-plane
  syncIntervalSeconds: 10
  platform:
    enabled: true
    hostname: api.kubebyon.example.com
    tlsSecretName: kubebyon-platform-tls
    httpToHttpsRedirect: true

4.3 单机 chart：启用平台 API + in-cluster web（Phase 3 推荐）

publicAccess:
  provider: gatewayapi

gatewayAPI:
  gatewayClassName: eg
  listenerName: control-plane
  syncIntervalSeconds: 10
  platform:
    enabled: true
    hostname: kubebyon.example.com
    tlsSecretName: kubebyon-platform-tls
    httpToHttpsRedirect: true

web:
  enabled: true
  image:
    repository: kubebyon-web
    tag: helm-test
    pullPolicy: IfNotPresent
  service:
    create: true
    port: 3000
  env:
    # 留空时默认走 in-cluster API Service。
    apiBaseURL: ""
    # 同 host 路由时通常保持留空，让浏览器继续访问当前站点 /api。
    nextPublicAPIBaseURL: ""
    # 留空时默认注入 0.0.0.0。
    hostname: ""

4.4 多机 chart：启用平台 API + in-cluster web（Phase 3 推荐）

publicAccess:
  provider: gatewayapi

gatewayAPI:
  gatewayClassName: eg
  listenerName: control-plane
  syncIntervalSeconds: 10
  platform:
    enabled: true
    hostname: kubebyon.example.com
    tlsSecretName: kubebyon-platform-tls
    httpToHttpsRedirect: true

web:
  enabled: true
  image:
    repository: kubebyon-web
    tag: helm-test
    pullPolicy: IfNotPresent
  service:
    create: true
    port: 3000
  env:
    apiBaseURL: ""
    # 同 host 路由时通常保持留空，让浏览器继续访问当前站点 /api。
    nextPublicAPIBaseURL: ""
    hostname: ""

4.4.1 多机 chart：`gatewayAPI.addressMode=single`（推荐示例）

适用场景：

你希望 control-plane / platform / workload 默认共用同一类 Gateway data plane
Gateway controller 侧只准备了一个公网入口、一个共享 address pool，或一个共享 GatewayClass
你想先以“单公网 IP / 共享入口”方式最小落地，再按需拆分 workload

publicAccess:
  provider: gatewayapi

gatewayAPI:
  # multi-node chart 默认 dual；这里显式切到 single。
  addressMode: single
  # shared 为空时，single 模式最终回退到这里。
  gatewayClassName: eg
  gatewayClassProfiles:
    shared: eg
    edge: ""
    workload: ""
  listenerName: control-plane
  platform:
    enabled: true
    hostname: kubebyon.example.com
    tlsSecretName: kubebyon-platform-tls
  workload:
    enabled: true
    nodeAddressType: internal

解析结果：

control-plane：默认走 gatewayClassProfiles.shared
platform：默认走 gatewayClassProfiles.shared
workload：默认走 gatewayClassProfiles.shared
若 shared 留空：三者统一回退到 gatewayAPI.gatewayClassName

4.4.2 多机 chart：`gatewayAPI.addressMode=dual`（推荐示例，默认）

适用场景：

你希望 control-plane / platform 与 workload 默认分层
controller 侧已经为“平台入口”和“workload 入口”准备了不同 GatewayClass、不同 address pool，或不同 data plane
你希望 platform/control-plane 与 workload 默认具有更清晰的回滚和容量边界

publicAccess:
  provider: gatewayapi

gatewayAPI:
  addressMode: dual
  # edge / workload profile 留空时，最终回退到这里。
  gatewayClassName: eg
  gatewayClassProfiles:
    shared: ""
    edge: eg-public
    workload: eg-workload
  listenerName: control-plane
  platform:
    enabled: true
    hostname: kubebyon.example.com
    tlsSecretName: kubebyon-platform-tls
  workload:
    enabled: true
    nodeAddressType: internal

解析结果：

control-plane：默认走 gatewayClassProfiles.edge
platform：默认走 gatewayClassProfiles.edge
workload：默认走 gatewayClassProfiles.workload
若 edge 或 workload 留空：对应角色再回退到 gatewayAPI.gatewayClassName

4.4.3 GatewayClass profile 语义、override 优先级与运维前提（示例仍以多机 chart 为主）

gatewayAPI.addressMode 当前在 single-node / multi-node chart 中都支持：

single：默认把 control-plane / platform / workload 都映射到 shared
dual：默认把 control-plane / platform 映射到 edge，workload 映射到 workload
默认值：dual

gatewayAPI.gatewayClassProfiles.* 语义：

shared：single 模式下的统一入口 profile
edge：dual 模式下 control-plane / platform 默认使用的入口 profile
workload：dual 模式下 workload 默认使用的入口 profile

显式 override 优先级仍保持不变：

gatewayAPI.platform.gatewayClassName
gatewayAPI.workload.gatewayClassName
若未显式 override，则按 addressMode 选择 gatewayClassProfiles.*
若选中的 profile 为空，则最终回退到 gatewayAPI.gatewayClassName

运维前提与兼容说明：

这些规则会影响 single-node / multi-node chart 中 control-plane / platform / workload Gateway 默认解析到哪个 GatewayClass
chart 仍会创建独立的 control-plane / platform / workload Gateway 对象；addressMode 不会把它们合并成一个 Gateway
“single / dual 公网 IP”是接入规划语义，不保证一定只会实际消耗 1 个或 2 个公网 IP
最终是否共享地址、共享 data plane、共享 LoadBalancer，取决于你的 Gateway controller / 云厂商 LB / address pool 配置
如果你计划走 single，请先确认 controller 支持让这些 Gateway 通过同一类 GatewayClass 或同一 address pool 共享入口
如果你计划走 dual，请先确认 edge 与 workload 对应的 GatewayClass / address pool 已存在，并且各自的 listener / 证书 / DNS 运维边界可接受

提示：本节示例主要以 multi-node chart 展开，但当前 single-node chart 也已经引入相同的 gatewayAPI.addressMode / gatewayAPI.gatewayClassProfiles.* 解析语义；若需要查看单机场景下的字段约束与默认值，可结合 deploy-kubebyon-backend-helm.md 一起使用。

4.5 单机 chart：额外启用 workload edge shared Gateway（HTTP 最小版）

publicAccess:
  provider: gatewayapi

gatewayAPI:
  gatewayClassName: eg
  listenerName: control-plane
  workload:
    enabled: true
    gatewayClassName: ""
    namespace: ""
    name: ""
    listenerName: ""
    nodeAddressType: internal

4.6 多机 chart：额外启用 workload edge shared Gateway（HTTP 最小版）

publicAccess:
  provider: gatewayapi

gatewayAPI:
  gatewayClassName: eg
  listenerName: control-plane
  workload:
    enabled: true
    gatewayClassName: ""
    namespace: ""
    name: ""
    listenerName: ""
    nodeAddressType: internal

4.7 workload edge HTTPS + cert-manager（runtime-managed：共享 + self-managed 独立证书接线）

publicAccess:
  provider: gatewayapi

gatewayAPI:
  gatewayClassName: eg
  listenerName: control-plane
  workload:
    enabled: true
    # HTTP listener 名称；留空时默认 workload-http。
    listenerName: ""
    nodeAddressType: internal
    tls:
      enabled: true
      # 留空时默认 <release>-kubebyon-workload-tls。
      secretName: ""
      httpToHttpsRedirect: true
      httpListenerName: ""
      httpsListenerName: ""
    certManager:
      # 默认 issuerRef；platform-managed shared Certificate 与 self-managed 独立 Certificate
      # 默认都会复用它。
      issuerRef:
        name: letsencrypt-dns
        kind: ClusterIssuer
        group: cert-manager.io
      # platform-managed hostname 的共享 Certificate 开关。
      enabled: true
      selfManaged:
        # self-managed 外部 hostname 的独立 Certificate 开关。
        enabled: true
        issuerRef:
          # 可选 override；留空时继承上面的 certManager.issuerRef。
          name: letsencrypt-external
          kind: ClusterIssuer
          group: cert-manager.io

说明：

上面这个方案不会在 Helm 里静态声明 Certificate 的 SAN，也不会在 chart 中静态列出 workload HTTPS listeners

Helm render 当前只保留 workload Gateway 的 HTTP:80 listener；HTTPS listener / redirect / Certificate 都由 kubebyon-api runtime syncer 动态维护

platform-managed 共享 Certificate 仍只会把 cluster 级 managed_workload_ingress_cname_target 与平台可托管 hostname bindings 聚合进 SAN

self-managed 外部 hostname 若启用独立 cert-manager，会使用 selfManaged.issuerRef（若留空则回退到 certManager.issuerRef）

字段说明：

gatewayAPI.gatewayClassName：兼容兜底的默认 GatewayClass；在 single-node / multi-node chart 中，当 addressMode 选中的 profile 为空时，control-plane / platform / workload 都会最终回退到这里
gatewayAPI.addressMode：single / dual；当前 single-node / multi-node chart 默认都为 dual
gatewayAPI.gatewayClassProfiles.shared：single 模式下 control-plane / platform / workload 共用的默认 profile
gatewayAPI.gatewayClassProfiles.edge：dual 模式下 control-plane / platform 默认使用的 profile
gatewayAPI.gatewayClassProfiles.workload：dual 模式下 workload 默认使用的 profile
gatewayAPI.namespace / gatewayAPI.name / gatewayAPI.listenerName：control plane shared Gateway 元数据
gatewayAPI.platform.enabled：是否额外创建平台站点专用 Gateway / HTTPRoute
gatewayAPI.platform.gatewayClassName：platform GatewayClass 显式 override；留空时，single-node / multi-node chart 都会先按 addressMode 选择 profile，再回退 gatewayAPI.gatewayClassName
gatewayAPI.platform.namespace：留空时继承 gatewayAPI.namespace / release namespace
gatewayAPI.platform.name：留空时默认 <release>-kubebyon-platform-gateway
gatewayAPI.platform.hostname：平台站点对外域名；启用时必填
gatewayAPI.platform.tlsSecretName：platform HTTPS listener 所用证书 Secret 名称；启用时必填
gatewayAPI.platform.httpToHttpsRedirect：是否同时创建 HTTP:80 -> HTTPS:443 redirect route
gatewayAPI.workload.enabled：是否额外创建独立 workload edge shared Gateway
gatewayAPI.workload.gatewayClassName：workload GatewayClass 显式 override；留空时，single-node / multi-node chart 都会先按 addressMode 选择 profile，再回退 gatewayAPI.gatewayClassName
gatewayAPI.workload.namespace：留空时继承 gatewayAPI.namespace / release namespace
gatewayAPI.workload.name：留空时默认 <release>-kubebyon-workload-gateway
gatewayAPI.workload.listenerName：workload HTTP listener 名称；留空时默认 workload-http
gatewayAPI.workload.nodeAddressType：runtime syncer 解析 workload Node 地址时的优先级，支持 internal / external
gatewayAPI.workload.tls.enabled：是否允许 runtime syncer 在 workload Gateway 上动态维护 HTTPS listener / route / Certificate
gatewayAPI.workload.tls.secretName：platform-managed shared HTTPS listener / shared Certificate 使用的 Secret 元数据；留空时默认 <release>-kubebyon-workload-tls
gatewayAPI.workload.tls.httpToHttpsRedirect：是否额外创建 HTTP:80 -> HTTPS:443 redirect route
gatewayAPI.workload.tls.httpListenerName / gatewayAPI.workload.tls.httpsListenerName：分别是 HTTP listener 与 platform-managed shared HTTPS listener 的元数据名；留空时默认 workload-http / workload-https
gatewayAPI.workload.certManager.issuerRef.*：workload cert-manager 的默认 Issuer / ClusterIssuer 引用；shared / self-managed 默认都可复用它
gatewayAPI.workload.certManager.enabled：是否让 runtime syncer 动态维护 platform-managed hostname 的共享 cert-manager Certificate
gatewayAPI.workload.certManager.selfManaged.enabled：是否允许 runtime syncer 为 self-managed 外部 hostname 动态维护独立 Certificate
gatewayAPI.workload.certManager.selfManaged.issuerRef.*：self-managed 独立 Certificate 的可选 issuerRef override；留空时回退到 gatewayAPI.workload.certManager.issuerRef.*
web.enabled：是否额外创建 in-cluster web Deployment / Service，并在同 host 的 HTTPS listener 上路由 /
web.service.create：web.enabled=true 时必须保持 true
web.env.apiBaseURL：web 容器内 server-side 请求使用的后端基地址；留空时 chart 默认回落到 in-cluster API Service
web.env.nextPublicAPIBaseURL：single-node / multi-node chart 都提供；浏览器必须直连不同 origin API 时再配置，同 host 路由场景通常保持留空

single-node / multi-node chart 中，control-plane Gateway 现在都会通过 helper 按 addressMode + gatewayClassProfiles.* 解析默认 GatewayClass；不再只依赖模板里直接读取 gatewayAPI.gatewayClassName。

约束：web.enabled=true 时，chart 会校验 gatewayAPI.platform.enabled=true 且 web.service.create=true。

约束：gatewayAPI.workload.enabled=true 时，chart 会校验 publicAccess.provider=gatewayapi，并要求 workload Gateway 与 control-plane / platform Gateway 不同名。

约束：gatewayAPI.workload.certManager.enabled=true 时，chart 会要求 gatewayAPI.workload.tls.enabled=true，并要求填写 gatewayAPI.workload.certManager.issuerRef.name。

约束：gatewayAPI.workload.certManager.selfManaged.enabled=true 时，chart 会要求 gatewayAPI.workload.tls.enabled=true，并要求：

gatewayAPI.workload.certManager.issuerRef.name 或

gatewayAPI.workload.certManager.selfManaged.issuerRef.name 至少配置一个

约束：gatewayAPI.workload.tls.enabled=true 时，chart 会要求：

httpListenerName 与 httpsListenerName 必须不同

runtime-managed shared HTTPS listener 的 Secret 元数据来自 gatewayAPI.workload.tls.secretName（留空则走默认值）

5. Chart 渲染结果与兼容性

5.1 `provider=haproxy`

保持现有兼容行为：

渲染 haproxy sidecar
渲染 start-haproxy.sh ConfigMap 内容
渲染 haproxy-runtime volume / mounts
API Pod 继续占用 hostNetwork:443（若 hostNetwork=true）

5.2 `provider=gatewayapi`

切换后的 control plane 行为：

不再渲染 haproxy sidecar
不再渲染 start-haproxy.sh ConfigMap 内容
不再渲染 haproxy-runtime volume / mounts
新增 control plane shared Gateway 资源
listener 固定为：
- protocol: TLS
- port: 443
- tls.mode: Passthrough
- allowedRoutes.namespaces.from: All
- allowedRoutes.kinds: TLSRoute
kubebyon-api（多机时也包含 kubebyon-worker）会收到：
- KUBEBYON_GATEWAY_API_GATEWAY_NAMESPACE
- KUBEBYON_GATEWAY_API_GATEWAY_NAME
- KUBEBYON_GATEWAY_API_LISTENER_NAME
- KUBEBYON_GATEWAY_API_SYNC_INTERVAL_SECONDS

5.3 `gatewayAPI.platform.enabled=true`

额外新增的平台站点行为：

创建一个独立的 platform Gateway
- 默认名字：<release>-kubebyon-platform-gateway
- HTTPS:443 listener 负责 TLS terminate
- 可选 HTTP:80 listener 负责 redirect
创建一个 platform API HTTPRoute
- host 固定为 gatewayAPI.platform.hostname
- 默认匹配 PathPrefix /api 与 Exact /healthz
- backend 指向 kubebyon-api Service 的 8080
若 web.enabled=true，再额外创建一个 platform web HTTPRoute
- 匹配 PathPrefix /
- backend 指向 web Service 的 3000
同一 hostname 下，/api 前缀与 Exact /healthz 会因更具体的 Gateway API 路径匹配优先进入 API，/ 只兜底 web 站点流量
如果 httpToHttpsRedirect=true
- web.enabled=false 时：仅 /api 与 /healthz 会被 302 重定向到 HTTPS
- web.enabled=true 时：redirect 扩展为覆盖 /，也就是同 host 的所有普通站点路径都会被重定向到 HTTPS

兼容性说明：当前实现对 platform Gateway 的 RequestRedirect.statusCode 使用 302。我们在 Envoy Gateway 环境中验证过 308 可能被 controller 拒绝，而 302 可正常工作； workload edge runtime syncer 当前也同样使用 302。

设计上这里故意不把平台 HTTPS listener 与 control plane TLS passthrough listener 混在同一个 Gateway 中，这样能避免不同 controller 对混合监听能力的兼容性差异，也保留了 control plane 与平台站点分层的第三阶段目标。

注意：gatewayAPI.platform.tlsSecretName 引用的 Secret 需要存在于 platform Gateway 所在 namespace。

5.4 `gatewayAPI.workload.enabled=true`

额外新增的 workload edge 行为：

创建一个独立的 workload shared Gateway
- 默认名字：<release>-kubebyon-workload-gateway
- Helm render 当前始终只保留 HTTP:80 listener
- tls.enabled=true 时，kubebyon-api runtime syncer 可在该 Gateway 上动态维护 HTTPS listener / redirect / Certificate
kubebyon-api 会额外收到 workload Gateway 运行时元数据：
- KUBEBYON_GATEWAY_API_WORKLOAD_GATEWAY_NAMESPACE
- KUBEBYON_GATEWAY_API_WORKLOAD_GATEWAY_NAME
- KUBEBYON_GATEWAY_API_WORKLOAD_LISTENER_NAME
- KUBEBYON_GATEWAY_API_WORKLOAD_HTTPS_LISTENER_NAME
- KUBEBYON_GATEWAY_API_WORKLOAD_TLS_SECRET_NAME
- KUBEBYON_GATEWAY_API_WORKLOAD_HTTP_TO_HTTPS_REDIRECT
- KUBEBYON_GATEWAY_API_WORKLOAD_CERT_MANAGER_ENABLED
- KUBEBYON_GATEWAY_API_WORKLOAD_CERT_MANAGER_ISSUER_NAME
- KUBEBYON_GATEWAY_API_WORKLOAD_CERT_MANAGER_ISSUER_KIND
- KUBEBYON_GATEWAY_API_WORKLOAD_CERT_MANAGER_ISSUER_GROUP
- KUBEBYON_GATEWAY_API_WORKLOAD_SELF_MANAGED_CERT_MANAGER_ENABLED
- KUBEBYON_GATEWAY_API_WORKLOAD_SELF_MANAGED_CERT_MANAGER_ISSUER_NAME
- KUBEBYON_GATEWAY_API_WORKLOAD_SELF_MANAGED_CERT_MANAGER_ISSUER_KIND
- KUBEBYON_GATEWAY_API_WORKLOAD_SELF_MANAGED_CERT_MANAGER_ISSUER_GROUP
- KUBEBYON_GATEWAY_API_WORKLOAD_NODE_ADDRESS_TYPE
- KUBEBYON_GATEWAY_API_WORKLOAD_BACKEND_STRATEGY
- KUBEBYON_GATEWAY_API_WORKLOAD_PODCIDR_ROUTE_ENABLED
- KUBEBYON_GATEWAY_API_WORKLOAD_PODCIDR_ROUTE_MODE
- KUBEBYON_GATEWAY_API_WORKLOAD_ROUTE_PLAN_NAMESPACE
- KUBEBYON_GATEWAY_API_WORKLOAD_ROUTE_TARGET_NODE_SELECTOR
- KUBEBYON_GATEWAY_API_WORKLOAD_ROUTE_STALE_AFTER_SECONDS
- KUBEBYON_GATEWAY_API_WORKLOAD_ROUTE_COMMAND_TIMEOUT_SECONDS
- KUBEBYON_GATEWAY_API_WORKLOAD_ROUTE_SYNC_INTERVAL_SECONDS
当前 workload edge syncer 运行在 kubebyon-api 进程中，不运行在 worker 中
runtime syncer 会按 cluster 在宿主 namespace 中维护：
- HTTPRoute
- Service
- EndpointSlice 并把：
- cluster 级 managed_workload_ingress_cname_target
- cluster hostname bindings 挂到该 workload Gateway 上的 HTTPRoute
这些路由会先进入同 namespace 的 shim Service
- 若当前宿主机已具备到目标 vCluster PodCIDR 的路由，且 host network 到 ingress PodIP:80 可达，则 EndpointSlice 会直接指向托管 ingress controller 的 PodIP:80
- 否则 runtime syncer 会自动回退到宿主节点 IP + NodePort
PodCIDR 路由收敛支持：
- gatewayAPI.workload.podCIDRRoute.mode=local：API 进程本地同步宿主路由
- gatewayAPI.workload.podCIDRRoute.mode=routeagent：chart 额外部署 kubebyon-route-agent DaemonSet，由 API 维护 RoutePlan CR，agent 在各宿主节点本机应用路由
若 gatewayAPI.workload.tls.enabled=true
- chart 只保留 HTTP:80 listener，并把 HTTPS listener / TLS secret 元数据下发给 kubebyon-api
- runtime syncer 会继续在 HTTP listener 上维护 HTTP backend route
- 会在 runtime-managed HTTPS listener 上为“已纳入 HTTPS 证书编排范围的 hostname”额外维护 HTTPS backend route
- 若 httpToHttpsRedirect=true，runtime syncer 还会只为这些 hostname 额外挂 HTTP -> HTTPS redirect route
若 gatewayAPI.workload.certManager.enabled=true
- chart 只负责把 issuerRef、secretName 等静态元数据传给 kubebyon-api
- 共享 Certificate 会由 runtime syncer 在 workload Gateway namespace 动态创建 / 更新 / 清理
- 当前最小范围只会把 managed_workload_ingress_cname_target 与落在 managed_workload_ingress_base_domain 下的 hostname bindings 聚合进 SAN
- self-managed 外部 hostname 不会自动纳入这个共享 Certificate
若 gatewayAPI.workload.certManager.selfManaged.enabled=true
- runtime syncer 可为 self-managed 外部 hostname 额外维护独立 Certificate
- 若 selfManaged.issuerRef 留空，则回退到 gatewayAPI.workload.certManager.issuerRef
- dedicated self-managed HTTPS backend route 还会额外挂 URLRewrite.hostname=<managed_workload_ingress_cname_target>，保证请求转发到 vCluster 托管 ingress controller 前，Host 能回到 cluster 的 canonical target

另外，hostname binding 的公网 DNS 最终状态当前按“canonical target”语义判定：

直接 CNAME -> managed_workload_ingress_cname_target
或先 CNAME -> managed_workload_ingress_cname_target，再继续解析到同一个最终 canonical name

这两种情况都会被视为 status=ready。

因此，Gateway API provider 当前有三条独立链路：

control-plane Gateway：TLSRoute passthrough -> vCluster API
platform Gateway：平台 hostname 下 /api、/healthz、可选 /
workload Gateway：Helm 提供基础 Gateway + HTTP listener，runtime syncer 动态编排 workload hostname / CNAME target 的 HTTPS edge 与证书

是否需要额外公网 IP 取决于 Gateway controller 的地址分配模型。当前 chart 会创建独立的 Gateway 对象；很多基于 LoadBalancer 的 controller 默认会给每个 Gateway 分配独立地址，因此在默认配置下 workload Gateway 可能额外占用一个公网 IP。若 controller 支持共享地址 / 共享 data plane，需要结合对应产品能力单独配置。

5.5 web Dockerfile 与运行时 env 建议

当前仓库里的 web/Dockerfile 是一个三阶段构建：

deps：执行 npm ci
builder：执行 npm run build，读取仓库根目录的 docs/ 并导出静态站点
runner：复制静态输出并通过 Nginx 提供服务

本地或远程构建示例：

docker build -f web/Dockerfile -t kubebyon-web:helm-test .

推荐用法：

KUBEBYON_API_BASE_URL
- 优先用于 server-side / SSR / route handler 访问后端
- Phase 3 同 host 路由场景下，推荐留空交给 chart 默认值，或显式设成 in-cluster API Service
NEXT_PUBLIC_KUBEBYON_API_BASE_URL
- 只在浏览器必须直连不同 origin 的 API 时再设置
- 如果平台 hostname 已经由 Gateway API 同时承接 /api 与 /，通常应保持留空，让浏览器继续访问当前站点的 /api

说明：当前 web/Dockerfile 本身没有额外声明自定义 build args；Phase 3 推荐主要依赖 Gateway API 同 host /api 路由与容器运行时 env，而不是把外部 API 地址硬编码进前端构建产物。

6. 安装后检查

假设 release namespace 为 kubebyon-system：

6.1 检查 control plane Gateway

kubectl -n kubebyon-system get gateway
kubectl -n kubebyon-system describe gateway <control-plane-gateway-name>

重点确认：

Accepted=True
Programmed=True（或 controller 对等状态）
listener 名称与 gatewayAPI.listenerName 一致

6.2 检查平台 Gateway / Route（若启用）

kubectl -n kubebyon-system get gateway <platform-gateway-name>
kubectl -n kubebyon-system get httproute
kubectl -n kubebyon-system describe httproute <platform-api-route-name>

重点确认：

platform Gateway 的 HTTPS listener 已被 controller 接受
HTTPRoute 的 ResolvedRefs=True
HTTPRoute 的 Accepted=True
TLS Secret 名称拼写正确且位于 platform Gateway namespace
若启用 web.enabled=true，还应能看到额外的 platform web HTTPRoute

如果启用了 web.enabled=true，建议再检查：

kubectl -n kubebyon-system get deploy,svc | rg 'kubebyon-web|web'
kubectl -n kubebyon-system describe httproute <platform-web-route-name>

6.3 检查 API / worker 环境变量

kubectl -n kubebyon-system get pod -l app.kubernetes.io/name=kubebyon -o yaml | rg 'KUBEBYON_GATEWAY_API_'

如果是多机模式，也可以检查 worker：

kubectl -n kubebyon-system get deploy -o yaml | rg 'KUBEBYON_GATEWAY_API_'

说明：

worker 会收到 control-plane shared Gateway 的基础 env
workload Gateway 相关 env 只注入 kubebyon-api

6.4 功能性验证（平台 hostname）

curl -I http://kubebyon.example.com/
curl -k https://kubebyon.example.com/
curl -k https://kubebyon.example.com/healthz
curl -k https://kubebyon.example.com/api/auth/providers

预期：

若开启 httpToHttpsRedirect=true
- web.enabled=true 时，第一个请求应返回 302
- web.enabled=false 时，应改为验证 http://<hostname>/healthz 或 /api/... 返回 302
web.enabled=true 时，/ 会进入 web
/healthz 会被转发到 kubebyon-api
/api 前缀会进入平台 API

6.5 检查 workload Gateway / HTTPRoute / Certificate（若启用）

kubectl -n <workload-gateway-namespace> get gateway <workload-gateway-name>
kubectl -n <workload-gateway-namespace> describe gateway <workload-gateway-name>
kubectl -n <workload-gateway-namespace> get certificate
kubectl get httproute -A
kubectl get httproute,svc,endpointslice -A -l 'app.kubernetes.io/managed-by=kubebyon,kubebyon.app/gateway-api-sync-kind=workload-edge'

重点确认：

workload Gateway 为独立对象
tls.enabled=false 时，listener 为 HTTP:80
tls.enabled=true 时，Helm render 仍只保留 HTTP:80 listener；待 runtime syncer 收敛后，Gateway 上应出现对应的 runtime-managed HTTPS listener
若启用 certManager.enabled=true
- 能看到 runtime syncer 动态创建的共享 Certificate
- Certificate.status.conditions[Ready=True]
- 生成的 Secret 位于 workload Gateway namespace，且名称与 gatewayAPI.workload.tls.secretName（或默认值）一致
若启用 certManager.selfManaged.enabled=true
- 对应 self-managed 外部 hostname 应出现额外的独立 Certificate
- 若显式设置 selfManaged.issuerRef，其独立证书应使用 override 后的 issuer；否则回退到默认 certManager.issuerRef
若启用 httpToHttpsRedirect=true
- 能看到 runtime syncer 额外创建的 redirect HTTPRoute
- curl -I http://<已纳入 HTTPS 证书编排范围的 hostname>/ 返回 302
当 cluster 已生成 managed_workload_ingress_cname_target 或配置了 hostname bindings 后，runtime syncer 会在对应 cluster 的宿主 namespace 中动态创建 / 更新 HTTPRoute、Service 与 EndpointSlice
HTTPRoute 的 hostnames 应覆盖 cluster 级 CNAME target 与已绑定 hostname，backend 指向同 namespace 的 shim Service
若启用 certManager.enabled=true 或 certManager.selfManaged.enabled=true，还应能看到：
- HTTP backend route：继续承接未纳入 HTTPS 证书编排范围的 hostname
- HTTPS backend route：只承接已纳入 HTTPS 证书编排范围的 hostname
- redirect route（若启用）：也只覆盖已纳入 HTTPS 证书编排范围的 hostname
检查 shim Service / EndpointSlice 注解：
- kubebyon.app/workload-edge-backend-mode=podip|nodeport
- kubebyon.app/workload-edge-backend-port
- kubebyon.app/workload-edge-backend-source
若当前是 podip 模式：
- EndpointSlice.endpoints[].addresses 应直接是托管 ingress controller 的 PodIP
- 端口应为 ingress controller HTTP targetPort（当前通常是 80）
若当前回退到 nodeport 模式：
- EndpointSlice.endpoints[].addresses 会是宿主节点地址
- 端口会对应目标 vCluster 内托管 ingress controller 的 NodePort
platform-managed 共享 Certificate 只会把 managed_workload_ingress_cname_target 与平台可托管 hostname bindings 聚合进 SAN；self-managed 外部 hostname 若启用独立 cert-manager，则应看到额外独立证书
对 self-managed 外部 hostname：
- 应看到 dedicated HTTPS listener
- 应看到 dedicated Certificate
- dedicated HTTPS HTTPRoute 上应出现 URLRewrite.hostname=<managed_workload_ingress_cname_target>
- curl -kI https://<self-managed-hostname>/ 应返回目标 workload 的正常响应

Gateway API Helm 公网入口 Runbook

1. 为什么需要额外前置条件

2. 安装 Gateway API CRD

3. 安装 Gateway controller（推荐 Envoy Gateway）

3.1 安装 cert-manager（仅在启用 workload HTTPS / 自动签发时需要）

4. 在 KubeBYON Helm values 中启用 provider

4.1 单机 chart：仅启用 control plane 替代

4.2 单机 chart：额外启用平台 API Gateway（Phase 2 兼容）

4.3 单机 chart：启用平台 API + in-cluster web（Phase 3 推荐）

4.4 多机 chart：启用平台 API + in-cluster web（Phase 3 推荐）

4.4.1 多机 chart：gatewayAPI.addressMode=single（推荐示例）

4.4.2 多机 chart：gatewayAPI.addressMode=dual（推荐示例，默认）

4.4.3 GatewayClass profile 语义、override 优先级与运维前提（示例仍以多机 chart 为主）

4.5 单机 chart：额外启用 workload edge shared Gateway（HTTP 最小版）

4.6 多机 chart：额外启用 workload edge shared Gateway（HTTP 最小版）

4.7 workload edge HTTPS + cert-manager（runtime-managed：共享 + self-managed 独立证书接线）

5. Chart 渲染结果与兼容性

5.1 provider=haproxy

5.2 provider=gatewayapi

5.3 gatewayAPI.platform.enabled=true

5.4 gatewayAPI.workload.enabled=true

5.5 web Dockerfile 与运行时 env 建议

6. 安装后检查

6.1 检查 control plane Gateway

6.2 检查平台 Gateway / Route（若启用）

6.3 检查 API / worker 环境变量

6.4 功能性验证（平台 hostname）

6.5 检查 workload Gateway / HTTPRoute / Certificate（若启用）

7. 推荐阅读

4.4.1 多机 chart：`gatewayAPI.addressMode=single`（推荐示例）

4.4.2 多机 chart：`gatewayAPI.addressMode=dual`（推荐示例，默认）

5.1 `provider=haproxy`

5.2 `provider=gatewayapi`

5.3 `gatewayAPI.platform.enabled=true`

5.4 `gatewayAPI.workload.enabled=true`