ACS Kubernetes Istio 参考架构基于 OPA 旁车的 Agent 治理部署实战指南【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit导读本文是 ACSAgent Control Specification在 Kubernetes Istio 服务网格中的参考部署指南面向需要为 AI Agent 工作负载落地策略执行的平台工程师与安全工程师。通过阅读本文你将掌握如何以应用进程内嵌 ACS SDK OPA 回环地址旁车 Istio Envoy 旁车的三层拓扑组织一个受治理的 Agent 服务理解六个策略干预点intervention point的挂载方式并学会用 ConfigMap Rego 将提示注入拦截、工具参数限额、密钥泄露防护等策略落到真实集群清单上。文中所有清单均来自仓库policy-engine/deploy/kubernetes/acs-sidecar-reference下的可审查参考实现可作为平台评审与生产改造的起点。一、架构定位ACS 不是旁车而是嵌入应用进程的策略运行时本参考架构解决的核心问题是一个 Agent 工作负载如何在 Kubernetes 中同时获得两层正交的保护ACS 层负责模型语义与工具语义的治理——提示注入、角色越权、工具参数限额、工具输出注入、密钥泄露等服务网格层Istio负责传输安全与工作负载身份——mTLS、SPIFFE 身份、旁车遥测与流量策略挂载点。两层保护彼此不互相替代。正如 deploy-istio-reference.md 明确指出的Envoy 看不到模型请求结构、工具参数、工具结果、transform 判定、注解值或宿主调用路径——即使网络路径启用 STRICT mTLS一条未受防护的模型调用或工具调用依然处于 ACS 保护之外。反过来ACS 也不拥有凭据、出口流量、ServiceAccount 权限或数据面路由。这一拓扑的完整示意图与资源文件清单见 deploy/kubernetes/acs-sidecar-reference/README.md其架构可以概括为Caller | v Istio ingress or east west mesh | v Pod in acs-agents - app container with ACS SDK integration - OPA sidecar on 127.0.0.1:8181 - Envoy sidecar injected by Istio - ConfigMap mounted at /etc/acs and /policy需要特别强调的是该清单是设计参考design reference不是经过 CI 验证的集群工件。原文与目录内 README 均声明它未经测试、未经 CI 验证生产使用前必须替换镜像、补齐探针、资源限额与真实策略内容并运行真实集群测试。二、分层职责ACS、Istio、OPA 各自管什么参考架构把职责划分得非常清晰理解这一点是安全评审的前提。2.1 ACS嵌入应用进程的决策运行时应用进程内嵌一个 ACS SDK。宿主host在六个干预点调用 ACS并传入完整快照complete snapshot干预点保护对象示例策略input进入 Agent 循环的入口数据用户输入、外部请求数据拦截已知的提示注入标记pre_model_call组装完成的模型请求消息、角色拒绝将不受信文本放入 system 角色、拒绝危险工具计划post_model_call模型返回的响应拒绝未经批准的资金操作提案pre_tool_call将要执行的确切工具名称与参数对实际执行的参数强制限额post_tool_call工具执行结果在模型复用/存储/披露前拦截工具输出注入output最终组装完成的响应在披露前拦截密钥标记每个干预点上的运行时行为是构建规范化的策略输入canonical policy input→ 解析配置的策略目标policy target→ 为工具干预点投影工具元数据 → 调用宿主策略分发器policy dispatcher→ 规范化判定verdict→ 校验任何transform判定 → 返回决策。deny 判定会阻断受保护路径上的操作运行时错误与分发器失败应 fail closed失败即拒绝。关于快照与运行时语义的进一步说明可参考 stateless-runtime.mdACS 是无状态、确定性的干预点策略运行时一次调用只评估一个宿主提供的完整快照。2.2 Istio只做服务网格的事Istio 负责 mTLS、工作负载身份SPIFFE、旁车遥测以及 Kubernetes Service 的流量策略挂载点。它不介入 ACS 策略判定——网格不理解快照、策略目标、工具元数据、transform 判定或干预点。这意味着一个安全结论必须被反复强调启用 STRICT mTLS ≠ Agent 语义受治理。若应用内部存在未包裹unwrapped的模型或工具引用Kubernetes 与 Istio 都检测不到这条绕过路径。应用集成契约要求宿主只能发布受治理的对象guarded model/tool/runner/middleware/hook/provider/filter保留未包裹的引用即制造绕过路径。2.3 OPA回环地址上的策略执行旁车参考架构使用 OPA 旁车但刻意将其限制在 Pod 内部应用容器与 OPA 容器挂载同一个 ConfigMap应用读取/etc/acs/manifest.yamlOPA 加载/policy/acs_sidecar_reference.rego应用策略分发器把每条 Rego 查询发送到 Pod 内http://127.0.0.1:8181回环地址让策略评估保持 Pod 本地化避免把 OPA 暴露为 Kubernetes Service分发器dispatcher属于宿主边界负责超时、重试、错误映射与 fail closed 行为。在 deployment.yaml 中OPA 以--addr127.0.0.1:8181启动并run --server只监听回环地址而 service.yaml 只暴露应用容器的 8080 端口OPA 端口不出 Pod。三、六个干预点的 Manifest 绑定以 ConfigMap 为单一策略载体参考实现的策略载体是一个 ConfigMap——acs-policy-configmap.yaml它同时存放manifest.yamlACS 清单与acs_sidecar_reference.rego策略规则并在 Deployment 中分别挂载到/etc/acs与/policy。3.1 Manifest 结构策略目标与 Rego 查询Manifest 的关键字段包括agent_control_specification_version清单格式版本示例为0.4.0-alpha.1用于保证跨 SDK 的契约一致性metadata清单名称与版本extends继承的父清单列表示例为空policies策略声明type: rego且bundle: /policy指向 OPA 的 Rego 包目录intervention_points六个干预点与各自policy_targetJSONPath 表达式和querydata.agent_control_specification.acs_sidecar_reference.point_verdict的绑定tools工具元数据type、id、clearance、security_labels供pre_tool_call投影。六个干预点在 manifest 中的完整绑定如下节选自 ConfigMap 数据干预点policy_target查询目标input$.input...input_verdictpre_model_call$.model_request...pre_model_call_verdictpost_model_call$.model_response...post_model_call_verdictpre_tool_call$.tool_call.args...pre_tool_call_verdictpost_tool_call$.tool_result...post_tool_call_verdictoutput$.output...output_verdict工具声明示例manifest 中真实存在tools: search_knowledge: type: Tool id: search_knowledge clearance: [public, internal] security_labels: [retrieval] send_email: type: Tool id: send_email clearance: [internal] security_labels: [external_communication] transfer_funds: type: Tool id: transfer_funds clearance: [confidential, payments] security_labels: [payment_instruction]从stateless-runtime.md可以看出policy_target的取值空间为$snap、$、$.field三种别名而transform.path仅允许指向$target即只能作用于策略目标本身不能触碰原始快照、注解或隐藏宿主状态。3.2 Rego 规则六类可运行的示例策略acs_sidecar_reference.rego包agent_control_specification.acs_sidecar_reference为六个干预点各定义一个默认 allow 的判定并实现了一组**说明性illustrative**规则。原文强调这些规则只是示例真实系统必须替换为经过评审的策略。其完整内容含deny辅助函数如下package agent_control_specification.acs_sidecar_reference import rego.v1 default input_verdict : {decision: allow} default pre_model_call_verdict : {decision: allow} default post_model_call_verdict : {decision: allow} default pre_tool_call_verdict : {decision: allow} default post_tool_call_verdict : {decision: allow} default output_verdict : {decision: allow} input_verdict : deny(prompt_injection_marker, Input contained an instruction override marker.) if { target_text : lower(sprintf(%v, [input.policy_target])) contains(target_text, ignore previous instructions) } pre_model_call_verdict : deny(untrusted_system_message, Model request attempted to place untrusted text in a system role.) if { message : input.policy_target.messages[_] lower(object.get(message, role, )) system content : lower(sprintf(%v, [object.get(message, content, )])) contains(content, from user upload) } post_model_call_verdict : deny(unsafe_tool_plan, Model response proposed an unsafe payment action.) if { response_text : lower(sprintf(%v, [input.policy_target])) contains(response_text, transfer_funds) contains(response_text, without approval) } pre_tool_call_verdict : deny(payment_limit_exceeded, Payment tool arguments exceeded the reference limit.) if { input.tool.id transfer_funds amount : to_number(object.get(input.policy_target, amount, 0)) amount 1000 } post_tool_call_verdict : deny(tool_output_injection, Tool output contained an instruction override marker.) if { result_text : lower(sprintf(%v, [input.policy_target])) contains(result_text, ignore all policy) } output_verdict : deny(secret_disclosure, Final output attempted to disclose a secret marker.) if { output_text : lower(sprintf(%v, [input.policy_target])) contains(output_text, secret_) } deny(reason, message) : { decision: deny, reason: reason, message: message, }这些规则覆盖了 Agent 治理中最典型的四类风险提示注入input输入文本命中ignore previous instructions即 deny角色越权pre_model_callsystem 角色内容中出现from user upload即 deny——防止不受信上传内容混入高权限系统提示危险工具计划与参数越权post_model_call/pre_tool_call模型响应同时出现transfer_funds与without approval即 denytransfer_funds工具的单笔amount超过 1000 即 deny——注意这里评估的是将要实际执行的精确参数工具输出注入与密钥泄露post_tool_call/output工具结果出现ignore all policy、最终输出出现secret_标记即 deny。判定对象统一为{decision, reason, message}形状便于宿主分发器规范化处理。ACS 对判定的处理语义allow/warn/deny/escalate/transform中仅transform可变更策略目标且只在enforce模式下生效可参见 stateless-runtime.md 第 71–75 行。四、部署清单全解从命名空间到 Deploymentkustomization.yaml将全部资源聚合为一个可kubectl apply -k的清单组apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization namespace: acs-agents resources: - namespace.yaml - acs-policy-configmap.yaml - deployment.yaml - service.yaml - peer-authentication.yaml - destination-rule.yaml4.1 命名空间与网格开关namespace.yaml 创建acs-agents命名空间并通过标签istio-injection: enabled开启自动注入使该命名空间内的 Pod 自动获得 Envoy 旁车apiVersion: v1 kind: Namespace metadata: name: acs-agents labels: istio-injection: enabled app.kubernetes.io/part-of: acs-sidecar-reference4.2 Deployment应用 OPA 双容器deployment.yaml 是拓扑的核心。其要点replicas: 2应用容器监听 8080/health就绪/存活探针应用容器通过环境变量装配 ACSACS_MANIFEST_PATH/etc/acs/manifest.yaml、ACS_POLICY_BUNDLE_PATH/policy、ACS_POLICY_DISPATCHERopa-http、ACS_OPA_URLhttp://127.0.0.1:8181、ACS_MODEenforce、OTEL_SERVICE_NAMEacs-mediated-app同一 ConfigMap 卷acs-policy以只读方式挂载两处/etc/acsmanifest与/policyRego 包OPA 容器镜像ghcr.io/open-policy-agent/opa:0.68.0-rootless以run --server --addr127.0.0.1:8181启动加载/policy只监听回环地址。完整 Deployment 如下apiVersion: apps/v1 kind: Deployment metadata: name: acs-mediated-app namespace: acs-agents labels: app.kubernetes.io/name: acs-mediated-app app.kubernetes.io/part-of: acs-sidecar-reference spec: replicas: 2 selector: matchLabels: app.kubernetes.io/name: acs-mediated-app template: metadata: labels: app.kubernetes.io/name: acs-mediated-app app.kubernetes.io/part-of: acs-sidecar-reference spec: containers: - name: app image: ghcr.io/your-org/acs-mediated-app:latest imagePullPolicy: IfNotPresent ports: - name: http containerPort: 8080 env: - name: ACS_MANIFEST_PATH value: /etc/acs/manifest.yaml - name: ACS_POLICY_BUNDLE_PATH value: /policy - name: ACS_POLICY_DISPATCHER value: opa-http - name: ACS_OPA_URL value: http://127.0.0.1:8181 - name: ACS_MODE value: enforce - name: OTEL_SERVICE_NAME value: acs-mediated-app volumeMounts: - name: acs-policy mountPath: /etc/acs readOnly: true - name: acs-policy mountPath: /policy readOnly: true readinessProbe: httpGet: path: /health port: http initialDelaySeconds: 5 periodSeconds: 10 livenessProbe: httpGet: path: /health port: http initialDelaySeconds: 10 periodSeconds: 10 - name: opa image: ghcr.io/open-policy-agent/opa:0.68.0-rootless imagePullPolicy: IfNotPresent args: - run - --server - --addr127.0.0.1:8181 - --log-levelinfo - /policy ports: - name: opa-http containerPort: 8181 volumeMounts: - name: acs-policy mountPath: /policy readOnly: true volumes: - name: acs-policy configMap: name: acs-policy-bundle items: - key: manifest.yaml path: manifest.yaml - key: acs_sidecar_reference.rego path: acs_sidecar_reference.rego生产改造要点原文明确要求替换占位镜像ghcr.io/your-org/acs-mediated-app:latest、固定镜像版本、补充资源限额resource limits、保护 ConfigMap 更新、选用生产级 OPA 版本、补齐与业务匹配的健康/就绪语义。4.3 Service 与 mTLS传输层强制的两把锁service.yaml 将应用暴露为 ClusterIP Service8080 → 容器 8080OPA 不在 Service 内。peer-authentication.yaml 在命名空间层面强制 STRICT mTLSapiVersion: security.istio.io/v1 kind: PeerAuthentication metadata: name: default namespace: acs-agents spec: mtls: mode: STRICTdestination-rule.yaml 为网格内调用方请求ISTIO_MUTUALapiVersion: networking.istio.io/v1 kind: DestinationRule metadata: name: default namespace: acs-agents spec: host: *.acs-agents.svc.cluster.local trafficPolicy: tls: mode: ISTIO_MUTUAL4.4 一键应用与镜像替换使用 kustomize 直接应用整个参考清单kubectl apply -k deploy/kubernetes/acs-sidecar-reference替换占位镜像的方式README 给出的片段spec: template: spec: containers: - name: app image: registry.example.com/team/acs-mediated-app:v0.1.0五、验证路径从集群引导到探测脚本5.1 本地集群引导说明性脚本setup-kind-istio.sh 是未经测试的说明性引导脚本其流程为创建 kind 集群kindest/node:v1.30.0→ 安装 Istio demo profile →kubectl apply -k应用参考清单 → 提示替换镜像后运行 test.sh。脚本要求本机具备kind、kubectl、istioctl。5.2 探测脚本做了什么test.sh 同样是未经测试的说明性探测脚本它验证了参考架构的四个关键断言可作为平台评审时的检查清单模板mTLS 资源PeerAuthentication的spec.mtls.mode必须为STRICTDestinationRule的trafficPolicy.tls.mode必须为ISTIO_MUTUALPod 容器构成Pod 内必须同时存在opa与istio-proxy容器健康探测通过kubectl port-forward转发svc/acs-mediated-app后GET /health期望 2xx策略行为探测向/chatPOST 正常消息期望 2xxallow 路径POST{message:ignore previous instructions}期望 4xxdeny 路径默认接受400|403|422。脚本大量使用环境变量做覆盖NAMESPACE、SERVICE、PORT、ALLOW_PAYLOAD、DENY_PAYLOAD等便于在不改动脚本的情况下适配真实业务。探测命令为bash deploy/kubernetes/acs-sidecar-reference/test.sh需要再次强调脚本假设替换后的应用暴露/health与/chat接口它只是参考探测不代表本仓库拥有经过测试的集群。六、信任边界与 fail closed 语义参考架构的信任边界划分非常明确security-model.md 提供了更完整的威胁模型支撑。**可信计算基TCB**包括应用集成代码、选定的 ACS SDK、Rust 核心、manifest、Rego bundle、分发器、OPA 二进制、应用镜像、Kubernetes 控制面以及保护工作负载身份与挂载产物的网格配置。不可信主体包括用户、检索内容作者、模型输出、工具结果以及下游文本——直到 ACS 允许相应转换transition为止。后端服务仍须自行负责其授权、幂等、审计与事务控制。三条边界各司其职README 的归纳网格边界保护 Pod 间传输标识工作负载ACS 边界仅在宿主将模型/工具语义路由经过运行时的情况下保护这些语义OPA 边界接收 ACS 选定的规范化策略输入返回判定形状对象OPA 不可达或返回非法输出时分发器错误路径应产生 fail closed 的 deny。结合 stateless-runtime.md 的实现语义运行时验证失败、路径解析失败、注解分发失败、策略分发失败、策略输出规范化失败、transform 校验失败全部 fail closed。同时遥测事件只携带内容安全的元数据干预点、模式、策略 id、判定、原因码、错误类、时长、transform 状态、操作身份绝不携带策略目标值、工具参数/结果、注解值、模型消息、密钥或 PII——这为审计提供了最小遥测的落地样板。七、从参考到生产平台评审清单将参考架构投入生产前原文给出明确的改造义务汇总为可操作的清单替换占位镜像将ghcr.io/your-org/acs-mediated-app:latest替换为真实内嵌 ACS SDK 的应用镜像并固定版本固定镜像版本应用与 OPA参考为0.68.0-rootless镜像均需固定 digest/版本禁用latest补充资源限额为 app 与 opa 容器配置 requests/limits防止策略评估挤占业务资源或 OOM保护 ConfigMap 更新策略即代码manifest 与 Rego 的更新需走评审、签名或不可变发布流程避免被篡改选择生产 OPA 版本参考版本只是示例需按 OPA 官方支持策略选定生产版本补齐健康/就绪语义探针路径与业务匹配并考虑将 OPA 可达性纳入就绪判断真实集群测试在 CI 或预发集群上跑完整 e2e验证 fail closed 行为、探测脚本断言与策略命中率宿主集成契约只发布受治理的 model/tool/runner/middleware/hook/provider/filter 对象保留未包裹引用即制造 Istio 与 Kubernetes 都无法检测的绕过路径output与流式场景应使用先缓冲、后披露模式因为 ACS 评估的是完整快照。八、总结本参考架构回答了一个关键命题在 Kubernetes Istio 环境中如何让传输层安全mTLS与 Agent 语义层治理ACS各司其职、互不替代。其核心设计决策包括ACS SDK 嵌入应用进程而非作为旁车、OPA 通过回环地址保持 Pod 本地策略评估、一个 ConfigMap 同时承载 manifest 与 Rego、命名空间级 STRICT mTLS DestinationRule 双锁传输、以及默认 deny、失败即关的判定语义。所有清单与脚本都位于 policy-engine/deploy/kubernetes/acs-sidecar-reference 目录威胁模型与运行时语义分别在 security-model.md 与 stateless-runtime.md 中展开。它们是平台评审的起点而非终点——在依赖该架构之前请完成清单改造并运行真实集群测试。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考