使用 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. 已经安装 secure-profile 依赖项——cert-manager、SPIRE、Keycloak、Istio ambient mesh。请参见 安装 Secure-Profile 依赖项。
  2. 在 Kagenti operand 上已启用 secure profile(spec.featureGates.globalEnabled: true,spec.authbridgeConfig.enabled: true,并设置 spec.keycloak.publicUrl)。请参见 启用 Secure Profile。
  3. 集群内可以访问一个提供 OpenAI-compatible chat API 的 InferenceService。本指南在 models 中使用 qwen36-27b-gguf;在你看到这些名称的地方,请替换为你自己的模型——有关如何解析 LLM_API_BASE、LLM_MODEL 和 LLM_API_KEY,请参见 快速开始中的模型端点示例。
  4. 具备目标集群的 kubectl 访问权限。

创建演示 namespace 并将其纳入 secure profile:

kubectl create namespace team1
kubectl label namespace team1 kagenti-enabled=true
WARNING

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 跳转。

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: weather-tool
  namespace: team1
  labels:
    app.kubernetes.io/name: weather-tool
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: weather-tool
  template:
    metadata:
      labels:
        app.kubernetes.io/name: weather-tool
    spec:
      containers:
      - name: mcp
        image: docker.io/alaudadockerhub/weather_tool:v0.1.0-rc.1
        imagePullPolicy: IfNotPresent
        env:
        - name: PORT
          value: "8000"
        - name: HOST
          value: 0.0.0.0
        - name: UV_CACHE_DIR
          value: /app/.cache/uv
        ports:
        - containerPort: 8000
        volumeMounts:
        - mountPath: /app/.cache
          name: cache
      volumes:
      - name: cache
        emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: weather-tool-mcp
  namespace: team1
spec:
  selector:
    app.kubernetes.io/name: weather-tool
  ports:
  - name: http
    port: 8000
    targetPort: 8000
EOF

kubectl rollout status deploy/weather-tool -n team1
kubectl get pod -n team1 -l app.kubernetes.io/name=weather-tool
# NAME                            READY   STATUS    RESTARTS   AGE
# weather-tool-XXXXXXXXXX-YYYYY   1/1     Running   0          1m

READY 1/1 表示即使在 secure profile 下,tool 也仍然以单容器运行——没有注入 sidecar。

agent 和 tool 镜像必须遵守

$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。

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: weather-agent
  namespace: team1
  labels:
    app.kubernetes.io/name: weather-agent
    protocol.kagenti.io/a2a: ""
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: weather-agent
  template:
    metadata:
      labels:
        app.kubernetes.io/name: weather-agent
    spec:
      containers:
      - name: agent
        image: docker.io/alaudadockerhub/weather_service:v0.1.0-rc.1
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8000
        env:
        - name: PORT
          value: "8000"
        - name: UV_CACHE_DIR
          value: /app/.cache/uv
        - name: MCP_URL
          value: http://weather-tool-mcp.team1.svc.cluster.local:8000/mcp
        - name: LLM_API_BASE
          value: http://qwen36-27b-gguf-predictor.models.svc.cluster.local/v1
        - name: LLM_API_KEY
          value: dummy
        - name: LLM_MODEL
          value: qwen36-27b-gguf
---
apiVersion: v1
kind: Service
metadata:
  name: weather-agent
  namespace: team1
spec:
  selector:
    app.kubernetes.io/name: weather-agent
  ports:
  - name: http
    port: 8000
    targetPort: 8000
---
apiVersion: agent.kagenti.dev/v1alpha1
kind: AgentRuntime
metadata:
  name: weather-agent-runtime
  namespace: team1
spec:
  type: agent
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: weather-agent
EOF

步骤 3:验证 secure wiring

确认 AuthBridge sidecar 已注入、SPIRE 已分发 SVID,并且 operator 已为该 workload 注册 Keycloak client:

# AuthBridge sidecar container present alongside the app container
kubectl get pod -n team1 -l kagenti.io/type=agent \
  -o jsonpath='{.items[0].spec.containers[*].name}{"\n"}'
# agent authbridge-proxy

# Agent pod is 2/2 (app + sidecar); tool pod is still 1/1
kubectl get pods -n team1
# NAME                             READY   STATUS    RESTARTS   AGE
# weather-agent-XXXXXXXXX-YYYYY    2/2     Running   0          1m
# weather-tool-XXXXXXXXX-YYYYY     1/1     Running   0          6m

# SPIRE X.509 SVID mirrored into the sidecar
kubectl exec -n team1 -c authbridge-proxy \
  $(kubectl get pod -n team1 -l app.kubernetes.io/name=weather-agent -o name | head -1) \
  -- ls -l /opt/svid.pem

# Keycloak client credentials Secret created by the operator and mounted at /shared/
kubectl get secret -n team1 | grep kagenti-keycloak-client
# kagenti-keycloak-client-credentials-<hash>   Opaque   2   30s

