使用说明

领事mcp代理人

GKE+Consul服务网格+HCP保险库专用+GCP上的MCP AI代理。

用于运行接触真实云API的LLM代理的端到端参考堆栈，具有 零长期凭据, 每跳mTLS，以及 5分钟GCP代币.HCP Vault Dedicated既是Consul Connect网格的证书颁发机构，也是GCP OAuth2令牌的动态代理；Consul控制平面在GCE VM上运行，而数据平面（Envoy sidecar）在GKE中运行；AI代理及其MCP工具服务器是单独的Pod，只能通过网格相互通信。

你得到了什么

一种人工智能代理网络终端 （ttyd）其中经过身份验证的用户使用角色范围的工具对GCS、BigQuery和计算引擎驱动LLM。
用户提示和GCP API调用之间的三个信任边界：Vault用户通行证（您是谁）→ 领事意图（哪些服务可以说话）→ capabilities.yaml （LLM看到了哪些工具）。
图像、清单或环境变量中没有秘密 --每个凭据都由vault代理呈现到tmpfs中，并在TTL下轮换。
交钥匙部署：约25-35分钟 task all 连接到可工作的web终端，带有处理HCP Vault的相位门控Terraform→ 保险库PKI→ 领事虚拟机→ GKE → MCP吊舱的顺序正确。

给谁的

平台工程师和安全架构师评估如何在不分发静态API密钥的情况下为LLM代理提供真正的云功能；HashiCorp客户希望HCP Vault+Consul+GKE有一个有主见的参考；希望将工作工件分叉而不是幻灯片图的团队。

快速开始 --先决条件、配置、部署、登录
建筑 --组件堆栈、证书链、Vault中的内容
部署阶段 --为什么应用程序被拆分，以什么顺序拆分
运营 --每个组件的任务文件命令
目录结构
安全一瞥
故障排除
深潜 — docs/architecture.md （每个吊舱的保险库流量，秘密生命周期）· docs/mesh.md （Vault PKI作为Consul Connect CA，VM TLS）· docs/blog-securing-agentic-platforms.md （关于OWASP-LLM映射的文章）

快速开始

先决条件

工具	版本	安装
地形	>=1.9.0	terraform.io
封隔器	>=1.10.0	打包器.io
任务	>=3.0	`brew install go-task`
gcloud	最新	cloud.google.com/sdk
kubectl	>= 1.28	`gcloud components install kubectl`
docker	>=24.0	docs.docker.com
vault命令行界面	>=1.17	Vaultproject.io
jq	>=1.6	`brew install jq`

您还需要：

A. GCP项目 在启用计费的情况下， roles/owner （或自定义角色覆盖 compute.*, container.*, iam.*, artifactregistry.*)，并且启用了计算引擎、GKE、IAM、工件注册表和云NAT API。
一 HCP帐户 (portal.cloud.hashicorp.com)使用服务主体（贡献者角色）--注意的客户端ID和客户端密码 terraform.tfvars.
一 Anthropic或OpenAI API密钥.

1·克隆

git clone https://github.com/ChrisAdkin8/consul-mcp-agents.git
cd consul-mcp-agents

2·配置 `terraform.tfvars`

cp tf/scenarios/consul-mcp-gke/terraform.tfvars.example \
   tf/scenarios/consul-mcp-gke/terraform.tfvars

编辑三个必需的块：

# ---- GCP ----
gcp_project_id = "your-gcp-project-id"
gcp_region     = "us-central1"
gcp_zone       = "us-central1-a"
environment    = "dev"

# ---- HCP ----  (service principal: HCP portal → Access control → Service principals)
hcp_client_id     = "your-hcp-client-id"
hcp_client_secret = "your-hcp-client-secret"
hcp_hvn_cidr      = "172.25.16.0/20"   # must not overlap GCP subnets
hcp_vault_tier    = "plus_small"

# ---- LLM ----
llm_provider     = "anthropic"
llm_model        = "claude-sonnet-4-6"
anthropic_api_key = "sk-ant-..."

3·通过GCP进行身份验证

所有四个命令都是必需的； task preflight 将验证它们。

