使用 Secure Profile 的演示
本指南会在 secure profile 下重新运行来自 使用 Core Profile 的快速开始 的 weather-agent 场景——会将 AuthBridge sidecar 注入到 agent 中,operator 为每个 workload 注册一个 Keycloak client,SPIRE 分发一个 workload SVID,并且每个请求都必须携带有效的 Bearer token。tool workload 仍然以普通 Deployment 的形式运行,不带 sidecar;这与上游 weather-agent 演示模式一致,并且让 tool 到公共地理编码 API 的出站调用继续走 pod 的默认 egress 路径。
如果你想要一个更严格的变体——tool 也使用 AuthBridge,且 agent 与 tool 之间通过 RFC 8693 token exchange——请在本指南之后继续阅读 高级演示。
目录
前提条件步骤 1:部署 MCP tool server步骤 2:部署受保护的 agent步骤 3:验证 secure wiring步骤 4:发送已认证查询AuthBridge 部署模式选择模式模式变更后的重新加载何时使用每种模式在proxy-sidecar 模式下允许出站流量清理故障排查前提条件
开始之前,请确认:
- 已经安装 secure-profile 依赖项——cert-manager、SPIRE、Keycloak、Istio ambient mesh。请参见 安装 Secure-Profile 依赖项。
- 在
Kagentioperand 上已启用 secure profile(spec.featureGates.globalEnabled: true,spec.authbridgeConfig.enabled: true,并设置spec.keycloak.publicUrl)。请参见 启用 Secure Profile。 - 集群内可以访问一个提供 OpenAI-compatible chat API 的 InferenceService。本指南在
models中使用qwen36-27b-gguf;在你看到这些名称的地方,请替换为你自己的模型——有关如何解析LLM_API_BASE、LLM_MODEL和LLM_API_KEY,请参见 快速开始中的模型端点示例。 - 具备目标集群的
kubectl访问权限。
创建演示 namespace 并将其纳入 secure profile:
kagenti-enabled=true 标签是必需的。没有它,operator 不会为该 namespace 创建 authbridge-config ConfigMap,也不会启动工作负载的 Keycloak client 注册流程,并且由于缺少 credentials Secret,所有 pod 都会一直处于 pending 状态。
步骤 1:部署 MCP tool server
tool workload 与 core-profile 版本 完全相同。它以普通 Deployment 运行,不包含 AgentRuntime 也不包含 AuthBridge sidecar——对 tool workload 的 sidecar 注入默认是关闭的(spec.featureGates.injectTools: false),因此即使你尝试仅为 Deployment 添加 kagenti.io/type: tool 标记,也不会注入 sidecar。此处的安全模型是仅对 agent 做入站保护:agent 的 AuthBridge 验证客户端的 JWT,然后 agent → tool 调用仅是一次集群内的普通 HTTP 跳转。
READY 1/1 表示即使在 secure profile 下,tool 也仍然以单容器运行——没有注入 sidecar。
$PORT
在 secure profile 下,AuthBridge proxy-sidecar 会绑定 workload 的 service port,而 operator 会将应用重新映射到另一个 PORT 值。硬编码端口的镜像会与反向代理冲突(address already in use)。上游 weather_service / weather_tool 镜像从 v0.1.0 开始遵守 PORT,因此无需修改即可使用。
步骤 2:部署受保护的 agent
agent 的 Deployment、Service 和 AgentRuntime 与 core-profile 快速开始 中相同——不需要任何 secure-profile 专属字段,因为 AuthBridge webhook 会在 admission 时根据 Kagenti operand 和 namespace 标签完成所有挂载与注入工作。AgentRuntime 会触发 mutating webhook 注入 sidecar,并挂载 operator 创建的 Keycloak client Secret。
步骤 3:验证 secure wiring
确认 AuthBridge sidecar 已注入、SPIRE 已分发 SVID,并且 operator 已为该 workload 注册 Keycloak client:
该 Secret 包含该 workload 动态注册的 Keycloak client 的 client-id.txt 和 client-secret.txt(命名为 team1/weather-agent)。webhook 会将其挂载到 agent pod 的 /shared/ 下,AuthBridge 会从那里读取。
启用 secure profile 后,对 agent 的未认证请求会被 AuthBridge 的 jwt-validation 插件拒绝:
步骤 4:发送已认证查询
由于 workload 自身的 Keycloak credentials Secret 已经挂载在集群内,验证受保护路径的最简单方式是启动一个短生命周期 pod,其执行以下操作:
- 将相同的 credentials Secret 挂载到
/creds/。 - 执行 Keycloak
client_credentialsgrant 获取 access token。 - 发送带有
Authorization: Bearer <token>的 A2Amessage/send请求。
无需 port-forward,client secret 也不会离开集群。
先查找 agent 的 credentials Secret 名称:
从一个 pod 中运行已认证查询。将 <credentials-secret> 替换为上一条命令输出的名称:
读取结果并清理:
你会得到与 core-profile 第 4 步 相同的已完成 A2A task——现在是通过已认证、经过 JWT 验证的路径完成的。
如果要从集群外部调用 agent,则应先从通过 Ingress/Gateway 暴露的 Keycloak endpoint 请求 token,然后使用相同的 Authorization: Bearer <token> header 将请求发送到 agent 的暴露端点。token 请求是标准的 OIDC 调用:POST <keycloak>/realms/kagenti/protocol/openid-connect/token,并带上 grant_type=client_credentials、client_id 和 client_secret。
AuthBridge 部署模式
AuthBridge 可以以两种形态注入。mode 决定要添加哪种 sidecar image、如何验证入站流量,以及如何拦截出站流量。它是按 namespace 生效的默认值(管理员级别的开关),不是按 workload 生效——该 namespace 中的所有 agent 和 MCP tool 都共享同一种 mode。
选择模式
mode 的解析顺序如下(第一个非空项生效):
- namespace ConfigMap
authbridge-runtime-config——config.yaml中的mode:字段。 - 集群范围默认值:
proxy-sidecar。
要将某个 namespace 切换为 envoy-sidecar,请应用一个 ConfigMap 并重启 agent 和 tool Deployment(参见 模式变更后的重新加载):
envoy-sidecar 在当前版本中可正常启动并运行,且 mtls.mode: permissive 下表现正常——authbridge-envoy 二进制会通过 go-spiffe 在进程内将 X.509 SVID 写入 /opt/svid*.pem,这正是 operator 的 Envoy filesystem-SDS 配置所期望的行为。不过,当前仍有两个 operator 模板方面的缺口,正在跟进后续版本:
- 入站认证强制执行:Envoy 配置模板会在 route 级别注入
x-authbridge-direction: inbound,而 router filter 会在ext_proc之后应用该 header。因此 AuthBridge 会将入站请求归类为出站请求并应用默认透传策略——JWT-validation 插件不会运行。后续补丁会把该 header 注入移动到位于ext_proc之前的 Lua HTTP filter 中。 - 通过 sidecar 的外部 HTTPS:Envoy 的 outbound listener 假定流量是 HTTP,因此到任意公共主机的 client TLS handshake 会被解析成 HTTP 并被破坏。此模式下没有
NO_PROXY逃逸通道;后续会在Kagentioperand 上增加一个spec.egressBypass字段,并将其下发到proxy-init的OUTBOUND_PORTS_EXCLUDE/ hosts allowlist。
当前版本建议: 在生产环境中使用 proxy-sidecar。它的入站 JWT 验证以及 NO_PROXY 出站 egress 选项(见下文)都已完成端到端验证。envoy-sidecar 适合用于启动和检查数据路径,但在上述两个问题修复之前,不应将其用于生产认证强制执行。
模式变更后的重新加载
manager 和按 workload 注入的配置都会在 pod 创建时缓存,因此模式变更需要三个操作:
确认注入已按预期发生:
何时使用每种模式
在以下任一场景下使用 proxy-sidecar(默认值)——这是当前版本经过测试并受支持的路径:
- 你需要 sidecar 到 sidecar 的 mTLS(
permissive或strict)。 - 你只是在调用其他集群内 HTTP 服务(agent → MCP tool、LLM InferenceService 等),不需要
CONNECT隧道。 - workload 不需要 SPIRE。
在以下情况下使用 envoy-sidecar:
- 你明确需要数据路径上的 Envoy 路由 / 可观测性功能。
- 你需要透明的 iptables 拦截(应用上不设置
HTTP_PROXY)。
在 proxy-sidecar 模式下允许出站流量
本指南所遵循的上游 weather-agent 演示模式——tool workload 上不使用 AgentRuntime,也不注入 sidecar(spec.featureGates.injectTools: false 是 operand 默认值)——完全绕开了这个问题:tool 作为单容器运行,没有 HTTP_PROXY/HTTPS_PROXY 环境变量,因此它对公共 API 的出站调用会直接通过 pod 的默认 egress。对于 tool 不需要自己的入站 JWT 验证或出站 token exchange 的场景,这是推荐的布局。
本节其余内容仅适用于你故意将 AuthBridge sidecar 注入到一个也需要外部 HTTPS 的 workload 中的情况——例如在 Kagenti operand 上将 injectTools: true 打开(参见 高级演示),或者在单独的 Deployment 上添加 kagenti.io/authbridge-inject: "true"。AuthBridge 的 HTTP forward proxy 仅支持 HTTP——它会对 CONNECT 返回 405 Method Not Allowed,因此通过 sidecar 发起出站 HTTPS 请求的注入式应用会遇到 Tunnel connection failed: 405。这属于设计如此:出站 token-exchange 插件需要读取并修改请求 header,而这在透明的 TLS tunnel 中是不可能实现的。
当一个出站流量很多的 workload 配置了 sidecar 时,有两个后果需要了解:
-
集群内 HTTP 可以直接使用,无需配置(agent → tool、LLM)。
-
外部 HTTPS(例如 weather MCP tool 使用的公共 API
geocoding-api.open-meteo.com)需要绕过 sidecar。请将目标主机名添加到 app container 的NO_PROXY中。kagenti webhook 只有在容器上尚未存在这些变量时,才会设置HTTP_PROXY/HTTPS_PROXY/NO_PROXY,因此在 workload 上预先声明NO_PROXY可以干净地覆盖默认值:效果:所有未被
NO_PROXY匹配到的主机,其出站调用仍会通过 AuthBridge sidecar 路由(并且仍然可以进行出站 token exchange、tracing 等);列出的公共 API 调用则绕过 sidecar,直接通过 pod 的默认 egress。流量最终是否真的到达公共目标地址,取决于集群的 egress network policy,而不是 AuthBridge。INFO只添加你确实需要外部访问的主机。
NO_PROXY中的每一项都会在出站检查路径上留下一个缺口——sidecar 将无法再为该主机名注入 Bearer token。
清理
这会删除演示 namespace 及其中的一切内容。集群范围的 secure-profile 安装内容(SPIRE、Keycloak、Istio ambient、Kagenti operand)不会受到影响。