#安全架构

除了注册和发现智能体之外，Kagenti Operator 还可以为你的智能体接入一套 zero-trust 安全栈：工作负载身份、传输加密和请求授权。本页将说明这些组件如何协同工作，以便你决定要启用哪些能力。

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

#概览

三个关注点对应三种技术，并由 operator 注入到每个智能体 Pod 中的 AuthBridge sidecar 串联起来：

经过安全保护的智能体，其请求路径如下：

                       ┌──────────────────────── 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.

#工作负载身份（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 状态条件上报。（即使在核心 profile 中也会应用该 label，这就是你在那里看到 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. 身份 / token —— operator 会在 Keycloak 中将智能体注册为一个 OAuth2 client。其凭据会写入 Secret 并挂载到 Pod 中；sidecar 会根据 Keycloak 的 issuer 和 audience 获取并验证 JWTs。token exchange 支持 tool-to-agent delegation。
2. Policy —— 一个 AuthorizationPolicy 自定义资源保存一个或多个 Rego policies。bundle-service 会将它们编译为 OPA bundle，并按身份提供服务；AuthBridge sidecar 会拉取与其 SPIFFE ID 匹配的 bundle。
3. Decision —— AuthBridge 会在四个点进行 policy 评估：inbound/outbound × request/response，并且采用 fail-closed（default allow := false）。

policy 的作用域采用三层层级：

#示例：全局 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

#AuthBridge sidecar

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

sidecar 模式通过 spec.authBridgeMode 按智能体进行选择：

Envoy/proxy 和 spiffe-helper 镜像随配套的 AuthBridge sidecar 镜像集合一起提供；在启用安全 profile 时，这些镜像必须可供集群使用。

#AgentRuntime 安全字段

安全 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

#启用安全 profile

安全 profile 依赖于不属于核心安装的集群组件。请先按大致如下顺序部署它们：

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

然后启用 operator feature gate（featureGates.globalEnabled: true、authbridgeConfig.enabled: true），使 AuthBridge webhook 开始注入，准备好 AuthBridge sidecar 镜像，并设置上面显示的 AgentRuntime 安全字段。

#使用场景

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

#相关内容

• Introduction — 核心 profile 和 CRD 概览。
• Installation — 安装 operator 并创建 Kagenti operand。
• Deploy an Agent with AgentRuntime — 核心智能体 + MCP 工作流。