KubeBYON 用户操作手册

最后更新：2026-05-11

本文档面向 KubeBYON 平台普通用户 / 租户用户，说明如何从零开始创建虚拟集群、接入自有节点、下载 kubeconfig，并暴露业务流量。

1. 这是什么

KubeBYON 是一套 Kubernetes Bring Your Own Nodes 平台：

平台侧托管你的 vCluster 控制面
你只需要提供自己的 Worker 节点
你可以通过控制台创建集群、生成加入命令、接入节点、查看状态并管理业务工作负载

可以把它理解为：

控制面由平台托管，工作节点和业务流量入口由你自己掌控；平台可选地为业务流量入口提供额外的托管能力。

2. 使用前需要准备什么

开始前，请确认你已经具备：

一个可登录的 KubeBYON 控制台账号
至少一台你有合法控制权的 Linux 主机，推荐：
- Debian / Ubuntu
- 1C / 1G 起步可做验证
- 生产环境请按业务负载提高配置
节点具备：
- 可访问公网
- 可执行 curl
- 具有 root 或 sudo 权限
如需公网暴露业务，还需要：
- 节点公网 IP，或
- 你自己的域名 / 证书 / 网关方案，或
- 平台运营方已配置好的托管业务入口基础域名与 DNS 提供方

3. 先理解两个“入口”

在 KubeBYON 里，常见会混淆两个入口：

3.1 控制面入口

用于：

kubectl
kubeconfig
访问虚拟集群 API Server

它由创建集群时的 公网访问模式 决定，常见为：

NodePort
LoadBalancer

3.2 业务流量入口

用于：

访问你部署在集群里的应用
例如 Web 服务、API、Ingress

它不是创建集群时那个“公网访问模式”自动帮你完成的。
业务入口需要你额外选择一种方案：

自己管理
- Service: NodePort
- 自己安装 Ingress Controller
- 自己管理域名 / DNS / TLS
平台托管业务入口
- 开启 managed workload ingress
- 使用平台准备的托管 ingress controller
- 使用 cluster 级 CNAME target
- 视域名是否落在托管 base domain 内，决定 DNS 由平台 best-effort 自动维护还是你自己管理

4. 第一次上手的推荐路径

推荐按下面顺序操作：

登录控制台
创建一个 vCluster
进入“添加节点”页面，复制加入命令
在你的 Linux 节点上执行加入命令
等节点变成 Ready
下载 kubeconfig
部署第一个工作负载
先用 NodePort 做一次最短链路验证
再决定是否开启 平台托管业务入口 或继续完全自建 Ingress

5. 登录与账号

当前平台支持的能力通常包括：

本地账号注册 / 登录
邮箱验证码注册
重置密码
GitHub / Google OAuth（是否开放取决于平台运营方配置）

登录后，你会进入用户控制台，可看到：

集群列表
节点列表
最近活动
个人设置 / API Key / 通知设置

6. 创建你的第一个集群

在控制台进入：

集群
点击 创建集群

创建时通常需要关注以下字段。

6.1 集群名称

建议使用：

简短
可读
能体现环境用途

例如：

dev-team-a
staging
customer-demo

6.2 Kubernetes 版本

通常保持平台默认版本即可，除非你有明确兼容性要求。

6.3 公网访问模式

这个配置影响的是 控制面 API Server 的对外访问方式。

如果界面里提供默认选项，表示“跟随平台当前系统默认设置”。

`NodePort`

适合：

单宿主机
快速验证
固定入口场景

特点：

平台会为虚拟集群 API 分配或复用一个 NodePort 端口
kubeconfig 通常会指向某个宿主机地址 + 端口

`LoadBalancer`

适合：

多宿主机部署
需要稳定域名 / VIP 的场景

特点：

通常要求平台运营方已准备好 LoadBalancer、HAProxy 或稳定入口
一般需要填写稳定域名或 IP

如果你不确定该选哪一个，优先询问平台运营方；对于初次验证，通常先用 NodePort。

6.4 托管业务入口开关

如果平台版本已提供 托管业务入口 开关，你会在集群详情页而不是“公网访问模式”里看到它。

它的语义是：

false：平台不为该集群准备托管 ingress controller
true：平台会尝试在该 vCluster 内准备托管 ingress controller

请注意：

这不是和用户自建入口互斥的 mode
即使开启了平台托管业务入口，你仍然可以继续：
- 自己安装别的 Ingress Controller
- 自己暴露 NodePort
- 自己接域名与证书

6.5 等待集群就绪

创建后，系统会在后台创建 vCluster 控制面。
完成后，你应能在详情页看到：