gcloud auth login                                              # gcloud CLI + kubectl + Taskfile
gcloud auth application-default login                          # Terraform google provider + Packer
gcloud config set project <your-project-id>                    # default --project
gcloud auth configure-docker us-central1-docker.pkg.dev        # docker push to Artifact Registry

4·部署

task tf:backend:create   # creates the GCS state bucket
task preflight           # verifies tools, credentials, tfvars
task all                 # full deployment, ~25–35 min

阶段时间：阶段1（HCP Vault+PKI+Consul VM）~10分钟·阶段2（GKE+Consul Helm）~15分钟·阶段3（MCP代理）~2分钟。

5·登录

task mcp:url
# Open http://<IP>/ — log in with:
#   alice / alice-pass    (operator, all tools)
#   bob   / bob-pass      (analyst, read + query)
#   carol / carol-pass    (viewer, read-only)

建筑

组件堆栈

层	组件	用途
身份和秘密	HCP专用保险库	PKI CA、GCP动态信任、配置存储、人+pod身份验证
服务网格CA	Vault PKI（根+中间）	为Consul Connect颁发mTLS叶子证书
控制平面	GCE VM上的Consul	GKE数据平面的外部Consul控制平面
计算	GKE（区域集群）	运行MCP代理Pod+Envoy Sidecar
凭据	Vault GCP密钥引擎	通过服务帐户模拟获得5分钟OAuth2令牌
Agent AI	vault mcp代理（Python）	Anthropic/OpenAI SDK适配器+mcp工具服务器（GCS、BigQuery、GCE）
用户访问	ttyd网络终端	基于浏览器的访问 `vault-mcp-agents` pod内的CLI

证书链

HCP Vault PKI
  └── Root CA  (connect-root)          10-year validity, never exported
        └── Intermediate CA  (connect-intermediate)  5-year validity
              ├── Consul Connect leaf certs          72h, auto-rotated
              └── Consul server TLS certs            72h, auto-rotated

凭证流（5分钟GCP代币）

User → Vault userpass login → Session token
  → Agent selects role + agent, opens MCP connection over the Consul mesh
  → (mTLS hop through Envoy sidecars; ServiceIntention authorises)
  → MCP server pod calls tool handler
  → Reads /vault/secrets/gcp-token (refreshed by its vault-agent sidecar)
  → Token came from: Vault GCP secrets engine → GCP generateAccessToken API
  → OAuth2 token (TTL 5 min, enforced server-side by Vault lease)
  → GCS / BigQuery / GCE API call

代理进程本身从不获取GCP凭据。每个MCP服务器pod都有自己的Vault角色和自己的GCP模拟链——代理的折衷爆炸半径是“根据意图允许发布MCP RPC”，而不是“铸造GCP令牌”

什么住在保险库里

秘密路径	内容	消费者
`connect-root/`	PKI根CA	领事TLS信任锚
`connect-intermediate/`	PKI中间CA	向Consul发放叶子证书
`auth/gcp`	GCP IAM身份验证方法	Consul服务器VM保险库代理
`auth/kubernetes`	K8s身份验证方法	GKE pod vault代理
`auth/userpass`	人类用户帐户	MCP CLI用户
`gcp/impersonated-account/data-agent-gcp`	GCP OAuth2代币（5分钟）	`mcp-data-server`
`gcp/impersonated-account/compute-agent-gcp`	GCP OAuth2代币（5分钟）	`mcp-compute-server`
`secret/mcp-agents/config`	`settings.yaml` 内容	通过vault代理的MCP Pod
`secret/mcp-agents/policies`	`capabilities.yaml` 内容	通过vault代理的MCP Pod
`secret/mcp-agents/llm-keys`	Anthropic/OpenAI API键	`mcp-agent` pod通过vault代理
`secret/consul/acl-token`	Consul引导ACL令牌	书面引导

想要更多深度？ docs/architecture.md 遍历每个pod的vault代理流（init容器、sidecar、序列图、秘密生命周期）。 docs/mesh.md 涵盖了作为Consul Connect CA的Vault PKI、VM上的GCP-IAM身份验证路径以及没有SIGHUP的TLS续订。

