Consul MCP Agents

领事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映射的文章）

______________________________________________________________________

快速开始

先决条件

您还需要：

• 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                     # 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:/// — log in with:
#   alice / alice-pass    (operator, all tools)
#   bob   / bob-pass      (analyst, read + query)
#   carol / carol-pass    (viewer, read-only)

______________________________________________________________________

建筑

Overall Architecture

组件堆栈

证书链

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令牌”

什么住在保险库里

想要更多深度？ 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

______________________________________________________________________

安全一瞥

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

______________________________________________________________________

故障排除

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

gcloud compute ssh  --project 
 --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 
 -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.