该 Secret 包含该 workload 动态注册的 Keycloak client 的 client-id.txt 和 client-secret.txt(命名为 team1/weather-agent)。webhook 会将其挂载到 agent pod 的 /shared/ 下,AuthBridge 会从那里读取。

现在请求需要 token

启用 secure profile 后,对 agent 的未认证请求会被 AuthBridge 的 jwt-validation 插件拒绝:

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

步骤 4:发送已认证查询

由于 workload 自身的 Keycloak credentials Secret 已经挂载在集群内,验证受保护路径的最简单方式是启动一个短生命周期 pod,其执行以下操作:

  1. 将相同的 credentials Secret 挂载到 /creds/。
  2. 执行 Keycloak client_credentials grant 获取 access token。
  3. 发送带有 Authorization: Bearer <token> 的 A2A message/send 请求。

无需 port-forward,client secret 也不会离开集群。

先查找 agent 的 credentials Secret 名称:

kubectl get secret -n team1 -o name | grep kagenti-keycloak-client
# secret/kagenti-keycloak-client-credentials-<hash>

从一个 pod 中运行已认证查询。将 <credentials-secret> 替换为上一条命令输出的名称:

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: weather-query
  namespace: team1
spec:
  restartPolicy: Never
  containers:
  - name: query
    image: docker.io/alaudadockerhub/curl:8.1.2
    command: ["/bin/sh", "-c"]
    args:
    - |
      CID=$(cat /creds/client-id.txt)
      CSEC=$(cat /creds/client-secret.txt)

      # 1. Get an access token from Keycloak (client_credentials grant).
      # Use the same Keycloak hostname form set as `keycloak.publicUrl` on the
      # Kagenti operand (the JWT `iss` claim must match what AuthBridge validates).
      # The recommended in-cluster form is the short svc URL:
      TOKEN=$(curl -s \
        http://keycloak-service.keycloak.svc:8080/realms/kagenti/protocol/openid-connect/token \
        -d grant_type=client_credentials \
        --data-urlencode "client_id=$CID" \
        --data-urlencode "client_secret=$CSEC" \
        | sed 's/.*"access_token":"\([^"]*\)".*/\1/')

      # 2. Call the agent with the token in the Authorization header
      curl -sS -X POST http://weather-agent.team1.svc.cluster.local:8000/ \
        -H "Authorization: Bearer $TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","id":"1","method":"message/send","params":{"message":{"role":"user","parts":[{"kind":"text","text":"What is the weather in NY?"}],"messageId":"m1"}}}'
    volumeMounts:
    - name: creds
      mountPath: /creds
      readOnly: true
  volumes:
  - name: creds
    secret:
      secretName: <credentials-secret>
EOF

读取结果并清理:

kubectl logs weather-query -n team1
kubectl delete pod weather-query -n team1

你会得到与 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。

ModeSidecar container / image入站(client → workload)出站(workload → 其他服务)
proxy-sidecar(默认)authbridge-proxy container,image authbridge。在 workload 的 service port 上做反向代理 → JWT 验证 → 转发到应用的偏移端口。协作式:webhook 注入指向 sidecar 上 HTTP forward proxy( :8081)的 HTTP_PROXY / HTTPS_PROXY 环境变量。应用通过遵循这些环境变量来选择接入。
envoy-sidecarenvoy-proxy container,image authbridge-envoy(Envoy + authbridge 作为 ext_proc)。额外添加一个安装 iptables 规则的 proxy-init initContainer。透明重定向:iptables 将入站流量发送到 Envoy,Envoy 再通过 gRPC ext_proc 调用 authbridge 进行 JWT 验证。透明式:iptables 将出站 TCP 重定向到 Envoy 的 outbound listener。应用上不会设置 HTTP_PROXY 环境变量。

选择模式

mode 的解析顺序如下(第一个非空项生效):

  1. namespace ConfigMap authbridge-runtime-config —— config.yaml 中的 mode: 字段。
  2. 集群范围默认值:proxy-sidecar。

要将某个 namespace 切换为 envoy-sidecar,请应用一个 ConfigMap 并重启 agent 和 tool Deployment(参见 模式变更后的重新加载):

apiVersion: v1
kind: ConfigMap
metadata:
  name: authbridge-runtime-config
  namespace: team1
data:
  config.yaml: |
    mode: envoy-sidecar
    mtls:
      mode: disabled
WARNING

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 逃逸通道;后续会在 Kagenti operand 上增加一个 spec.egressBypass 字段,并将其下发到 proxy-init 的 OUTBOUND_PORTS_EXCLUDE / hosts allowlist。

当前版本建议: 在生产环境中使用 proxy-sidecar。它的入站 JWT 验证以及 NO_PROXY 出站 egress 选项(见下文)都已完成端到端验证。envoy-sidecar 适合用于启动和检查数据路径,但在上述两个问题修复之前,不应将其用于生产认证强制执行。

