生产环境安全基线与加固
本文档是 KubeOsprey 的生产环境安全基线,适用于 Helm 安装、独立 Kubernetes 清单和 Cluster Agent 部署。
KubeOsprey 是 Kubernetes 控制面。它可以创建高权限 Kubernetes 客户端、终端 Pod、exec 会话、代理请求,并执行 AI 辅助的资源变更。请把 KubeOsprey 视为集群管理边界来部署和审计。
生产环境基线
向用户开放 KubeOsprey 前,请确认:
- KubeOsprey、OAuth/OIDC 回调、Cluster Agent 连接和 WebSocket 流量均使用 HTTPS。
- 设置高熵的
KUBE_OSPREY_ENCRYPT_KEY并存储在外部 Secret 中,不要使用开发文档中的公开示例值。 - 如果需要重启后或多副本之间保持会话稳定,请显式设置
JWT_SECRET。 - 设置
ANONYMOUS_USER_ENABLED=false,并验证匿名访问已关闭。 - 将
TRUSTED_PROXIES限制为实际的反向代理地址,不要信任任意客户端转发头。 - 使用外部 PostgreSQL/MySQL,或为 SQLite 配置持久化卷。
- 将 KubeOsprey、终端和 Cluster Agent 镜像固定到发布版本或 digest,生产环境不要使用
latest。 - 部署前检查每一条
cluster-admin、通配符 RBAC、privileged 容器、主机 namespace 和 hostPath 配置。 - 只启用运维人员确实需要的终端和 Cluster Agent 能力。
- 同时备份数据库和加密密钥。没有加密密钥的数据库备份无法恢复加密字段。
密钥与加密
数据库中的 SecretString 字段包括 kubeconfig、OAuth/LDAP 密钥、Helm 仓库密码、API Key、MFA Secret 和 Cluster Agent 私钥等凭据,它们使用 KUBE_OSPREY_ENCRYPT_KEY 加密。
启动时会校验 KUBE_OSPREY_ENCRYPT_KEY:密钥不能为空、长度至少 32 个字符、且不能等于内置的开发用默认值,否则服务拒绝启动。仅本地开发环境可以设置 KUBE_OSPREY_ALLOW_INSECURE_DEFAULTS=true 跳过默认值检查。
TRUSTED_PROXIES 建议配置为实际反向代理的网段或 IP;设置为 none 表示忽略所有客户端转发头。
用户密码使用单向密码哈希保存,不能通过 KUBE_OSPREY_ENCRYPT_KEY 恢复。
建议使用已有 Kubernetes Secret:
secret:
create: false
existingSecret: kube-osprey-secrets该 Secret 必须包含当前部署模式需要的配置项。恢复已有数据库时,必须保持原加密密钥不变。密钥轮换需要专门的迁移流程:使用旧密钥解密,再使用新密钥重加密。
不要把真实密钥写入 values.yaml、Git、Shell 历史、工单或生成的 Manifest。
Kubernetes 权限
KubeOsprey 有应用层 RBAC,Kubernetes 还会独立检查 KubeOsprey Server 和 Cluster Agent 使用的 ServiceAccount 或 kubeconfig。最终权限受两套系统共同影响,但过大的 Kubernetes 身份仍会放大误操作或会话被攻破后的影响。
请分别检查:
- KubeOsprey Server 的 ServiceAccount 和 ClusterRole;
- Cluster Agent 的 ServiceAccount 和 ClusterRoleBinding;
- kubectl Terminal 的 ServiceAccount 和 ClusterRoleBinding;
- Node Terminal 的 host 访问、privileged、主机 namespace 和 hostPath;
imagePullSecrets以及终端 Pod 创建的 namespace。
生产环境避免使用以下通配符规则,除非该部署明确只用于管理员 Break-glass 场景:
apiGroups: ["*"]
resources: ["*"]
verbs: ["*"]Cluster Agent Manifest 支持权限档位:
readOnly:全资源只读。operator:常见工作负载资源可读写(pods 含 exec/attach/portforward、services、configmaps、PVC、deployments、statefulsets、daemonsets、replicasets、jobs、cronjobs、ingresses、networkpolicies、PDB、HPA),并对 namespaces、nodes、PV、StorageClass、events、CRD、metrics、Secrets 只读;不授予 Secret 和 RBAC 的写权限。admin:绑定cluster-admin(兼容旧的高信任行为)。custom:绑定指定的已有 ClusterRole。
默认档位为 admin(向后兼容);生产环境建议使用 operator 或 readOnly。注意 operator 档位可以读 Secrets(KubeOsprey 控制台的 Secret 页面和 Helm Release 浏览依赖 Secret 数据);如不可接受请使用 custom。
Kubernetes 中 ClusterRoleBinding 的 roleRef 不可修改。切换已有 Cluster Agent 的权限档位时,必须先删除已有的 Cluster Agent ClusterRoleBinding,再应用新 Manifest(新安装名为 kube-osprey-cluster-agent;从更名前版本升级的安装为 kite-cluster-agent)。
终端与 exec 能力
Pod exec、kubectl Terminal 和 Node Terminal 都不是普通的只读功能:
- Pod exec 可以在工作负载容器内执行命令;
- kubectl Terminal 使用其 ServiceAccount 操作集群;
- Node Terminal 可以获得主机级能力。
应使用明确的管理员权限、短会话、自动清理和审计日志。除非确有需要,否则保持 kubectl 和 Node Terminal 关闭。请验证关闭后不会创建 ServiceAccount、Binding 或 Agent Pod。
Prometheus 与原始 PromQL
PromQL Explorer 是集群级可观测性工具。只有允许查询配置的 Prometheus 数据源的用户才应获得该能力。Kubernetes namespace RBAC 不会自动过滤 Prometheus 查询结果。
如果 KubeOsprey 用作多租户平台,应在 Prometheus 层实现租户隔离,或改用审核过的查询模板。不要通过给任意 PromQL 盲目追加 namespace selector 来伪造数据隔离。
数据库与持久化
默认 SQLite 适合评估环境。没有持久化卷时,Pod 替换会丢失数据库。生产环境建议:
- 多副本和运维备份优先使用 PostgreSQL 或 MySQL;
- 使用 SQLite 时配置持久化卷,并使用适合单写卷的部署策略;
- 不仅测试备份创建,还要定期测试恢复;
- 将数据库、加密密钥和部署配置作为一个恢复集合备份。
审计策略
所有改变状态的console请求都会写入操作审计日志。策略在 Settings → Audit 中配置:
- 日志保留期:操作日志保留的天数(1–3650,默认 30),超期条目自动清理。
- 跳过模块:所选模块的变更不写入审计日志。请尽量保持该列表为空——跳过一个模块意味着它的变更不留任何审计痕迹。
若审计策略读取失败,审计按"失败放行"处理:变更仍会以默认保留期记录。
Cluster Agent 检查清单
- 使用 HTTPS Server URL,并确保 Agent 信任对应证书;
- 将一次性 Agent Token 和生成的 YAML 当作凭据处理;
- 怀疑泄露后及时轮换或吊销 Agent Token;
- 应用 Manifest 前验证 Agent 镜像和 digest;
- 应用前检查 ServiceAccount、ClusterRoleBinding、Secret 和 Deployment;
- 切换权限档位时,先删除已有的 ClusterRoleBinding(
roleRef无法原地更新;新安装名为kube-osprey-cluster-agent,从更名前版本升级的安装为kite-cluster-agent); - 确保反向代理支持 WebSocket Upgrade 和长连接;
- 多副本部署前验证会话路由和共享状态。
验证命令
检查 Chart:
helm lint charts/kube-osprey
helm template kube-osprey charts/kube-osprey --namespace kube-osprey-system
bash scripts/validate-chart.sh在测试集群中检查实际 Kubernetes 权限:
kubectl auth can-i --list \
--as=system:serviceaccount:<namespace>:<service-account>
kubectl get clusterrolebinding <binding-name> -o yaml
kubectl get serviceaccount <service-account> -n <namespace> -o yaml运行应用检查:
go test ./...
pnpm --dir ui exec tsc --noEmit -p tsconfig.app.json请区分进程存活和应用就绪。进程可以运行,但数据库、加密密钥或集群配置可能已经不可用。
当前限制与后续路线
以下问题需要独立设计,不应直接粗暴收紧权限:
- Cluster Agent 当前使用注册的 Kubernetes 凭据转发请求,不会在 Kubernetes API 层模拟 KubeOsprey 用户身份;
- kubectl 和 Node Terminal 需要更强的 Break-glass 控制和更小权限的身份;
- 加密密钥轮换需要兼容已有
SecretString的迁移流程; - KubeOsprey 不会对原始 PromQL 做 namespace 改写,多租户隔离应由指标架构或受限查询模型提供;
- Passkey、Cluster Agent 会话和其他进程内状态在正式支持多副本前需要共享存储。