KubeBYON 托管业务流量入口（当前实现与后续规划）

最后更新：2026-05-11

本文档说明 托管业务流量入口 这一能力在当前版本里的真实实现、边界和后续演进方向。

请注意：

  • 控制面公网入口 与 业务流量入口 不是一回事
  • public_access_mode=nodeport | loadbalancer 解决的是 vCluster API / kubeconfig 的外部访问
  • managed_workload_ingress_enabled 解决的是 用户工作负载 HTTP/HTTPS 流量 的入口控制器准备工作

1. 当前已经落地的内容

当前分支已经完成 Phase 1 ~ Phase 4A，并补充了 Phase 4B / Phase 5 的最小版：

1.1 Phase 1：产品面与状态面

  • clusters 表新增：
    • managed_workload_ingress_enabled
    • managed_workload_ingress_status
    • managed_workload_ingress_class
    • managed_workload_ingress_last_error
  • 控制台 cluster 详情页支持：
    • 开启 / 关闭托管业务流量入口
    • 查看当前状态
    • 查看托管 IngressClass
    • 查看最近错误
  • API / 异步 worker 会把该配置作为 cluster 更新的一部分持久化并回写状态

1.2 Phase 2：真实 reconcile

当 managed_workload_ingress_enabled=true 时，后端会在：

  • ProvisionCluster
  • UpdateCluster

两个链路里，使用 vCluster internal REST config + Helm SDK 直接连接目标 vCluster，并在其中准备托管 ingress controller。

当前实现会：

  1. 检查目标 vCluster 内是否已存在健康的托管 ingress controller
  2. 若不存在或未就绪，则执行 Helm install / upgrade
  3. 若关闭该功能，则执行 uninstall，并额外做一次孤儿资源 cleanup

1.3 Phase 3：域名产品面

当前已经补充：

  • 全局系统设置 managed_workload_ingress_base_domain
  • console cluster 视图 / 详情只读字段 managed_workload_ingress_cname_target
  • hostname binding 的存储模型、HTTP API 与控制台 UI

这意味着：

  • 平台已经能给每个 cluster 暴露一个稳定的 CNAME target
  • 用户已经能在控制台维护自定义域名绑定记录
  • 平台已经能自动维护 platform-managed 范围内的 cluster 级 CNAME，以及落在该 base domain 下的 hostname binding CNAME
  • workload edge 也已经补上最小版 HTTPS / cert-manager 接线，但仍依赖正确的 Gateway API、DNS 和 cert-manager 配置

1.4 Phase 4A：平台自有 DNS 自动化（cluster 级）

当前已经补充：

  • 全局系统设置 managed_workload_ingress_dns
    • enabled
    • active_provider=cloudflare
    • record_target_hostname
    • cloudflare.zone_id
    • cloudflare.api_token
  • 后端会在 cluster 生命周期与 system settings 变更后，自动维护平台自有 Zone 下的 cluster 级 CNAME 记录
    • record name：managed_workload_ingress_cname_target
    • record target：managed_workload_ingress_dns.record_target_hostname

这意味着：

  • 平台现在已经能自动创建 / 更新 / 删除 cluster 级平台托管 CNAME
  • 若 hostname binding 也落在 managed_workload_ingress_base_domain 下，平台会 best-effort 自动维护该 binding 的 CNAME，使其指向对应 cluster 的 CNAME target
  • hostname binding 的 HTTP API / console 视图会返回只读 dns_management_scope，明确区分当前是 platform_managed 还是 self_managed
  • cluster 视图与 hostname binding 视图都会返回托管 DNS 自动化的结构化同步状态，分别通过 managed_workload_ingress_dns_status / managed_workload_ingress_dns_message 与 dns_management_status / dns_management_message 暴露，并补充最近成功同步时间与最近失败原因/时间
  • console / UI 当前会基于这些既有时间字段派生展示 cluster 级 / binding 级平台 DNS 自动化“已恢复（Recovered）”历史提示：最近成功同步时间 > 最近失败时间；这不是新增 API 字段，也不表示公网 DNS 最终解析已经恢复
  • hostname binding 创建表单当前会在 UI 层基于 cluster managed_workload_ingress_cname_target 反推 base domain，实时预览创建后预计属于 platform_managed 还是 self_managed；这只是前端预期展示，外部 hostname 仍然合法，只是 self_managed
  • 用户可以把自己的外部域名 CNAME 到这个 cluster 级 target
  • 但用户自己的外部 DNS Zone 仍然不会被平台代管
  • TLS、边缘网关完整产品化、L7 路由产品化仍未完成

