一键部署(Bundle)
首次安装的最短路径:装好 operator,apply 一份 Bundle,按验收清单确认。出问题时转 逐服务手动部署。
← 文档索引
底座安装
这是整份指南里唯一必须手动做的一步。原因很简单:Bundle 是自定义资源,安装它的 operator 和定义它的 CRD 不能用 Bundle 自己安装——先有鸡才有蛋,这一层只能单独 apply。
底座应该尽可能小、静态、可复现。它越小,在您的环境里"装不上"的可能性越低。
一、命名空间与 ServiceAccount
operator 本身跑在 fewbox-system 里,用 fewbox 这个 ServiceAccount 访问 API Server
(集群内运行,靠 projected token,不需要额外配 endpoint / token):
kubectl create namespace fewbox-system
kubectl create serviceaccount fewbox -n fewbox-system
二、RBAC
kubectl apply -f deploy/operator-role.yaml # ClusterRole
kubectl apply -f deploy/operator-role-binding.yaml # ClusterRoleBinding -> fewbox-system/fewbox
这张 ClusterRole 覆盖工作负载、CRD、Istio 与 RBAC 本身——其中的
customresourcedefinitions 写权限是下一步 CRD 自装的前提。它不含节点与指标:
控制台的节点页和资源占用图走 nodes 与 metrics.k8s.io(NodeMetricses 读 metrics-server),
要用这两页就单独补一条 ClusterRole。
三、PackingTable operator
operator 就三份清单,全文附在下面,照抄成三个文件即可——第一份是权限,第二份把它绑到 fewbox SA,
第三份是 Deployment。先把 <your-registry> 与 <tag> 换成您的镜像地址,然后:
kubectl apply -f operator-role.yaml
kubectl apply -f operator-role-binding.yaml
kubectl apply -f operator-deployment.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: packingtable-operator
rules:
# Operator framework needs (leader election & events)
- apiGroups:
- ""
resources:
- events
verbs:
- get
- list
- create
- update
- apiGroups:
- coordination.k8s.io
resources:
- leases
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
# FewBox CRDs
- apiGroups:
- fewbox.com
resources:
- tenants
- tenants/status
- registries
- infrastructures
- infrastructures/status
- middlewares
- middlewares/status
- bundles
- bundles/status
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
# Operator manages K8S core resources
- apiGroups:
- ""
resources:
- namespaces
- services
- configmaps
- secrets
- pods
- pods/log
- serviceaccounts
- persistentvolumes
- persistentvolumeclaims
- replicationcontrollers
- resourcequotas
- endpoints
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- apps
resources:
- deployments
- replicasets
- statefulsets
- daemonsets
- controllerrevisions
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- batch
resources:
- jobs
- cronjobs
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- rbac.authorization.k8s.io
resources:
- clusterroles
- clusterrolebindings
- roles
- rolebindings
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- networking.k8s.io
resources:
- ingresses
- networkpolicies
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- networking.istio.io
resources:
- virtualservices
- destinationrules
- serviceentries
- gateways
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- apiextensions.k8s.io
resources:
- customresourcedefinitions
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- storage.k8s.io
resources:
- storageclasses
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- autoscaling
resources:
- horizontalpodautoscalers
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
# RabbitMQ / MySQL operators
- apiGroups:
- rabbitmq.com
resources:
- rabbitmqclusters
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- mysql.oracle.com
resources:
- innodbclusters
- mysqlbackups
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
- apiGroups:
- zalando.org
resources:
- kopfpeerings
- clusterkopfpeerings
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: packingtable-operator
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: packingtable-operator
subjects:
- kind: ServiceAccount
name: fewbox
namespace: fewbox-system
apiVersion: apps/v1
kind: Deployment
metadata:
name: packingtable
namespace: fewbox-system
labels:
app: packingtable
spec:
replicas: 1
revisionHistoryLimit: 3
selector:
matchLabels:
app: packingtable
template:
metadata:
labels:
app: packingtable
spec:
serviceAccountName: fewbox
containers:
- name: packingtable
image: <your-registry>/packingtable:<tag>
env:
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
# KubeOps connects with in-cluster config (same ServiceAccount); no extra endpoint/token needed.
resources:
limits:
cpu: 200m
memory: 256Mi
requests:
cpu: 100m
memory: 128Mi
terminationGracePeriodSeconds: 10
三件事值得先看一眼:
- 第一份就是完整的权限清单:工作负载、CRD、Istio、RBAC、
apiextensions.k8s.io全在里面。 operator 天生是特权组件,只应装在受控集群里。它不含nodes与metrics.k8s.io—— 控制台的节点页与资源占用图要用,按需另加一条 ClusterRole。 - Deployment 是单副本,唯一的环境变量是
POD_NAMESPACE(downward API 取自己的命名空间); K8s 连接走 in-cluster 配置,没有 endpoint / token 要填。 - 对象都叫
packingtable-operator/packingtable,与租户里的fewboxSA 是两回事。
CRD 不需要单独 apply。 operator 启动时把实体类型转译成 fewbox.com/v1 的 CRD 写进集群
(代码是唯一真源,schema 与程序永远一致)。起来之后验证:
kubectl get crd | grep fewbox.com
# tenants / infrastructures / middlewares / bundles / families / registries
kubectl get pods -n fewbox-system -l app=packingtable
operator 没起来之前,Bundle 对象只会静静地躺在那里,不会有任何东西被创建——症状是
"apply 成功了但集群里什么都没有"。这是最常见的第一个卡点。启动日志里出现
Failed to ensure FewBox CRDs 说明缺 CRD 写权限,先补 RBAC;不要拿旧的生成件去覆盖 CRD,
那样会把 schema 回退,之后写入的字段会被静默裁掉。
四、租户底座(apply Bundle 之前)
Bundle 是命名空间级资源,apply 之前下面四件必须已经在目标租户里:
| 对象 | 为什么 |
|---|---|
Namespace <tenant> |
就是 metadata.namespace,不存在时 apply 直接报错 |
ServiceAccount <tenant> |
普通 pack 用它启动(serviceAccountName 缺省等于租户名) |
ServiceAccount fewbox + ClusterRoleBinding |
isRunAsClusterAdmin: true 的 pack(如 fewbox-tethys-shipping)用它;没绑集群权限时 Pod 照常启动,但每次调 K8s API 都是 403 |
Istio Gateway internet |
isPublic: true 的服务把 VirtualService 绑到它;没有它不报错,只是域名 404 |
Tenant CR 不是创建租户的入口。 它只是一条记录(控制台的租户列表、基础域名、仓库来源),
没有 controller——手工 apply 一份 Tenant 什么都不会发生。租户的命名空间、ServiceAccount、Gateway
由 tethys-shipping 的 POST /api/v1/tenants(控制台「添加租户」)创建。
所以全新集群有两条起手方式,二选一:
先手工建(不需要 tethys):
kubectl create namespace <tenant> kubectl label namespace <tenant> istio-injection=enabled kubectl create serviceaccount <tenant> -n <tenant> kubectl create serviceaccount fewbox -n <tenant> kubectl -n <tenant> create rolebinding fewbox-admin \ --clusterrole=packingtable-operator --serviceaccount=<tenant>:fewbox再建入口
Gateway(形状见「安装 Istio」,selector要指向您集群里 ingressgateway 的标签):# tethys-shipping 按 v1beta1 读写这张 Gateway;Istio 1.22+ 的 v1 是同一个对象,两种写法等价 apiVersion: networking.istio.io/v1beta1 kind: Gateway metadata: name: internet namespace: <tenant> spec: selector: istio: ingressgateway servers: - hosts: ["<您的域名>", "*.<您的域名>"] port: number: 80 name: http protocol: HTTP等 tethys 起来后,再在控制台里把租户补齐(域名、配额、仓库):
Register对已存在的 命名空间、ServiceAccount 与 Gateway 只会跳过,不会重建,所以先手工建和先建租户可以互相接上。先把 tethys 起来,用「添加租户」一步建完上面四件,再在界面里导入 Bundle。 这条适合已经有一个可用的 tethys 实例(集群外引导)的环境。
tethys-gateway / tethys-shipping / tethys-web 本身就是 Bundle 里的三个 pack,所以路径 A
装完就有控制台,不需要为它单独准备一份清单。
五、定时任务(不在 Bundle 里)
thia-jobs-tick 这个 CronJob 不随 Bundle 导出(导出的 spec 里没有 scheduledTaskPacks),
它是 agent 仓 k8s/thia-jobs-tick.yaml 下的独立清单,含一个 ConfigMap 与一个 CronJob:
kubectl apply -f thia-jobs-tick.yaml -n <tenant>
漏了它系统照样装得上、页面照样打得开,但心跳检查、记忆整理、积分结算都不会发生, 而且没有报错——见「部署概览」。
引导凭据与 API Server 暴露
tethys 自己也是集群里的工作负载,第一次安装时还没有它可用的管理入口——这是不可避免的
"先有鸡"。引导方式有两种,任选其一:
| 引导方式 | 怎么装 | 适用场景 |
|---|---|---|
| 集群内 apply | kubectl apply RBAC、operator 与租户底座,再 apply Bundle(路径 A、B) |
有集群访问权限的常规安装 |
| 集群外引导 | 在一台集群外的机器上运行 tethys,连 API Server 从控制台安装 | 已有可用的 tethys 实例,或希望全程不碰 YAML;做法见下方「集群外引导:本机起 tethys」 |
两种方式对 API Server 的可达性要求相同,但外部引导多两处必须收紧的地方。
① API Server 的暴露范围
外部引导需要 API Server 从部署机可达。不要为此把 6443 开到 0.0.0.0/0:
- 安全组 / 防火墙只放行部署机的出口 IP(或跳板机、VPN 网段);
- 引导完成后关闭公网访问,日常升级走集群内的控制台;
- 集群里的
tethys-shipping必须通过集群内地址访问 API Server,即DevOps__Endpoints__K8SEndpoint__Host=kubernetes.default.svc、Port=443。否则运行态会 一直依赖那个公网口子,想关也关不掉。
② 引导凭据的有效期
kubectl create token 签出的是 ServiceAccount 的 JWT,不是 Secret:到期前它就是一条长期
有效的 bearer 凭据,无法单独吊销——撤销只能靠删除 / 修改该 ServiceAccount,或轮换 API
Server 的签名密钥(后者会同时踢掉所有 SA token)。
operator 使用的 SA 又是特权组件(要创建 Deployment、Service、Ingress、ClusterRole 乃至 CRD),这条凭据等同于集群控制权。因此:
- 按需现取、短期使用,例如
--duration 1h; - 不要签发以年为单位的 token,也不要把 token 写进配置文件、数据库或交付物;
- 已经固化保存过的凭据,在引导完成后清理并重新生成。
走集群内 apply 的路径同样需要一份可达 API Server 的 kubeconfig。区别只是凭据形态,不是 风险有无——kubeconfig 里内嵌的 client certificate 也应当短期保管、用后收回。
集群外引导:本机起 tethys,在界面里装 operator
不想在集群上敲 YAML 时,可以反过来:在一台能访问 API Server 的机器(本机或跳板机)上把
tethys-gateway、tethys-shipping、tethys-web 跑起来,用 kubectl create token 签出的凭据连上集群,
然后在界面里把上面的底座与 operator 点一遍,最后导入 Bundle。
顺序不能反:PackingTable 装好之前,导入 Bundle 一定失败——没有 controller 接它。所以:
本机起三个服务(镜像用 Bundle 里那三个 pack 的同一版),只改连接信息:
tethys-shipping的DevOps__Endpoints__K8SEndpoint__Host/Port指向 API Server、AppSettingsToken填 token;tethys-gateway的SHIPPING_ENDPOINT指到本机 shipping。身份服务还没进集群时,PERMISSIONS_OPEN=true会同时跳过 JWT 公钥自检与 ADMIN 鉴权(日志打[SECURITY]警告)。命名空间与 ServiceAccount:控制台建
fewbox-system,再在其中建fewboxSA。ClusterRole / ClusterRoleBinding:内容就是第三节那份清单, 一条权限都别省——省了 operator 照样起得来,reconcile 时才 403。
PackingTable 的 Deployment:
serviceAccountName: fewbox,POD_NAMESPACE用 downward API 取。租户 → Bundle → 定时任务:「添加租户」建命名空间、SA 与
Gateway internet,导入 Bundle, 最后单独建thia-jobs-tick。装完退场:这时集群里已经有
tethys-*三个 pack,把控制台切到集群内那份;本机 shipping 的 SQLite 只是引导现场的记录(发布历史、租户行),别当权威数据源。 退场前做两件收尾:把界面建出来的对象导回清单(界面里点出来的东西没有声明来源, 不导出来就没人知道集群里那份是什么镜像、什么 env)——kubectl get deploy,clusterrole,clusterrolebinding -n fewbox-system -o yaml > operator-as-installed.yaml存进交付记录,下次升级或排障时对照;然后停掉本机三件套、撤销引导 token, 别让一个
PERMISSIONS_OPEN=true的管理面一直挂在客户的集群上。
这条路的固定成本与边界:
| 项 | 说明 |
|---|---|
| 本机 tethys 要有自己的用户表 | SUPABASE(Tethys 早于统一身份,用户表独立)。这一点路径 A 也一样——那三个 pack 在 Bundle 里同样要它 |
| 引导凭据等于集群控制权 | 短期签发、不落盘、用完撤销,见上一节 ② |
| 界面里建的对象会与清单漂移 | 点出来的对象没有 diff 可看。退场时导出一次(见第 6 步),升级或改权限时按第三节对齐 |
| 长期入口是集群内那份 tethys | 本机那份只负责把第一版装上去 |
路径 A:Bundle 一键部署
首次安装和日常升级都走这条路。您拿到的 Bundle 由我们从参考环境导出,作为交付物提供, 不需要自己拼。
字段含义、reconcile 与删除行为见「Bundle 格式」。
Bundle 从哪来
由我方从参考环境导出,作为交付物提供。您不需要自己导出。
想知道这份文件长什么样、有哪些字段要改,直接看「示例清单」:那是参考环境的 完整导出(21 个应用 + 17 个 Secret),已脱敏,可以当作填写模板。
导入前准备
打开 YAML,先处理下面几项,再 apply:
① 镜像仓库前缀
每个 pack 都有 registry 字段,默认是我方的仓库地址:
spec:
packs:
- registry: <您的镜像仓库>/<项目>
app: thia-web
version: v1.2.3
整体替换最稳妥,逐条改容易漏。
② 命名空间
metadata.namespace 是租户名。私有化部署通常只用一个:
metadata:
name: agentic-hat
namespace: <您的命名空间>
③ 镜像拉取凭据
imagePullSecret 只写 Secret 的名字,不写内容。请先在目标命名空间里创建它:
kubectl create secret docker-registry <secret-name> \
--docker-server=<您的镜像仓库> \
--docker-username=<用户名> \
--docker-password=<密码> \
-n <您的命名空间>
④ 被引用的业务 Secret
Bundle 里的 runtimeVariables[].source: Secret 和 settings[].source: Secret 只保留
secretName / secretKey 引用,不包含任何密钥内容。这些 Secret 必须在 apply 之前
就存在于目标命名空间,名称要与 Bundle 里完全一致。
# 列出 Bundle 引用到的所有 Secret
grep -E '^\s*(- )?secretName:' bundle.yaml | awk '{print $NF}' | sort -u
以 Themis 为例(各键的用途见「路径 B / Themis:身份」):
# ES256 密钥对:auth 签名(私钥 + 公钥)、gateway 验签(公钥)
kubectl create secret generic <bundle 里的 auth 密钥 Secret 名> -n <您的命名空间> \
--from-file=JWT_PRIVATE_KEY=jwt-private.pem \
--from-file=JWT_PUBLIC_KEY=jwt-public.pem
kubectl create secret generic <bundle 里的 gateway 公钥 Secret 名> -n <您的命名空间> \
--from-file=JWT_PUBLIC_KEY=jwt-public.pem
# 会话签名密钥:必填、无默认值,空值会被启动自检直接拒绝
kubectl create secret generic <bundle 里的 session Secret 名> -n <您的命名空间> \
--from-literal=IDP_SESSION_SECRET="$(openssl rand -base64 48)"
缺任何一个,对应 Pod 会停在 CreateContainerConfigError: secret "..." not found;
补建 Secret 后无需重新 apply,kubelet 会自动重试挂载。
⚠️ Bundle 文件本身是敏感文件。
spec.packs[].runtimeVariables里的值是明文的, 配置文件内容(spec.customPacks[].settings[].settingsTemplate)是 base64,等于不设防。 不要把填好真实值的 Bundle 提交到 git,也不要用邮件传输。
应用
kubectl apply -f bundle.yaml
观察 reconcile
kubectl get bundles -n <您的命名空间>
kubectl get deploy,svc -n <您的命名空间>
operator 会先创建 Deployment,再创建 Service。全部 READY 之后才能进入「首次启动验收」一节。
Reconcile 卡住时的判断顺序:
- operator 的 Pod 在不在、日志有没有报错
- 镜像拉得下来吗(
kubectl describe pod看ImagePullBackOff) - 资源配额够不够(
ReplicaSet创建失败会留下事件)
首次启动验收
六项全部通过才算装好。顺序是从基础设施到业务——前一项不过,后一项验不了。
| # | 检查 | 怎么验 |
|---|---|---|
| 1 | 所有 Pod READY |
kubectl get pods -n <ns> |
| 2 | 健康检查通过 | 各服务的 /livez、/readyz(themis-auth、rhea-email、rhea-push 的在 /api/v1 下面;thia-web 没有健康路由,见 Service 与端口) |
| 3 | 能注册并登录 | 打开 accounts.titanides.com,走完注册 → 收信 → 验证 → 登录 |
| 4 | 能发一次对话 | 登录 thia-web,新建会话,发一条消息,看到回复 |
| 5 | 积分账本正确 | 余额随对话扣减,能在数据库里看到对应流水 |
| 6 | 定时任务在跑 | kubectl get jobs -n <ns> 能看到 thia-jobs-tick 生成的 Job(名字形如 thia-jobs-tick-xxxxx),且最近一次是 5 分钟内的 |
验收第 3 项最容易出问题——它同时验证了邮件服务和身份服务。如果收不到验证邮件,
先查 rhea-email 的 SMTP 配置,再看 themis-auth 能不能连到它的 Service。