安全架构

除了注册和发现智能体之外,Kagenti Operator 还可以为你的智能体接入一个 零信任安全栈:工作负载身份、传输加密以及请求授权。本页将说明这些组件如何协同工作,帮助你决定启用哪些能力。

这个安全栈是 operator 的 secure profile。它在 Introduction 中描述的 core profile 里默认禁用——智能体以单容器方式运行,MTLSReady 报告为 False 且原因是 SPIREUnavailable,并且不会强制执行任何授权。下面介绍的内容都属于可选能力,并依赖额外的集群组件。

概览

三个关注点分别对应三种技术,并由 operator 注入到每个智能体 pod 中的 AuthBridge sidecar 串联起来:

关注点问题技术
工作负载身份这是谁的工作负载?SPIFFE / SPIRE
传输安全连接是否已加密并完成认证?Istio ambient mesh (+ AuthBridge mTLS)
授权调用方是否被允许执行此操作?Open Policy Agent (OPA) + AuthBridge + Keycloak

通过安全加固后的智能体,请求路径如下:

                       ┌──────────────────────── Agent Pod ────────────────────────┐
 caller (agent/tool) ─▶│  AuthBridge sidecar                  your agent container  │
                       │   ├─ terminate / originate mTLS (SVID from SPIRE)          │
                       │   ├─ validate JWT (issued by Keycloak)                     │
                       │   └─ evaluate OPA policy (Rego bundle from bundle-service) │
                       │  spiffe-helper sidecar ◀── SPIRE Workload API (X.509-SVID) │
                       └────────────────────────────────────────────────────────────┘
   Istio ambient (ztunnel) provides namespace-wide L4 mTLS underneath the pod.
INFO

这个 operator 不使用 Authorino 做授权。授权通过 OPA Rego policies 来表达,并由 AuthBridge sidecar 强制执行。可选的 Kuadrant 集成仅用于确保 Istio ambient gateway 存在一个基础的 Kuadrant 自定义资源——operator 不会把 policies 转换为 Kuadrant AuthPolicy 或 Authorino AuthConfig 对象。

工作负载身份(SPIFFE / SPIRE)

SPIFFE 为每个工作负载提供加密身份;SPIRE 则是在运行时发放该身份的组件。

  • 当集群中存在 Zero-Trust Workload Identity Manager 时,operator 会协调 SPIRE 相关组件;你也可以自行部署 SPIRE。

  • AuthBridge webhook 会注入一个 spiffe-helper sidecar 和 SPIFFE CSI socket。spiffe-helper 会从 SPIRE Workload API 获取一个 X.509-SVID,并自动轮换。

  • 该身份的形式如下:

    spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>

    由于该身份是从 ServiceAccount 派生的,请为每个智能体单独分配一个 ServiceAccount,使其获得唯一身份。

这个 SVID 是其他所有能力的信任根:它用于保护传输(mTLS)、作为智能体的 Keycloak client 名称,并为智能体的 AgentCard 签名,以便进行可验证发现。

传输安全(Istio ambient mesh)

operator 通过为智能体的 namespace 添加标签,将其接入 Istio ambient mode:

istio.io/dataplane-mode: ambient
istio-discovery: enabled
  • 这会在 AgentRuntime 上体现为 IstioMeshEnrolled 状态条件。(即使在 core profile 中也会应用该标签,这就是你在那里看到 IstioMeshEnrolled=True 的原因。)
  • Pod 之间的 L4 mTLS 由 Istio 的 ztunnel 透明处理——operator 不会编写 PeerAuthentication 或 DestinationRule。
  • operator 会保持各个 namespace 之间的证书颁发机构链一致(将 cert-manager 的 mesh root 中的 Istio cacerts 进行协调),从而确保 SPIRE 和 Istio 签发的证书最终链到共同根。
  • 可通过注解 kagenti.io/istio-mesh=disabled 将某个 namespace 排除在外。

在 mesh 级别 mTLS 之上,AuthBridge sidecar 还可以使用工作负载自身的 SVID 在智能体之间执行 应用层 mTLS——参见 mtlsMode。

授权(OPA + AuthBridge + Keycloak)

授权在 AuthBridge sidecar 处以 policy-as-code 的方式进行评估:

  1. 身份 / 令牌 — operator 会在 Keycloak 中将智能体注册为 OAuth2 client。其凭据会写入 Secret 并挂载到 pod 中;sidecar 会针对 Keycloak issuer 和 audience 获取并验证 JWTs。令牌交换支持 tool-to-agent 委派。
  2. Policy — AuthorizationPolicy 自定义资源保存一个或多个 Rego policies。bundle-service 会将它们编译为 OPA bundle,并按身份进行提供;AuthBridge sidecar 会拉取与其 SPIFFE ID 匹配的 bundle。
  3. 决策 — AuthBridge 在四个点位评估 policy——inbound/outbound × request/response——并采用 fail-closed(default allow := false)。

policies 按三层层级进行作用域划分:

spec.scope适用范围
global集群中的所有客户端(kagenti-system 中的默认 policy)
namespace单个 namespace;可扩展/覆盖 global
client特定的 OAuth2 client(按 clientID 标识的智能体或 tool)

示例:一个全局 Rego policy

