企业官网建设流程全解析

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

导读：本文是 ACS（Agent 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）：

每个干预点上的运行时行为是：构建规范化的策略输入（canonical policy input）→ 解析配置的策略目标（policy target）→ 为工具干预点投影工具元数据 → 调用宿主策略分发器（policy dispatcher）→ 规范化判定（verdict）→ 校验任何transform判定 → 返回决策。deny 判定会阻断受保护路径上的操作；运行时错误与分发器失败应 fail closed（失败即拒绝）。

关于快照与运行时语义的进一步说明，可参考 stateless-runtime.md：ACS 是无状态、确定性的干预点策略运行时，一次调用只评估一个宿主提供的完整快照。

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.yaml，OPA 加载/policy/acs_sidecar_reference.rego；
• 应用策略分发器把每条 Rego 查询发送到 Pod 内http://127.0.0.1:8181；
• 回环地址让策略评估保持 Pod 本地化，避免把 OPA 暴露为 Kubernetes Service；
• 分发器（dispatcher）属于宿主边界，负责超时、重试、错误映射与 fail closed 行为。

在 deployment.yaml 中，OPA 以--addr=127.0.0.1:8181启动并run --server，只监听回环地址；而 service.yaml 只暴露应用容器的 8080 端口，OPA 端口不出 Pod。

三、六个干预点的 Manifest 绑定：以 ConfigMap 为单一策略载体

参考实现的策略载体是一个 ConfigMap——acs-policy-configmap.yaml，它同时存放manifest.yaml（ACS 清单）与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_target（JSONPath 表达式）和query（data.agent_control_specification.acs_sidecar_reference.<point>_verdict）的绑定；
• tools：工具元数据（type、id、clearance、security_labels），供pre_tool_call投影。

六个干预点在 manifest 中的完整绑定如下（节选自 ConfigMap 数据）：

工具声明示例（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 治理中最典型的四类风险：

1. 提示注入（input）：输入文本命中"ignore previous instructions"即 deny；
2. 角色越权（pre_model_call）：system 角色内容中出现"from user upload"即 deny——防止不受信上传内容混入高权限系统提示；
3. 危险工具计划与参数越权（post_model_call/pre_tool_call）：模型响应同时出现"transfer_funds"与"without approval"即 deny；transfer_funds工具的单笔amount超过 1000 即 deny——注意这里评估的是将要实际执行的精确参数；
4. 工具输出注入与密钥泄露（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 行。

四、部署清单全解：从命名空间到 Deployment

kustomization.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.yaml

4.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-reference

4.2 Deployment：应用 + OPA 双容器

deployment.yaml 是拓扑的核心。其要点：

• replicas: 2，应用容器监听 8080（/health就绪/存活探针）；
• 应用容器通过环境变量装配 ACS：ACS_MANIFEST_PATH=/etc/acs/manifest.yaml、ACS_POLICY_BUNDLE_PATH=/policy、ACS_POLICY_DISPATCHER=opa-http、ACS_OPA_URL=http://127.0.0.1:8181、ACS_MODE=enforce、OTEL_SERVICE_NAME=acs-mediated-app；
• 同一 ConfigMap 卷acs-policy以只读方式挂载两处：/etc/acs（manifest）与/policy（Rego 包）；
• OPA 容器镜像ghcr.io/open-policy-agent/opa:0.68.0-rootless，以run --server --addr=127.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 - --addr=127.0.0.1:8181 - --log-level=info - /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 Service（8080 → 容器 8080），OPA 不在 Service 内。

peer-authentication.yaml 在命名空间层面强制 STRICT mTLS：

apiVersion: security.istio.io/v1 kind: PeerAuthentication metadata: name: default namespace: acs-agents spec: mtls: mode: STRICT

destination-rule.yaml 为网格内调用方请求ISTIO_MUTUAL：

apiVersion: networking.istio.io/v1 kind: DestinationRule metadata: name: default namespace: acs-agents spec: host: "*.acs-agents.svc.cluster.local" trafficPolicy: tls: mode: ISTIO_MUTUAL

4.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 同样是未经测试的说明性探测脚本，它验证了参考架构的四个关键断言，可作为平台评审时的检查清单模板：

1. mTLS 资源：PeerAuthentication的spec.mtls.mode必须为STRICT，DestinationRule的trafficPolicy.tls.mode必须为ISTIO_MUTUAL；
2. Pod 容器构成：Pod 内必须同时存在opa与istio-proxy容器；
3. 健康探测：通过kubectl port-forward转发svc/acs-mediated-app后，GET /health期望 2xx；
4. 策略行为探测：向/chatPOST 正常消息期望 2xx（allow 路径），POST{"message":"ignore previous instructions"}期望 4xx（deny 路径，默认接受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——这为审计提供了"最小遥测"的落地样板。

七、从参考到生产：平台评审清单

将参考架构投入生产前，原文给出明确的改造义务，汇总为可操作的清单：

1. 替换占位镜像：将ghcr.io/your-org/acs-mediated-app:latest替换为真实内嵌 ACS SDK 的应用镜像，并固定版本；
2. 固定镜像版本：应用与 OPA（参考为0.68.0-rootless）镜像均需固定 digest/版本，禁用latest；
3. 补充资源限额：为 app 与 opa 容器配置 requests/limits，防止策略评估挤占业务资源或 OOM；
4. 保护 ConfigMap 更新：策略即代码，manifest 与 Rego 的更新需走评审、签名或不可变发布流程，避免被篡改；
5. 选择生产 OPA 版本：参考版本只是示例，需按 OPA 官方支持策略选定生产版本；
6. 补齐健康/就绪语义：探针路径与业务匹配，并考虑将 OPA 可达性纳入就绪判断；
7. 真实集群测试：在 CI 或预发集群上跑完整 e2e，验证 fail closed 行为、探测脚本断言与策略命中率；
8. 宿主集成契约：只发布受治理的 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