启用安全配置文件
Kagenti Operator 默认提供 core profile——Agent 注册和发现,但不包含身份 sidecar。secure profile 添加零信任工作负载身份(SPIRE mTLS)、OAuth2/JWT 身份验证(Keycloak)以及 Istio ambient mesh,并通过注入到每个已注册工作负载中的 AuthBridge sidecar 强制执行。本指南将引导你启用它。有关架构和设计原因,请参阅 Security Architecture。
前提条件
secure profile 依赖于不属于核心安装范围的集群组件。请按以下顺序先安装它们:
- cert-manager — webhook 和 CA 证书。
- SPIRE — 签发工作负载 SVID。提供
csi.spiffe.ioCSI driver 和 trust bundle ConfigMap(spire-bundle)。请注意其 trust domain(例如kagenti.local)。 - Keycloak — 集群内可访问的一个实例,其命名空间中包含
keycloak-initial-adminsecret,并启用了token-exchange功能。 - Istio (ambient) — 用于命名空间级 mTLS 的
ztunnel+istio-cni。
在 AI 上,这些组件对应为:cert-manager(内置)、SPIRE cluster plugin、Keycloak operator 加上一个 Keycloak 实例,以及启用 ambient 的 Service Mesh v2(Istio CR profile: ambient 加上一个 ZTunnel)。有关各组件的逐步安装和配置,请参阅 Install the Secure-Profile Dependencies。
1. 在 operand 上启用安全配置文件
修补 Kagenti 自定义资源,以开启 sidecar 注入,并将其指向你的 Keycloak 和 SPIRE trust domain:
featureGates.globalEnabled— 用于 AuthBridge sidecar 注入的主开关。injectTools: true会将注入范围扩展到tool工作负载,从而也保护 agent↔tool 流量。authbridgeConfig.enabled— 启用由 operator 管理的 Keycloak client 注册、按命名空间划分的authbridge-configConfigMap(issuer / audience)以及 realm 启动引导。keycloak.publicUrl— 集群内 Keycloak 的 URL;它会成为 AuthBridge 验证的令牌 issuer 和预期 audience。defaults.spiffe.trustDomain— 必须与 SPIRE trust domain 匹配。defaults.images— AuthBridge sidecar 镜像(其中已捆绑spiffe-helper)。请将它们迁移到你的集群可拉取的 registry;operator bundle 也会在relatedImages中记录它们。
当 authbridgeConfig.enabled 为 true 且 配置命名空间中已存在 Keycloak 实例时,operator 会自动将 kagenti realm 导入其中(一个包含平台 client 和 kagenti-platform-audience scope 的 KeycloakRealmImport)——无需手动配置 realm。
2. 将命名空间纳入安全配置文件
operator 只会管理明确加入的命名空间中的身份。请为运行受保护 agent 或 tool 的每个命名空间打标签:
此标签是必需的。如果没有 kagenti-enabled=true,operator 将不会为该命名空间创建 authbridge-config ConfigMap,并且其工作负载的 Keycloak client 注册也不会启动(工作负载会因缺少 credentials secret 而一直处于 pending 状态)。
3. 部署受保护的 Agent
请继续阅读 Demo with Secure Profile,了解在 secure profile 下完整的 weather-agent 演示流程。部署 YAML 与 core-profile quick start 相同——在 Deployment 或 AgentRuntime 中不需要任何 secure-profile 专用字段,因为 AuthBridge webhook 会在 admission 时基于 Kagenti operand 和命名空间标签完成所有关联配置。它会向每个已注册的 Pod 注入 authbridge-proxy sidecar 和 SPIRE SVID,并且 operator 会为每个工作负载注册一个 Keycloak client。
如果你需要一个更严格的变体,将 AuthBridge 也放到 tool 上,并在 agent 与 tool 之间交换令牌,请参阅 Demo Advanced: AuthBridge on the Tool with Token Exchange。
$PORT
在 proxy-sidecar 模式下,AuthBridge reverse-proxy 会绑定工作负载的 service port,而 operator 会将应用重映射到一个 PORT 环境变量值(例如 8001)。Agent 容器必须绑定 $PORT,而不是硬编码端口,否则它会与 reverse-proxy 冲突(address already in use)。上游 weather 示例从 v0.1.0 起已遵守 PORT。
4. 验证
现在 mesh 会强制执行身份验证。一个未认证的请求会被拒绝:
成功的请求必须携带一个有效的 Keycloak access token,其 audience 与 realm issuer 匹配——使用工作负载已注册的 client(<namespace>/<workload>,secret 来自 kagenti-keycloak-client-credentials-*)通过 client_credentials grant 获取 token,并将其作为 Authorization: Bearer <token> 发送。