apiVersion: agent.kagenti.dev/v1alpha1
kind: AuthorizationPolicy
metadata:
  name: default
  namespace: kagenti-system
spec:
  scope: global
  policies:
    - path: "inbound/request.rego"
      content: |
        package authbridge.inbound.request
        import rego.v1
        default allow := false
        allow if data.authbridge.ns.inbound.request.override
        allow if {
            ns_ok
            client_ok
        }
        ns_ok     if data.authbridge.ns.inbound.request.allow
        ns_ok     if not data.authbridge.ns.inbound.request
        client_ok if data.authbridge.client.inbound.request.allow
        client_ok if not data.authbridge.client.inbound.request
    # ... plus inbound/response, outbound/request, outbound/response
  1. spec.scope — global、namespace 或 client。默认 policy 以集群作用域提供,并委托给 namespace 级和 client 级规则。
  2. policies[].path — 该 Rego 覆盖的决策点({inbound,outbound}/{request,response}.rego)。
  3. policies[].content — Rego 源码。默认规则为 fail-closed;团队可以在其上叠加 namespace 或 client 作用域的 policies,以允许特定调用方。

AuthBridge sidecar

AuthBridge 是负责强制执行身份、mTLS 和授权的数据平面组件。operator 的 mutating webhook 会将其注入到任何带有 kagenti.io/type=agent 标签的 pod 中(在启用 injectTools feature gate 时,也包括 tool),前提是全局 feature gate 已开启。

sidecar 模式可通过 spec.authBridgeMode 针对每个智能体单独选择:

模式注入内容说明
proxy-sidecar轻量级 AuthBridge proxy + spiffe-helper默认;支持 TLS bridge
envoy-sidecarEnvoy proxy + proxy-init + spiffe-helper完整的 Envoy 数据平面
lite精简版 proxy最小占用
waypoint独立 waypoint适用于 Istio ambient waypoints

Envoy/proxy 和 spiffe-helper 镜像随配套的 AuthBridge sidecar 镜像集一起提供,在启用 secure profile 时,这些镜像必须在集群中可用。

AgentRuntime 安全字段

secure profile 通过 AgentRuntime 按智能体进行配置。所有字段默认均为关闭/安全;一个完全加固的智能体如下所示:

apiVersion: agent.kagenti.dev/v1alpha1
kind: AgentRuntime
metadata:
  name: weather-agent-runtime
  namespace: agents
spec:
  type: agent
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: weather-agent
  authBridgeMode: proxy-sidecar     # proxy-sidecar (default) | envoy-sidecar | lite | waypoint 
  mtlsMode: permissive              # disabled | permissive (default) | strict 
  tlsBridgeMode: enabled            # per-agent egress CA, requires cert-manager 
  egressEnforcement: enforce-redirect
  1. authBridgeMode — 要注入的 sidecar 数据平面类型(参见上表)。
  2. mtlsMode — 智能体之间的应用层 mTLS。permissive 同时接受 TLS 和明文(用于逐步启用);strict 则要求 TLS,否则失败(生产环境)。只有在 SPIRE 可用时,MTLSReady 条件才会变为 True,它仅用于信息展示——从不阻塞 Ready。
  3. tlsBridgeMode — 通过 cert-manager 为每个智能体配置一个 CA,使 sidecar 能够检查出站 HTTPS。仅支持 proxy-sidecar / lite。

启用 secure profile

secure profile 依赖于不属于 core install 的集群组件。请先按大致如下顺序部署它们:

  1. cert-manager — 为 operator 的 webhook 证书以及 TLS-bridge / Istio CA 链签发证书。
  2. SPIRE(或 Zero-Trust Workload Identity Manager)— 签发工作负载 SVID。
  3. Keycloak — 签发并验证 OAuth2/OIDC tokens;operator 会将智能体注册为客户端。
  4. Istio(ambient) — 提供 mesh 和 ztunnel mTLS;ambient gateways 需要一个 Kuadrant 自定义资源。

随后启用 operator feature gates(featureGates.globalEnabled: true、authbridgeConfig.enabled: true),这样 AuthBridge webhook 就会开始注入 sidecar,同时使 AuthBridge sidecar 镜像可用,并设置上文所示的 AgentRuntime 安全字段。

INFO

与 core 的智能体启用相比,启用 secure profile 是一项较大的平台工程。请先在非生产集群中验证,并在切换到 strict 之前先将 mtlsMode 设为 permissive 进行分阶段发布。

使用场景

  • 智能体到智能体的授权 — 通过结合 Keycloak audience / token exchange 的 client 作用域 Rego policy,允许 Agent A 调用 Agent B,但不允许反向调用。
  • 多租户隔离 — namespace 作用域 policies 可防止某个团队的智能体访问其他团队的智能体。
  • Tool 访问控制 — 通过 injectTools feature gate 和按 client 的 policy,控制哪些工作负载可以作为 tool 使用。
  • 可验证的智能体身份 — AgentCards 使用该智能体的 SVID 进行 JWS 签名,因此消费者在信任或调用智能体之前,可以验证其证书链是否已链到 trust bundle。
  • 透明传输加密 — 将 namespace 加入 Istio ambient 后,可获得 ztunnel mTLS,而无需修改应用;同时还可以叠加可选的应用层 mTLS。

相关内容