集群基本信息
节点数
kubeconfig 下载入口
控制面 API Endpoint

7. 把你的节点加入集群

7.1 打开“添加节点”

有两种常见入口：

集群列表里的 添加节点
集群详情页里的 添加节点

7.2 复制加入命令

系统会生成：

一条 一键加入命令
一个 加入令牌
令牌过期时间

你只需要复制那条命令，在目标 Linux 节点执行即可。

7.3 在目标节点执行

在你的机器上执行类似：

curl ... | sh

或控制台直接给出的完整 join 命令。

7.4 成功后的表现

成功后，节点会出现在：

集群详情页的节点列表
全局节点页面

理想状态是：

Ready

7.5 关于 Join Token 的注意事项

Join Token 会过期
过期后可重新生成
明文 token / join command 不会长期保存供你反复查看
如果你刷新“添加节点”页面，系统可能生成新的加入令牌

因此建议：

现用现复制
不要把 join 命令长期暴露在聊天工具或工单系统中

8. 验证集群是否可用

节点 Ready 后，建议做三步验证。

8.1 在控制台看节点状态

检查：

节点名称
状态
CPU / 内存
kubelet 版本
加入时间

8.2 下载 kubeconfig

可从以下位置下载：

集群列表
集群详情页

下载后本地执行：

export KUBECONFIG=./your-cluster.kubeconfig
kubectl get nodes

应能看到你刚加入的节点。

8.3 用一个简单工作负载做冒烟测试

例如：

kubectl create deployment demo --image=nginx
kubectl expose deployment demo --port=80
kubectl get pods -o wide
kubectl get svc

如果 Pod 能正常 Running，说明集群基本可用。

9. 如何暴露业务流量

这是用户最容易误解的地方，请重点看。

9.1 你有两条路：自建 or 平台托管

当前推荐把业务入口理解为两类方案：

A. 用户自己管理

适合：

快速验证
完全自定义
你已经有自己的域名 / DNS / TLS / 边缘设施

典型做法：

Service: NodePort
自己安装 ingress-nginx
自己创建 IngressClass / Ingress
自己管理 DNS / TLS

B. 平台托管业务入口

适合：

你希望平台先帮你准备托管 ingress controller
你希望获得稳定的 cluster 级 CNAME target
你愿意在平台约定的 base domain 内使用 hostname，以获得平台 DNS 的 best-effort 自动维护

但请注意：

当前平台托管能力还不是完整 edge gateway 产品
目前重点是：
- 托管 ingress controller
- cluster 级 CNAME target
- hostname binding 记录
- 对平台 base domain 内 CNAME 的 best-effort 自动维护
- 部署侧启用 Gateway API workload edge 后的 HTTP 接线，以及可选最小版 HTTPS / cert-manager 接线
不等于已经包含：
- 你的外部 DNS Zone 托管
- 面向所有外部域名的完整 TLS 产品化与证书可视化
- 完整平台边缘网关

9.2 最简单方案：NodePort

适合：

快速验证
单服务暴露
你可以直接使用节点公网 IP 的场景

示例：

kubectl expose deployment demo \
  --name demo-nodeport \
  --port 80 \
  --target-port 80 \
  --type NodePort

kubectl get svc demo-nodeport

然后访问：

http://<你的工作节点公网IP>:<nodePort>

真实验证中，这条路径已经可用，业务入口可以直接落在你的 Worker 节点上。

9.3 自己安装 Ingress Controller

适合：

多服务路由
域名转发
HTTPS
更接近生产形态

你可以在自己的 vCluster 中自行安装，例如：

ingress-nginx

然后再创建：

IngressClass
Ingress
TLS Secret

一个最小示例：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: nginx
  rules:
    - host: demo.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: demo
                port:
                  number: 80

9.4 开启平台托管业务入口后你会看到什么

如果你在集群详情页开启了托管业务入口，通常会看到：

当前开关状态
托管入口状态：
- disabled
- provisioning
- ready
- error
托管 IngressClass
最近错误
cluster 级 CNAME target
hostname binding 列表

这些含义大致是：

disabled：当前未托管
provisioning：平台正在为该集群准备托管 ingress controller 或相关资源
ready：托管 ingress controller 与基础资源已经就绪
error：最近一次收敛失败，可查看最近错误

9.5 什么是 cluster `CNAME target`

开启托管业务入口后，平台会为该 cluster 暴露一个稳定的 cluster 级 CNAME target。

你可以把它理解为：

这个集群所有业务域名最终应汇聚到的 canonical target。