1.5 Phase 4B / Phase 5：workload edge shared Gateway + HTTPS/cert-manager（最小版）

当前已经补充：

  • single-node / multi-node Helm chart 可选创建独立的 workload edge shared Gateway
  • 默认提供 HTTP:80
  • Helm chart 只保留 workload Gateway 基础对象与 HTTP:80 listener
  • HTTPS listener / redirect / Certificate 由 kubebyon-api runtime syncer 动态维护
  • kubebyon-api 内的 runtime syncer 会按 cluster 在宿主 namespace 中维护：
    • HTTPRoute
    • Service
    • EndpointSlice 并把：
    • cluster 级 managed_workload_ingress_cname_target
    • cluster 级 hostname bindings 挂到该 workload Gateway 上
  • HTTPRoute backend 先指向同 namespace 的 shim Service，再通过 EndpointSlice 转到实际后端
  • 当前实现优先使用 Gateway -> shim Service -> EndpointSlice -> ingress controller PodIP:80
  • 若当前宿主拓扑、PodCIDR 路由或 host network reachability 不满足直连条件，再自动回退到宿主节点 IP + NodePort
  • PodCIDR 路由收敛支持两种模式：
    • local：由 kubebyon-api 所在进程直接同步宿主路由，通常要求 API 具备 hostNetwork / NET_ADMIN 等权限
    • routeagent：由 API 维护 RoutePlan CR，宿主节点上的 kubebyon-route-agent DaemonSet 读取计划并在本节点执行路由变更；这是多宿主场景更推荐的路径
  • 若启用 cert-manager，kubebyon-api runtime syncer 还会在 workload Gateway namespace 动态维护：
    • 一个 platform-managed 共享 Certificate
      • 覆盖 cluster 级 managed_workload_ingress_cname_target
      • 以及 platform_managed hostname bindings
    • 以及可选的 self-managed 外部 hostname 独立 Certificate
      • 可选使用单独 issuerRef override
      • 未显式 override 时回退到 workload cert-manager 默认 issuerRef
      • dedicated HTTPS route 会把 Host rewrite 回 cluster 级 managed_workload_ingress_cname_target

这意味着：

  • control-plane、platform、workload 三条 Gateway 链路现在是分开的
  • 平台已具备最小版 workload edge 接线能力
  • 平台已具备最小版 HTTPS/cert-manager 接线能力
  • 平台已具备 self-managed 外部 hostname 的最小版独立证书编排能力（仍依赖预先准备好的 cert-manager issuer 与域名所有权验证能力）

2. 当前运行时语义

2.1 当前内置 controller

当前实现明确收敛为：

  • chart name：ingress-nginx
  • chart repo：https://kubernetes.github.io/ingress-nginx

也就是说：

  • 当前不是“任意 ingress chart 通用框架”
  • 只是把 ingress-nginx 作为当前内置托管 controller 进行 reconcile

可选配置：

  • KUBEBYON_MANAGED_INGRESS_CHART_VERSION

说明：

  • chart version 可按部署需要锁定
  • chart name / repo 虽然在配置层可见，但当前运行时只接受上述默认值

2.2 当前默认资源形态

