启用安全配置文件

Kagenti Operator 默认提供 core profile——Agent 注册和发现,但不包含身份 sidecar。secure profile 添加零信任工作负载身份(SPIRE mTLS)、OAuth2/JWT 身份验证(Keycloak)以及 Istio ambient mesh,并通过注入到每个已注册工作负载中的 AuthBridge sidecar 强制执行。本指南将引导你启用它。有关架构和设计原因,请参阅 Security Architecture。

前提条件

secure profile 依赖于不属于核心安装范围的集群组件。请按以下顺序先安装它们:

  1. cert-manager — webhook 和 CA 证书。
  2. SPIRE — 签发工作负载 SVID。提供 csi.spiffe.io CSI driver 和 trust bundle ConfigMap(spire-bundle)。请注意其 trust domain(例如 kagenti.local)。
  3. Keycloak — 集群内可访问的一个实例,其命名空间中包含 keycloak-initial-admin secret,并启用了 token-exchange 功能。
  4. Istio (ambient) — 用于命名空间级 mTLS 的 ztunnel + istio-cni。
INFO

在 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:

apiVersion: kagenti.alauda.io/v1alpha1
kind: Kagenti
metadata:
  name: kagenti
  namespace: kagenti-system
spec:
  featureGates:
    globalEnabled: true
    injectTools: true
  authbridgeConfig:
    enabled: true
  keycloak:
    publicUrl: http://keycloak-service.keycloak.svc.cluster.local:8080
  defaults:
    spiffe:
      trustDomain: kagenti.local
    images:
      envoyProxy: <registry>/authbridge-envoy:<tag>
      authbridge: <registry>/authbridge:<tag>
      authbridgeLite: <registry>/authbridge-lite:<tag>
      proxyInit: <registry>/proxy-init:<tag>
  1. featureGates.globalEnabled — 用于 AuthBridge sidecar 注入的主开关。injectTools: true 会将注入范围扩展到 tool 工作负载,从而也保护 agent↔tool 流量。
  2. authbridgeConfig.enabled — 启用由 operator 管理的 Keycloak client 注册、按命名空间划分的 authbridge-config ConfigMap(issuer / audience)以及 realm 启动引导。
  3. keycloak.publicUrl — 集群内 Keycloak 的 URL;它会成为 AuthBridge 验证的令牌 issuer 和预期 audience。
  4. defaults.spiffe.trustDomain — 必须与 SPIRE trust domain 匹配。
  5. 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 的每个命名空间打标签:

kubectl label namespace <agent-namespace> kagenti-enabled=true
WARNING

此标签是必需的。如果没有 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。

Agent 镜像必须遵守

$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. 验证

# AuthBridge sidecar injected (app container + authbridge-proxy)
kubectl get pod -n <ns> -l kagenti.io/type=agent \
  -o jsonpath='{.items[0].spec.containers[*].name}{"\n"}'

# SPIRE SVID delivered to the sidecar
kubectl exec -n <ns> <agent-pod> -c authbridge-proxy -- ls -l /opt/svid.pem

# Keycloak client registered (credentials secret created + mounted)
kubectl get secret -n <ns> | grep kagenti-keycloak-client

现在 mesh 会强制执行身份验证。一个未认证的请求会被拒绝:

{"error":"auth.unauthorized","message":"missing Authorization header","plugin":"jwt-validation"}

成功的请求必须携带一个有效的 Keycloak access token,其 audience 与 realm issuer 匹配——使用工作负载已注册的 client(<namespace>/<workload>,secret 来自 kagenti-keycloak-client-credentials-*)通过 client_credentials grant 获取 token,并将其作为 Authorization: Bearer <token> 发送。