你后续创建的 hostname binding，原则上都应让 DNS 最终指向这个 target。

9.6 什么是 hostname binding

hostname binding 表示：

“这个域名要绑定到这个 cluster”

它的作用是：

让平台知道该域名属于哪个 cluster
在满足条件时，让平台对该域名的 CNAME 做 best-effort 自动维护

9.7 `platform-managed` 和 `self-managed` 的区别

当前平台会区分 hostname binding 的 DNS 托管范围：

`platform-managed`

表示该 hostname：

位于管理员配置的 managed_workload_ingress_base_domain 下
因此有资格进入平台 DNS 自动维护范围

此时平台会 best-effort 自动维护它的 CNAME，使其指向该 cluster 的 CNAME target。

`self-managed`

表示该 hostname：

不在平台托管 base domain 下
或当前不满足进入平台 DNS 自动化范围的条件

此时：

binding 仍然是合法的
你仍然可以继续使用这个域名
只是 DNS 记录需要你自己管理

self-managed 不是错误状态，只表示“该域名由用户自行维护 DNS”。

9.8 平台 DNS 自动化的当前边界

当前请按下面理解：

平台只会对平台自有 base domain 范围内的 CNAME 做 best-effort 自动维护
平台不会代管你自己的外部 DNS Zone
平台当前也不自动帮你签发 TLS 证书

所以：

如果你用的是平台 base domain 内的 hostname，平台可能帮你自动维护 CNAME
如果你用的是自己的 app.example.com，通常仍需要你自己在 DNS 提供商那里创建：

app.example.com CNAME <cluster-cname-target>

9.9 当前建议怎么选

只想最快验证：先用 NodePort
想完全自控：自己安装 Ingress Controller
想让平台先帮你准备托管入口：开启 托管业务入口
想用自己的域名：把自己的外部域名 CNAME 到 cluster CNAME target
想让平台尽量代管 DNS：尽量使用平台提供的 base domain 范围内 hostname

10. 节点运维操作

在节点详情页，当前常见可用操作包括：

封锁节点（cordon）
解除封锁（uncordon）
驱逐工作负载（drain）
移除节点（delete）

10.1 这些操作分别意味着什么

封锁节点

新的工作负载不再调度到该节点
已有 Pod 通常不会立即被赶走

解除封锁

允许新工作负载重新调度到该节点

驱逐工作负载

尝试把现有 Pod 从该节点迁走
可能影响业务可用性

移除节点

把该节点从虚拟集群中删除
一般用于节点退役、替换或误接入修复

drain 和 delete 都可能直接影响线上业务，请谨慎执行。

11. 集群详情页还能做什么

当前集群详情页通常还提供：

节点列表
kubeconfig 查看 / 下载
kubectl 命令执行
控制面指标历史
公网访问设置
托管业务入口开关与状态
hostname binding 管理

11.1 后端代理执行 kubectl

如果你不方便本地配置 kubeconfig，可在控制台直接执行非交互式命令，例如：

kubectl get pods -A
kubectl describe node <node-name>
kubectl logs deploy/<name>

更适合：

临时排障
快速查看状态

不建议长期替代你自己的本地运维链路。

12. 个人设置与 API Key

在 个人设置 页面，你通常可以：

修改个人资料
上传头像
配置通知偏好
创建 / 删除 API Key
删除自己的账户

关于 API Key：

创建后请立刻保存明文
平台通常只保存前缀与哈希，不会反复回显完整密钥

13. 常见问题

Q1：我已经创建集群了，为什么业务域名还不能访问？

因为“创建集群时的公网访问模式”解决的是 控制面 API 暴露，不是你的业务流量入口。
你还需要额外选择一种业务入口方案：

NodePort
自己安装 Ingress Controller
或开启平台托管业务入口

Q2：默认有 Ingress 吗？

更准确地说：

不是所有集群都会默认自动拥有可用的托管业务入口
是否启用平台托管业务入口，取决于该集群当前设置
即使平台支持托管业务入口，你仍然可以完全自己安装 Ingress Controller

Q3：我能只用自己的 Worker 节点承载业务流量吗？

可以。
真实验证里，NodePort 与 Ingress Controller 都可以运行在用户自己的 Worker 节点上。

Q4：Join Token 失效了怎么办？

回到 添加节点 页面，重新生成并复制新的加入命令。

Q5：下载不了 kubeconfig 怎么办？

优先检查：

集群是否已就绪
公网访问是否已启用
公网访问模式是否配置正确
如果是 LoadBalancer，是否填写了稳定域名 / IP

Q6：NodePort 创建了，但外部访问不通怎么办？