当前托管入口控制器在目标 vCluster 内使用：

  • namespace：kubebyon-system
  • Helm release：kubebyon-managed-ingress
  • controller 资源名：kubebyon-managed-ingress-controller
  • 默认托管 IngressClass：kubebyon
  • IngressClass.spec.controller：kubebyon.app/managed-ingress
  • Service 类型：NodePort

2.3 当前状态值

managed_workload_ingress_status 当前使用：

  • disabled
  • provisioning
  • ready
  • error

大致语义：

  • disabled：当前未托管
  • provisioning：设置已提交，后台正在收敛
  • ready：controller 与基础资源已就绪
  • error：最近一次收敛失败，错误见 managed_workload_ingress_last_error

2.4 当前 workload edge 路由语义（Phase 4B / Phase 5 最小版）

启用 gatewayAPI.workload.enabled=true 后：

  • Helm chart 会创建一个独立于 control-plane / platform 的 workload shared Gateway
  • 该 Gateway 在 Helm render 中默认提供 HTTP:80 listener
  • 若启用 tls.enabled=true，HTTPS listener / redirect / Certificate 由 kubebyon-api runtime syncer 动态编排，而不是由 Helm 静态声明
  • kubebyon-api 进程中的 runtime syncer 会基于：
    • cluster 级 managed_workload_ingress_cname_target
    • cluster hostname bindings 在 cluster 对应的宿主 namespace 中动态维护对应 HTTPRoute、Service 与 EndpointSlice
  • HTTPRoute backend 指向同 namespace 的 shim Service
  • 这些 shim 资源当前优先把流量直接送到目标 vCluster 内托管 ingress controller 的 PodIP:80
  • 若当前宿主机无法稳定直达这些 PodIP，再自动回退到宿主节点 IP + NodePort
  • 若启用 gatewayAPI.workload.podCIDRRoute.enabled=true，PodIP 直连所需路由可由 API 本地同步，或在 mode=routeagent 时交给 kubebyon-route-agent DaemonSet 按 RoutePlan 收敛
  • 若启用 cert-manager，syncer 还会在 workload Gateway namespace 动态维护：
    • platform-managed 共享 Certificate
    • 以及可选的 self-managed 独立 Certificate
    • self-managed dedicated HTTPS route 上的 URLRewrite.hostname=<managed_workload_ingress_cname_target>

因此当前链路更准确地说是：

用户 hostname / CNAME target
  -> workload edge shared Gateway (Helm 保留 HTTP:80 / runtime-managed HTTPS)
  -> runtime-managed HTTPRoute / 可选 redirect route / 可选共享或独立 Certificate
  -> host-side Service + EndpointSlice shim
  -> 优先 ingress controller PodIP:80
  -> 不可达时再回退到宿主节点 IP:NodePort
  -> vCluster 内托管 ingress controller
  -> 用户 workload

3. 当前没有做的事情

当前实现还没有包含以下基础设施与自动化能力：

  1. 外部用户 DNS Zone 的托管
    • 平台当前会自动维护平台自有 base domain 下的 cluster 级 CNAME，以及同样落在该 base domain 下的 hostname binding CNAME
    • 用户自己外部 Zone 里的 CNAME / ALIAS / 其他记录仍需用户自行管理
    • 但 binding status=ready 的判定已经按“最终 canonical target”语义处理：外部 hostname 只要最终汇聚到 cluster 级 managed_workload_ingress_cname_target 所在的 canonical 链路即可
  2. 完整的 TLS 产品化
    • 当前已支持通过 cert-manager 动态维护共享 Certificate
    • 已补到 self-managed 外部 hostname 的最小版独立证书编排
    • 仍未覆盖外部 DNS Zone 托管与更细粒度的证书聚合策略
  3. 完整 workload edge 产品化
    • 当前已经有独立 workload shared Gateway
    • 也已具备最小版 HTTPS:443 + cert-manager 接线
    • 但尚未提供按租户拆分证书、证书可视化、策略配额等能力
  4. L7 产品化能力
    • 如路由可视化、证书管理、域名管理、流量审计、WAF 等