部署阶段

部署分为多个阶段，因为在早期资源存在之前，Terraform无法观察运行时值（GKE端点、Vault令牌、Consul ACL引导）。

Phase 1a   Network            VPC, subnets, Cloud NAT
Phase 1b   HCP Vault          HVN + Vault cluster + VPC peering
Phase 1c   Vault PKI          Root CA + Intermediate CA + GCP auth roles
Phase 1d   Vault Config       KV secrets, GCP engine, userpass, K8s auth skeleton
Phase 1e   Consul VMs         Boot with vault-agent → GCP IAM auth → certs from Vault PKI

Phase 2    GKE + Consul Helm  Cluster + Consul dataplane Helm (TLS via Vault PKI CA cert)

Post-GKE   K8s auth wiring    `vault:configure-k8s-auth` fills in GKE endpoint + CA

Phase 3    Docker image       MCP agent image build + push to Artifact Registry
Phase 4    K8s workloads      MCP agent + server Deployments, Services, Intentions

为什么分裂： HCP保险库 必须存在才能应用Vault PKI/config； 保险库PKI 必须在Consul VM启动之前存在（vault代理获取证书）； 领事虚拟机 GKE Helm必须先运行，然后才能连接到外部服务器； GKE端点 只有在GKE应用后才知道（Vault K8s auth需要它）； 保险库K8s身份验证 必须先进行配置，然后MCP Pod才能进行身份验证。

运营

# Vault
task vault:status                # cluster health
task vault:login:operator        # log in as alice
task vault:configure-k8s-auth    # re-wire K8s auth after cluster changes

# Consul
task consul:status               # member list (via IAP SSH)
task consul:refresh-tls          # re-issue TLS cert + sync consul-ca-cert K8s secret
task consul:bootstrap-acl        # bootstrap ACLs (idempotent)

# GKE
task gke:ensure-ready            # kubeconfig + phase gate + private endpoint tfvar
task gke:nodes                   # list nodes

# MCP agents
task mcp:status                  # pod and service status
task mcp:url                     # web terminal URL
task mcp:logs                    # tail pod logs
task mcp:exec                    # shell into a pod
task mcp:restart                 # rolling restart

# Docker
task docker:build                # build with git SHA tag
task docker:push                 # push to Artifact Registry

# HCP
task hcp:list-orphans            # surface leaked random_pet HVNs from prior runs

# Diagrams
task diagrams:generate           # regenerate architecture PNGs

完整列表： task --list.

目录结构

consul-mcp-agents/
├── Taskfile.yml                # Orchestration (task --list)
├── README.md
├── CLAUDE.md                   # Working notes / operational rules for contributors
│
├── docker/                     # Multi-stage Python + vault-agent + ttyd image
├── packer/                     # Consul server VM image (AlmaLinux + vault-agent baked in)
├── src/vault_mcp_agents/       # Agent CLI + MCP servers (data, compute)
├── config/                     # Bundled settings.yaml + capabilities.yaml defaults
│
├── docs/
│   ├── architecture.md         # Per-pod Vault flow, secret lifetimes
│   ├── mesh.md                 # Vault PKI as Consul Connect CA, VM TLS
│   ├── blog-securing-agentic-platforms.md
│   └── diagrams/               # Architecture PNGs + D2 sources
│
└── tf/
    ├── modules/
    │   ├── hcp-vault/          # HVN + Vault Dedicated + VPC peering
    │   ├── vault-pki-consul/   # Root + Intermediate CA, GCP auth, policies
    │   ├── vault-config/       # KV, GCP engine, userpass, K8s auth
    │   ├── network/            # VPC + subnets + Cloud NAT + firewalls
    │   ├── consul/             # Consul server VMs (GCE)
    │   ├── gke-consul-dataplane/  # GKE cluster + Consul Helm
    │   └── mcp-agents-k8s/     # K8s ns, SA, vault-agent ConfigMaps, Deployments
    └── scenarios/
        └── consul-mcp-gke/     # Root module wiring everything together

安全一瞥

