Bundle 与 CRD 参考
Bundle 的字段、reconcile / 删除 / 导入导出语义,以及 PackingTable 自装的 CRD。
← 文档索引
PackingTable 的 CRD 一览
所有 CR 都是 apiVersion: fewbox.com/v1。
| Kind | 作用域 | 作用 | 谁来创建 |
|---|---|---|---|
Tenant |
命名空间级 | 记录一个租户:spec.logo、spec.domains、spec.registry。只是记录,没有 controller——命名空间、ServiceAccount、Gateway 由 tethys-shipping 的 POST /api/v1/tenants 创建 |
控制台「添加租户」;手工 apply 只产生一条记录,不创建任何东西 |
Bundle |
命名空间级 | 声明「这个租户里要跑哪些应用/任务」,是本文重点 | 控制台导出/导入或手工 apply |
Infrastructure |
命名空间级 | 环境级基础设施(NFS、RabbitMQ operator、MySQL operator) | 环境安装脚本/控制台 |
Middleware |
命名空间级 | 中间件实例(RabbitMQ、Verdaccio、PostgreSQL、Redis 的版本、存储、口令) | 环境安装脚本/控制台 |
Registry |
集群级 | 镜像仓库地址与默认标记;operator 物化 pull secret 时读取 | 平台侧预装(operator 不装它) |
Bundle 依赖租户底座已经就绪:命名空间、ServiceAccount <tenant>、ServiceAccount fewbox(isRunAsClusterAdmin 的 pack 用它)
与 Istio Gateway internet 必须在 apply 之前存在,Bundle 里的应用要靠它们启动,具体清单见
「一键部署 / 租户底座」。
删除 Tenant CR 不会清理命名空间里的资源——它没有 controller,删之前请把应用和命名空间一起处理。
Bundle 格式
9.1 骨架
Bundle 是命名空间级资源,metadata.namespace 就是目标租户;包内所有应用都属于这个租户,
所以 pack 里不再重复写 tenant。一个租户可以有多个 Bundle,但同名应用不要重复声明。
apiVersion: fewbox.com/v1
kind: Bundle
metadata:
name: <bundle-name>
namespace: <tenant> # 目标租户命名空间
spec:
isRetainOnDelete: false # 删除 Bundle 时是否保留下面的应用
packs: [] # 无配置文件的应用
customPacks: [] # 带 1..n 个配置文件挂载的应用
standardTaskPacks: [] # 一次性任务
customStandardTaskPacks: []
scheduledTaskPacks: [] # 定时任务
customScheduledTaskPacks: []
packs 与 customPacks、单配置与多配置的任务包,区别只在「有没有配置文件」;同一个应用不要同时出现在
两组里。
9.2 所有 pack 共有的字段
| 字段 | 类型 | 说明 |
|---|---|---|
registry |
string | 镜像前缀,不带末尾斜杠。为空时镜像退化为 <app>:<version> |
app |
string | 应用名,同时是 Deployment/Service 的名字。必须等于镜像仓库名(见 9.9 的已知限制) |
version |
string | 镜像 tag,通常以 v 开头(如 v1.2.3)。不是版本身份 |
releaseVersion |
string | 版本身份,形如 v3,决定 Deployment 名(<app>-v3)、version/release label 与 Istio subset。可省略,省略时从 version 的第一个点截断推断(v3.1 → v3) |
runtimeVariables |
array | 运行期环境变量,见 9.3 |
imagePullSecret |
string | 拉取镜像用的 Secret 名字,不含内容 |
isIgnore |
bool | 为 true 时跳过该 pack,用来临时下线某个应用 |
镜像串的拼装规则只有一条:
registry 为空 → {app}:{version}
registry 非空 → {registry}/{app}:{version}
imagePullSecret 的处理与它配合:
- operator 先用 pack 的
registry去匹配集群里的RegistryCR,找到平台凭证后,在目标租户里物化一个 拉取 Secret(名字由平台规则生成)。 - 如果 pack 显式写了
imagePullSecret,且该名字在目标租户里真实存在,则尊重用户的选择。 - 名字不存在(跨集群导入的典型情况)时,改用刚物化出来的 Secret;匹配不到任何平台凭证时只告警,
应用仍会创建,但 Pod 可能
ImagePullBackOff。
因此导出文件里只有 Secret 名,没有凭证内容;跨环境导入能否自愈,取决于目标集群是否预置了对应仓库的凭证。
9.3 runtimeVariables
runtimeVariables:
- name: LOG_LEVEL
value: info
source: Manual
- name: DATABASE_URL
value: ""
source: Secret
secretName: <tenant-secret-name>
secretKey: DATABASE_URL
| 字段 | 说明 |
|---|---|
name |
注入到容器里的变量名 |
value |
source: Manual 时的明文值 |
source |
字符串枚举:Manual(默认)或 Secret。必须写字符串,写 0/1 会被 apiserver 拒绝 |
secretName / secretKey |
source: Secret 时引用目标租户里已有的 Secret 及其 key;value 被忽略 |
Secret 来源只保存引用,凭证内容永远不随 Bundle 走。
9.4 Pack 与 CustomPack
两者字段基本相同,区别是有没有 settings。
| 字段 | 适用 | 说明 |
|---|---|---|
replicas |
两者 | 副本数;建议显式写 1 |
isPublic |
两者 | true 时把应用暴露出去(创建/更新 VirtualService) |
publicPrefix |
两者 | 公开路径前缀;为空时用平台默认 |
isRunAsClusterAdmin |
两者 | true 时以 fewbox ServiceAccount 启动(需要额外集群权限的应用) |
supplyMode |
两者 | 字符串枚举 OnDemand / RealTime / Offline;非法或为空按 OnDemand |
command |
两者 | 覆盖镜像的启动命令(数组) |
isWaitingForNetwork |
两者 | 启动时等待网络就绪 |
isRawNetwork |
两者 | 使用非 sidecar 劫持的直连网络 |
settings |
仅 CustomPack | 配置文件挂载数组,见 9.5 |
普通 Pack 不挂载配置文件。 即使写了 settingsTemplate,Bundle 的 reconcile 也不会把它传给 Launch;
要挂配置文件请放进 customPacks。控制台导出时也是按这个规则分组的。
9.5 settings:配置文件挂载
customPacks[].settings 与 custom*TaskPacks[].settings 都是 ConfigFileMountTemplate 数组:
settings:
- name: agentic.yaml
path: /app/config/agentic.yaml
source: Manual
mountMode: SingleFile
settingsTemplate: <base64-of-file-content>
settingsVariables:
MODEL_ENDPOINT: https://<model-api>
- name: credentials
path: /app/secrets
source: Secret
secretName: <tenant-secret-name>
mountMode: Directory
| 字段 | 说明 |
|---|---|
name |
挂载项名字。mountMode: SingleFile 时它同时是 Secret 里的 key |
path |
容器内的绝对路径 |
source |
字符串枚举:Manual(内联内容)或 Secret(引用已有 Secret) |
secretName |
source: Secret 时必填;指的是目标租户里的 Secret 名 |
mountMode |
SingleFile(默认,单文件)或 Directory(整个 Secret 挂成目录) |
settingsTemplate |
source: Manual 时文件内容的 UTF-8 base64;Secret 来源留空 |
settingsVariables |
键值对,在 base64 解码之后对内容做普通字符串替换(Replace(key, value)),不是 shell 展开,也不是环境变量替换 |
settingsVariables 常用于「模板里保留 ${VAR} 占位,导入到不同环境时只换地址」。
替换发生在挂载前,因此占位符在最终文件里会被直接替换成字面值。
9.6 任务类 pack
| 类型 | 字段 | 说明 |
|---|---|---|
standardTaskPacks |
command、settingsTemplate、settingsVariables |
一次性 Job;command 为空时用镜像默认 ENTRYPOINT |
customStandardTaskPacks |
同上 + settings[] |
一次性 Job,可挂多个配置文件 |
scheduledTaskPacks |
schedule、command、settingsTemplate、settingsVariables |
定时 CronJob;schedule 是标准 cron 表达式 |
customScheduledTaskPacks |
同上 + settings[] |
定时 CronJob,可挂多个配置文件 |
任务包也支持 runtimeVariables、imagePullSecret、isRawNetwork、isIgnore;它们不创建常驻 Deployment,
删除 Bundle 时对应 Job/CronJob 会被清掉。
9.7 reconcile 语义
Bundle 控制器是收敛式的:每次 reconcile 都让现状向声明靠拢,而不是「执行一次部署脚本」。
| 现状 | 动作 |
|---|---|
| 租户里没有这个应用的 Service | Launch:按 pack 创建 Service/Deployment(isRunAsClusterAdmin 决定用哪个 ServiceAccount) |
有 Service,但没有 <app>-<release> 这个 Deployment |
UpgradeMajor 到目标镜像,然后 Promote(把流量切到新版本,旧版本缩到 0 副本但保留) |
<app>-<release> 已存在 |
视为已就绪,不动——同一大版本内只改 version 再 apply 是空操作 |
isPublic: true |
每次 reconcile 都确保 VirtualService 指向该应用(publicPrefix 为空时用默认) |
含义与边界:
- 配置变更不收敛。 已有 Deployment 的
runtimeVariables/settings改动不会触发重新配置; 运行态微调要用控制台的重配置/合并功能。Bundle 只负责「有没有、是不是这个版本」。 - 升级要求身份递增,且身份是 DNS label。
UpgradeMajor要求版本身份匹配v\d+且大于当前身份; 带点的值属于镜像 tag,写进releaseVersion会被拒绝(Istio subset 不接受点号)。不满足时 Bundle 会进入Failed。因此 Bundle 不能用来回滚——回滚走控制台的「回退」。 - 任一 pack 抛错,整个 Bundle 记为失败,30 秒后重试;已经成功的应用不会回滚。
- 删除 Bundle 里的某个 pack 不会自动下线对应应用;要么删 Bundle 并让它走 finalizer,要么在控制台手动下线。
9.8 状态与条件
status 由 operator 显式写回:
status:
phase: Ready # Pending → Provisioning → Ready / Failed
message: <failure-text>
observedGeneration: <generation>
conditions:
- type: BundleReady # 所有 pack 已部署
status: "True"
reason: BundleDeployed
- type: Reconciled # 本轮协调结果
status: "True"
reason: ReconcileSucceeded
排障时先看 status.phase 与 status.message,再看 conditions 里的原因。phase: Failed 且 message 提到
upgrade failed 时,优先检查版本 tag 规则与镜像是否存在。
9.9 删除语义
Bundle 带 finalizer fewbox.com/bundlefinalizer。删除时:
isRetainOnDelete |
行为 |
|---|---|
true |
保留所有已部署的应用与任务,只删 Bundle 本身 |
false(默认) |
逐个 Shutdown 应用(删 Deployment/Service);isPublic 的再删 VirtualService;任务包清空对应的 Job/CronJob |
删除租户命名空间时,命名空间里的 Bundle 会先走各自的 finalizer,再随命名空间一起消失。若 CR 卡在
Terminating,通常是 finalizer 名与注册名不一致(KubeOps 10 的 finalizer 名固定为
{group}/{类名小写})。
9.10 控制台导出/导入
导出(微服务列表多选 → 导出 Bundle):
- 按租户分组,每个租户生成一份 Bundle;
metadata.namespace是源租户。 - 每个应用的镜像被拆成
registry+app+version;可以在导出时统一覆盖registry。 - 有配置文件挂载的应用进
customPacks,其余进packs。 - 配置内容以 base64 写进
settingsTemplate;Secret 来源的挂载与运行变量只导出secretName/secretKey, 内容不导出。 imagePullSecret只写名字。isRetainOnDelete由导出对话框决定。
导入(Kits/Bundles 页 → 粘贴 YAML):
- 只处理
kind: Bundle的文档,其它 kind 忽略。 - 每个源租户映射到一个目标租户,映射后改写
metadata.namespace;不同源租户映射到同一目标时, 同名 Bundle 会被判为冲突并拒绝。 - 整份 YAML 作为一个 GraphQL 变量提交给网关,受
GRAPHQL_BODY_LIMIT(默认 10mb)与边缘 nginxclient_max_body_size(默认 1MB)两层限制,超限表现为 413。
已知限制:
app必须等于镜像仓库名。 克隆类微服务的 app 名与镜像名不同时,导出的镜像串会拼错,导入后拉不到镜像。- Secret 内容不随文件走。 目标环境必须已经有同名配置 Secret,或在目标租户里先建好;平台仓库凭证 可以自动物化,业务配置 Secret 不会。
settingsVariables不导出。 如果原环境的配置文件依赖运行期替换,导出文件里只有 base64 原文, 需要在 YAML 里补回替换表。- 同版本视为已就绪。 想用 Bundle 改配置或改副本数不会生效,见 9.7。
- 版本必须递增。 用 Bundle 做「回滚到旧版本」不会成功,回滚走控制台的版本切换。
- 导入不会创建租户。 命名空间、ServiceAccount 与
Gateway internet必须先存在,见 「一键部署 / 租户底座」。 - 导入对话框在提交后立即关闭;保存失败(例如 413 或校验错误)只写浏览器控制台,不会弹错误提示。
大文件导入后请到 Bundle 列表确认
phase。
9.11 一份脱敏示例
下面是字段形状的最小示意;一份从参考环境完整导出、已脱敏的 21 应用 Bundle(含 customPacks、
多套 Secret 引用与真实字段组合)在「示例清单」里。
apiVersion: fewbox.com/v1
kind: Bundle
metadata:
name: example-suite
namespace: <tenant>
spec:
isRetainOnDelete: false
packs:
- registry: registry.example.com/example
app: example-web
version: v1.2.3
replicas: 2
isPublic: true
publicPrefix: /
supplyMode: RealTime
runtimeVariables:
- name: LOG_LEVEL
value: info
source: Manual
- name: SESSION_TOKEN
value: ""
source: Secret
secretName: <tenant-secret-name>
secretKey: SESSION_TOKEN
customPacks:
- registry: registry.example.com/example
app: example-agent
version: v2.0.0
replicas: 1
isPublic: false
command: ["node", "dist/index.js"]
runtimeVariables:
- name: DATABASE_URL
value: ""
source: Secret
secretName: <tenant-secret-name>
secretKey: DATABASE_URL
settings:
- name: agentic.yaml
path: /app/config/agentic.yaml
source: Manual
mountMode: SingleFile
settingsTemplate: <base64-of-file-content>
settingsVariables:
MODEL_ENDPOINT: https://<model-api>/api/v3
- name: credentials
path: /app/secrets
source: Secret
secretName: <tenant-secret-name>
mountMode: Directory
standardTaskPacks:
- registry: registry.example.com/example
app: example-migrate
version: v2.0.0
command: ["/app/migrate", "--yes"]
scheduledTaskPacks:
- registry: registry.example.com/example
app: example-tick
version: v2.0.0
schedule: "0 * * * *"
command: ["/app/tick"]