模式变更后的重新加载

manager 和按 workload 注入的配置都会在 pod 创建时缓存,因此模式变更需要三个操作:

# 1. Roll the operator so it picks up the new namespace ConfigMap.
kubectl -n kagenti-system rollout restart deploy/kagenti-controller-manager

# 2. Delete stale per-workload ConfigMaps so the webhook re-renders them
#    with the new mode. (Kept for both modes; the operator preserves
#    existing values, see issue upstream #433.)
kubectl -n team1 delete cm envoy-config-weather-agent envoy-config-weather-tool 2>/dev/null

# 3. Recycle the workloads so the webhook re-injects the sidecars.
kubectl -n team1 rollout restart deploy/weather-agent deploy/weather-tool

确认注入已按预期发生:

# proxy-sidecar: container "authbridge-proxy" runs image "authbridge:..."
# envoy-sidecar: container "envoy-proxy" runs image "authbridge-envoy:...",
#                and an "proxy-init" initContainer appears.
kubectl -n team1 get pod -l app=weather-agent -o jsonpath='{range .spec.containers[*]}{.name}={.image}{"\n"}{end}'

何时使用每种模式

在以下任一场景下使用 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 时,有两个后果需要了解:

  1. 集群内 HTTP 可以直接使用,无需配置(agent → tool、LLM)。

  2. 外部 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 可以干净地覆盖默认值:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: weather-tool
      namespace: team1
    spec:
      template:
        spec:
          containers:
          - name: mcp                 # the app container, not the sidecar
            env:
            - name: NO_PROXY
              value: "127.0.0.1,localhost,.svc,.svc.cluster.local,geocoding-api.open-meteo.com,api.open-meteo.com"

    效果:所有未被 NO_PROXY 匹配到的主机,其出站调用仍会通过 AuthBridge sidecar 路由(并且仍然可以进行出站 token exchange、tracing 等);列出的公共 API 调用则绕过 sidecar,直接通过 pod 的默认 egress。流量最终是否真的到达公共目标地址,取决于集群的 egress network policy,而不是 AuthBridge。

    INFO

    只添加你确实需要外部访问的主机。NO_PROXY 中的每一项都会在出站检查路径上留下一个缺口——sidecar 将无法再为该主机名注入 Bearer token。

清理

kubectl delete namespace team1

这会删除演示 namespace 及其中的一切内容。集群范围的 secure-profile 安装内容(SPIRE、Keycloak、Istio ambient、Kagenti operand)不会受到影响。

故障排查

症状检查项
未认证请求被拒绝并返回 auth.unauthorized这是预期行为——secure profile 需要有效的 Bearer token。有关 client credentials 的操作方法,请参见 步骤 4。
带 token 的请求返回 401JWT iss claim 不匹配:获取 token 所用的 Keycloak hostname 与 Kagenti operand 上设置的 keycloak.publicUrl 不是同一个。请从与 AuthBridge 验证时所使用的相同 hostname 获取 token(通常是 http://keycloak-service.keycloak.svc:8080)。
Agent pod 一直停留在 1/1 而不是 2/2sidecar 未注入。检查 namespace 标签(kagenti-enabled=true)、Kagenti operand(featureGates.globalEnabled: true、authbridgeConfig.enabled: true),以及 AgentRuntime 是否已完成调谐(kubectl describe agentruntime weather-agent-runtime -n team1)。
namespace 中没有 kagenti-keycloak-client-credentials-* SecretKeycloak client 注册尚未完成。检查 kagenti-controller-manager 日志中的 ClientRegistrationReconciler 错误,并确认 kagenti-system 中存在 keycloak-admin-secret。
tool 返回“weather service temporarily unavailable”tool 的 get_weather 调用会访问 geocoding-api.open-meteo.com——一个公共 HTTPS endpoint。使用推荐模式(tool 上不注入 sidecar)时,它会直接工作。如果你把 sidecar 注入到了 tool 中,那么 HTTP_PROXY 环境变量会让 HTTPS 通过 AuthBridge,而 AuthBridge 会以 405 拒绝 CONNECT;请改回无 sidecar 布局,或者将目标添加到 NO_PROXY——参见 在 proxy-sidecar 模式下允许出站流量。
AuthBridge image 出现 ImagePullBackOffKagenti operand 上的 defaults.images 指向了集群无法拉取的 registry。请将 AuthBridge sidecar images 重新定位到集群可访问的 registry(参见 启用 Secure Profile)。
AgentRuntime 上的 MTLSReady=False确认 SPIRE 已安装,并且其 trust domain 与 operand 上的 defaults.spiffe.trustDomain 一致。在 proxy-sidecar 模式下,sidecar 即使没有 mTLS 也仍然可以验证 JWT——对于 smoke test 来说,真正需要关注的是 Ready=True。