什么	如何
领事VM→ 保险库身份验证	GCP IAM身份验证（VM SA身份JWT）
gke pod→vault auth	kuberneses auth（JWT上的pod）
保险库→ GCP APIs	服务帐户密钥处于Vault状态（可旋转）
LLM API密钥	保险库KV→ 保险库代理人→ tmpfs文件（从未出现在K8s清单中）
GCP凭据	通过模拟进行5分钟OAuth2（服务器端租约+客户端TTL）
Consul mTLS	Vault PKI叶子证书（72小时，由Vault代理自动轮换）
代理商↔ 服务器	Consul Connect mTLS+服务意图（无明文）
用户密码	保险库用户通行证（在Terraform中管理，带外轮换）

每次工具调用都有四层深度防御（Vault策略→ 领事意向→ capabilities.yaml → GCP IAM）。看 docs/architecture.md 对于每一层所执行的内容。

故障排除

Consul服务器虚拟机未加入群集

gcloud compute ssh <consul-vm-name> --project <project> --zone <zone> --tunnel-through-iap

sudo systemctl status vault-agent
sudo journalctl -u vault-agent -f       # auth + render activity
ls -la /etc/consul.d/                   # vault-agent should have written tls/, connect-ca.hcl
sudo systemctl status consul
sudo journalctl -u consul -f

MCP吊舱卡在里面 `Init:0/2` --保险库代理人 `permission denied`

症状： 豆荚在 mcp-agents 展示 Init:0/2; vault-agent-init 日志显示重复 403 permission denied 上 auth/kubernetes/login.

原因： 这 vault-reviewer ClusterRoleBinding丢失。Vault需要它来调用K8s TokenReview API。保管库审阅者SA+CRB+令牌密钥是 vault-config.tf --不在里面 module.vault_config --因此，仅模块的目标应用程序会跳过它们。

kubectl get clusterrolebinding vault-reviewer    # expect: not NotFound

task vault:configure-k8s-auth                    # re-applies the vault-reviewer resources
kubectl rollout restart deployment/mcp-agent deployment/mcp-data-server deployment/mcp-compute-server -n mcp-agents

pod到Vault身份验证失败的其他原因：

kubectl logs -n mcp-agents <pod-name> -c vault-agent-init
vault read auth/kubernetes/config
vault read auth/kubernetes/role/mcp-server

Terraform警告未声明的变量 `gke_cluster_endpoint` / `gke_cluster_ca_certificate`

场景通过以下方式自动发现两者 data.google_container_cluster.main 当 gke_cluster_ready = true.从以下位置拆下手动管路 terraform.tfvars --他们不在 terraform.tfvars.example 不应该用手设置。

ttyd网络终端未加载

kubectl get pods -n mcp-agents -o wide
kubectl logs -n mcp-agents deployment/mcp-agents -c ttyd
kubectl get svc mcp-agents-lb -n mcp-agents

对于更深层次的操作故障模式（TLS过期的Pod崩溃循环、Vault K8s认证JWT在污染后为空、HCP HVN配额耗尽、， errored.tfstate 恢复），请参阅 关键操作规则 部分在 CLAUDE.md.

使用说明

领事mcp代理人

你得到了什么

给谁的

目录

快速开始

先决条件

1·克隆

2·配置 terraform.tfvars

3·通过GCP进行身份验证

4·部署

5·登录

建筑

组件堆栈

证书链

凭证流（5分钟GCP代币）

什么住在保险库里

部署阶段

运营

目录结构

安全一瞥

故障排除

Consul服务器虚拟机未加入群集

MCP吊舱卡在里面 Init:0/2 --保险库代理人 permission denied

Terraform警告未声明的变量 gke_cluster_endpoint / gke_cluster_ca_certificate

ttyd网络终端未加载

相关 MCP

Kubernetes MCP服务器

Kubernetes管理服务器

Kubernetes 多集群管理服务

MCP连接网关

CNCF项目查询工具

OVH API访问服务

2·配置 `terraform.tfvars`

MCP吊舱卡在里面 `Init:0/2` --保险库代理人 `permission denied`

Terraform警告未声明的变量 `gke_cluster_endpoint` / `gke_cluster_ca_certificate`