因此，当前能力更准确的描述应是：

平台已经提供托管入口的产品面（base domain、cluster 级 CNAME target、hostname binding 记录），并能为目标 vCluster 自动准备托管 ingress controller、自动维护平台自有 base domain 下的 cluster 级 CNAME 与相应 hostname binding CNAME，并通过独立 workload shared Gateway 提供 HTTP/HTTPS 最小版接线；若启用 cert-manager，平台现在既能为 platform-managed hostname 维护共享 Certificate，也能为 self-managed 外部 hostname 维护独立 Certificate。外部用户 DNS Zone 托管、证书可视化与更细粒度策略仍未完成。

4. 与用户自建入口方案的关系

即使开启托管业务流量入口，用户仍然可以继续：

  • 自己安装其他 Ingress Controller
  • 自己创建 NodePort
  • 使用 Gateway API / ServiceLB / 云厂商 LB 等其他入口方式

因此：

  • 它不是一个排他的 mode
  • 而是 cluster 级的一个 可选开关

这也是为什么它没有复用 public_access_mode：

  • public_access_mode：控制面 API 的公网访问语义
  • managed_workload_ingress_enabled：业务工作负载入口控制器的托管开关

5. 当前限制与实现边界

5.1 技术限制

  • 当前 readiness 探测依赖 ingress-nginx 的资源命名约定
  • 当前只校验 controller Deployment / Service / IngressClass
  • 非 provisioning 场景下，如 vCluster internal API 本身不可达，disable 仍可能失败

5.2 产品限制

  • 当前控制台已提供：
    • 托管入口开关与状态查看
    • managed_workload_ingress_cname_target 展示
    • cluster 级 managed_workload_ingress_dns_status / managed_workload_ingress_dns_message / managed_workload_ingress_dns_last_synced_at / managed_workload_ingress_dns_last_error / managed_workload_ingress_dns_last_error_at
    • 基于既有时间字段的 cluster 级平台 DNS 自动化“已恢复（Recovered）”历史提示（前端派生，不是新增 API 字段）
    • managed_workload_ingress_dns 系统设置
    • hostname binding 列表 / 新增 / 删除
    • hostname binding 的只读 dns_management_scope / dns_management_status / dns_management_message / dns_management_last_synced_at / dns_management_last_error / dns_management_last_error_at 展示
    • 基于既有时间字段的 binding 级平台 DNS 自动化“已恢复（Recovered）”历史提示，以及创建表单里基于 cluster managed_workload_ingress_cname_target 反推 base domain 的 DNS 托管范围实时预览
  • 当前后端已提供：
    • cluster 生命周期与 system settings 变更后的 cluster 级 CNAME 自动维护
    • 平台自有 base domain 下 hostname binding 的 CNAME 自动维护
    • hostname binding 的 CNAME 生效检测与状态回写
    • 可选 workload shared Gateway 的最小版 HTTP / HTTPS edge 接线
    • cert-manager 共享 Certificate 的 runtime 聚合维护（仅覆盖平台可托管范围）
  • 当前 Helm / 文档侧已补充：
    • self-managed 外部 hostname 独立证书编排的 values / env / NOTES / runbook / architecture 接线
    • self-managed 证书可选 issuerRef override，并可回退到 workload cert-manager 默认 issuerRef
    • self-managed dedicated HTTPS route 的 Host rewrite 说明，以及 PodIP 优先 / NodePort 回退语义
  • 但还没有：
    • 外部用户 DNS Zone 的托管 / 删除生命周期
    • 更完整的证书管理（如细粒度配额、可视化、审批 / 审计等）
    • app 级路由编排

6. 推荐阅读

7. 后续仍待补齐

  • 用户自定义域名的 DNS 托管 / 删除生命周期
  • workload edge 的 TLS / HTTPS 自动化
  • 证书管理与更多 L7 编排能力
  • 更完善的可观测性、诊断与失败恢复