Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 VPC Service Controls 部署代理和 Agent Gateway

1. 简介

此 Codelab 将引导您配置 Google Cloud 环境，以设置智能体和 Agent Gateway，并使用 VPC Service Controls 边界。您将建立 VPC Service Controls 边界，配置网络和 DNS，部署具有 Identity-Aware Proxy (IAP) 请求授权的 Agent Gateway，并安全地测试代理。

构建内容

在此 Codelab 中，您将为 Gemini Enterprise Agent Platform 和 Agent Gateway 构建安全的 Google Cloud 架构，该架构可执行以下操作：

使用 VPC Service Controls 帮助保护项目资源免遭未经授权的数据渗漏。
配置专用 Google 访问通道、Private Service Connect (PSC) 和 Cloud DNS 私有区域，以实现私有 API 路由。
预配具有集中式流量代理、出站流量规则和协议配置的 Agent Gateway。
强制执行 Identity-Aware Proxy (IAP) 请求授权政策。
通过专用连接部署并安全地测试 Agent Engine 代理。

学习内容

如何为 Agent Platform 和安全性启用所需的 Google Cloud API。
如何配置 VPC Service Controls 边界和入站访问权限规则。
如何设置专用网络连接和专用 DNS 记录。
如何创建 Agent Gateway 和智能体连接模板。
如何配置 IAP 请求授权扩展程序和政策。
如何安全地部署和测试 Agent Engine 智能体。

所需条件

Google Cloud CLI 已安装并更新为最新版本。
工作站上安装了 Python 3。
工作站上已安装 Git。
有效的 Google Cloud 组织和结算账号权限。

2. 前提条件

本部分概述了运行设置脚本之前所需的基本命令行工具要求和环境配置。

验证 Google Cloud CLI 是否已安装并更新为最新版本，然后使用您的 Google 账号进行身份验证。更新 Google Cloud CLI 组件，确保您获得对网络服务和 VPC Service Controls 的最新功能支持。

gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL

验证是否已安装 Python 3，以便配置和部署自定义代理框架。如需查看相关说明，请参阅安装 Python 模块：

python3 --version

确保已安装 Git，以便克隆包含设置代码和配置模板的示例代码库。如需查看相关说明，请参阅 Git 安装。

3. 配置 Google Cloud 项目

在组织内创建隔离项目可确保此 Codelab 中使用的所有资源、网络和权限保持封装状态，以便于管理。详细了解如何创建和管理项目。

在您的组织下初始化一个新的 Google Cloud 云项目，以托管此设置的资源。您也可以使用自己的项目：

export PROJ_ID="YOUR_PROJECT_ID"
gcloud projects create ${PROJ_ID} --organization=YOUR_ORG_ID

gcloud config set project $PROJ_ID

gcloud auth application-default set-quota-project $PROJ_ID

通过登录获取应用默认凭据：

gcloud auth application-default login

验证配置：

gcloud config list

启用结算功能

将有效的结算账号关联到新创建的项目，以启用服务使用。

启用结算功能是使用 API 配额和预配 Google Cloud 基础架构（例如代理网关、虚拟私有云和计算节点）的前提条件。如需详细了解结算配置，请参阅 Google Cloud 结算文档。

gcloud billing accounts list
# Copy the billing account to assign to your GCP project
gcloud billing projects link $PROJ_ID --billing-account=BILLING_ACCOUNT_ID

4. 启用服务

为代理、Agent Gateway、网络、安全和可观测性功能启用所有必需的 Google Cloud API。

API 激活会公开后端云服务，以提供安全代理连接所需的资源管理、可观测性和网络功能。如需了解详情，请参阅 Service Usage API 文档。

gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com \
  securitycenter.googleapis.com

gcloud services enable \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com \
  accesscontextmanager.googleapis.com \
  discoveryengine.googleapis.com \
  agentidentity.googleapis.com \
  agentidentitycredentials.googleapis.com

5. 导出环境变量

为区域、项目 ID、项目编号、组织 ID 和用户身份定义可重复使用的环境变量。设置 shell 变量可标准化各个步骤中的资源配置命令，从而最大限度地减少脚本执行期间出现的手动替换错误。

export REGION="us-central1"
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)

6. 创建 VPC Service Controls 边界

创建 VPC Service Controls 边界以隔离项目资源，并帮助防止数据渗漏。如需了解详情，请参阅 VPC Service Controls 概览。

获取访问权限政策

检索与您的组织相关联的 Access Context Manager 政策 ID。Access Context Manager 政策定义了 VPC Service Controls 边界所附加和强制执行的组织边界。

gcloud access-context-manager policies list --organization=$ORG_ID

导出访问权限政策

在 gcloud CLI 配置中设置访问权限政策，并收集受支持的受限服务列表。收集所有受支持的服务可让您构建受限的边界规则集，以防止通过 Google Cloud API 端点进行未经授权的访问。

export ACCESS_POLICY=ACCESS_POLICY_ID

gcloud config set access_context_manager/policy $ACCESS_POLICY
SUPPORTED_SERVICES=$(gcloud access-context-manager supported-services list --format="value(name)" | paste -sd, -)

创建边界

定义服务边界名称，并在项目内支持的 Google Cloud 服务中强制执行限制。边界充当项目资源周围的边界，除非入站流量/出站流量规则明确允许，否则会限制直接传入和传出流量。

export PERIMETER_NAME="perimeter_${PROJ_NO}"

gcloud access-context-manager perimeters create accessPolicies/${ACCESS_POLICY}/servicePerimeters/${PERIMETER_NAME} \
--title="${PERIMETER_NAME}" \
--perimeter-type=regular \
--resources=projects/${PROJ_NO} \
--restricted-services=${SUPPORTED_SERVICES}

创建入站流量政策

入站政策定义了明确的条件（例如特定用户身份或访问权限级别），在这些条件下，流量从边界外发起，并允许到达边界内的受限资源。

创建一个 YAML 文件，以允许您的用户身份跨所有服务进行显式访问：

cat > ingress-policy.yaml << EOF
- ingressFrom:
    identities:
      - user:${USER_IDENTITY}
    sources:
      - accessLevel: '*'
  ingressTo:
    operations:
      - serviceName: '*'
    resources:
      - '*'
EOF

gcloud access-context-manager perimeters update $PERIMETER_NAME --set-ingress-policies="ingress-policy.yaml"

此 Codelab 会配置您的环境，以默认避免 VPC Service Controls 拒绝访问。不过，为了帮助您在测试期间进行问题排查，VPC Service Controls 提供了详细的拒绝日志和政策智能工具。

排查 VPC Service Controls 拒绝问题

在整个测试过程中，请参考以下问题排查提示：

启用违规信息中心，以跟踪您环境中的最新违规情况。
监控 Cloud Audit Logs 中与 VPC Service Controls 访问遭拒 (403) 相关的日志。
在违规分析器中使用违规唯一 ID 或令牌诊断违规情况。
观看排查 VPC Service Controls 问题视频，了解详细的操作演示。

7. 设置网络

配置 VPC 网络设置，以支持与 Google API 和服务的私密通信。正确的网络配置可确保代理、网关和 Google Cloud API 之间的网络流量保留在专用内部网络中。如需详细了解网络模式，请参阅 Google Cloud VPC 文档。

启用专用 Google 访问通道

在默认子网上启用专用 Google 访问通道，以便虚拟机实例和内部工作负载可以使用内部 IP 地址（而非公共 IP 地址）访问 Google API。

export NETWORK_NAME="default"
export SUBNET_NAME="default"

gcloud compute networks subnets update $SUBNET_NAME --region=$REGION --enable-private-ip-google-access

创建 PSC 网络连接

为 Agent Gateway 连接创建 Private Service Connect (PSC) 网络连接。网络连接提供 Private Service Connect (PSC) 接口，有助于在 Agent Gateway 服务与您的内部子网之间实现安全的跨 VPC 通信。

gcloud compute network-attachments create psc-agw-${REGION} \
  --region=${REGION} \
  --subnets=${SUBNET_NAME} \
  --connection-preference=ACCEPT_AUTOMATIC

验证

检索并检查新创建的网络连接的自链接资源 URI。验证资源 URI 可确保网络连接已成功实例化，并且可以在连接模板中引用。

export PSC_NA_URI=$(gcloud compute network-attachments describe psc-agw-${REGION} \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

创建 Cloud DNS 专用区

配置 Cloud DNS 专用区域，以通过专用 IP 范围路由 googleapis.com 流量。专用 DNS 区域会替换 googleapis.com 的公共网域查找，从而将所有出站流量定向到 VPC 网络内的专用内部虚拟 IP (VIP)。如需了解详情，请参阅 Cloud DNS 专用可用区。

export ZONE_NAME="gapis"

gcloud dns managed-zones create ${ZONE_NAME} \
--visibility=private \
--networks=https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/global/networks/${NETWORK_NAME} \
  --description="Privately reach Google APIs" \
  --dns-name=googleapis.com

gcloud dns record-sets transaction start --zone=${ZONE_NAME}

选择以下任一专用路由网域选项（在执行交易之前，仅运行选项 1 或选项 2 下的命令）- 如需了解详情，请参阅专用 Google 访问通道配置选项：

方法 1：专用 VIP [推荐]

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME private.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=private.googleapis.com. \
    --type=A 199.36.153.8 199.36.153.9 199.36.153.10 199.36.153.11 \
    --zone=${ZONE_NAME} \
    --ttl=300

方法 2：受限 VIP

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME restricted.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=restricted.googleapis.com. \
    --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
    --zone=${ZONE_NAME} \
    --ttl=300

提交 DNS 事务：

gcloud dns record-sets transaction execute --zone=${ZONE_NAME}

8. 创建 Agent Gateway

预配 Agent Gateway 并定义其连接模板和路由规则。Agent Gateway 充当集中式代理，用于管理智能体流量、出站流量政策、协议处理和安全服务发现。如需了解架构参考信息，请参阅代理网关概览。

架构图：显示了代理如何通过 Agent Gateway、IAP 请求授权和 VPC Service Controls 边界内的 PSC 网络连接路由请求。

export AGW_NAME="gateway-${USER_IDENTITY}"
export AGW_CONNECTIVITY_TEMPLATE="agw-connectivity-template-${USER_IDENTITY}"

创建代理连接模板

连接模板用于指定网关处理出站请求所需的网络配置、出站路由政策、DNS 对等互连设置和网络连接 URI。

cat > ${AGW_CONNECTIVITY_TEMPLATE}.yaml << EOF
name: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
  networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domain: googleapis.com.
    targetNetwork: projects/${PROJ_ID}/global/networks/${NETWORK_NAME}
  vpcEgress: ALL_TRAFFIC
EOF

gcloud network-services agent-connectivity-templates import ${AGW_CONNECTIVITY_TEMPLATE} \
    --source="${AGW_CONNECTIVITY_TEMPLATE}.yaml" \
    --location=${REGION}

创建 Agent Gateway

cat > ${AGW_NAME}-config.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
registries:
  - //agentregistry.googleapis.com/projects/${PROJ_NO}/locations/global
EOF

gcloud network-services agent-gateways import ${AGW_NAME} \
    --source="${AGW_NAME}-config.yaml" \
    --location=${REGION}

验证创建

确认 Agent Gateway 资源已成功部署和配置。描述已部署的代理网关可确认其运行状态为有效，并验证关联的连接模板和注册表是否已正确附加。

gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

9. 通过 IAP 创建授权

配置 Identity-Aware Proxy (IAP) 请求授权政策和 Service Extensions，以在授予对 Agent Gateway 的访问权限之前验证请求凭据。如需了解详情，请参阅 IAP 文档。

流程图：显示了代理网关如何使用网络安全授权政策和授权服务扩展程序将请求授权委托给 Identity-Aware Proxy (IAP)。

export AUTHZ_EXT="iap-authz-extension-${USER_IDENTITY}"
export AUTHZ_POLICY="iap-authz-policy-${USER_IDENTITY}"

创建 AuthZ 扩展程序

cat > ${AUTHZ_EXT}.yaml << EOF
name: ${AUTHZ_EXT}
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
EOF

gcloud service-extensions authz-extensions import ${AUTHZ_EXT} \
    --source=${AUTHZ_EXT}.yaml \
    --location=${REGION}

创建授权政策并将其绑定到 Agent Gateway

cat > ${AUTHZ_POLICY}.yaml << EOF
name: ${AUTHZ_POLICY}
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AUTHZ_EXT}"
EOF

gcloud network-security authz-policies import ${AUTHZ_POLICY} \
    --source=${AUTHZ_POLICY}.yaml \
    --location=${REGION}

此 Codelab 可确保您默认不会遇到任何 IAP 访问遭拒的情况。不过，为了帮助您进行测试，Agent Gateway 提供了详细的访问拒绝可观测性。

排查和监控 IAP 授权拒绝问题

在 _Default 日志记录存储桶中启用 Log Analytics：

gcloud logging buckets update _Default --location=global --enable-analytics --async

打开 Agent Gateway 可观测性信息中心：
在 Google Cloud 控制台中，前往 Agent Gateway 页面。
点击网关的名称（例如 gateway-xyz）。
点击可观测性标签页。
查看“授权失败”和“403 拒绝”信息中心。

10. 创建 Agent Engine 代理

创建临时存储桶

在目标区域中创建一个 Cloud Storage 存储桶，以便在运行时初始化期间存储临时暂存工件、依赖项和部署配置。

#Staging bucket name needs to be globally unique
export STAGING_BUCKET="agent-temp-bucket-${PROJ_NO}-${USER_IDENTITY}"
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

激活 Python 虚拟环境

python3 -m venv .venv
source .venv/bin/activate

下载代理代码

git clone https://github.com/gpratikab/gcp-vpcsc-agent.git
cd gcp-vpcsc-agent

安装依赖项

python3 -m pip install --upgrade -r requirements.txt

向 Agent Platform 服务代理授予 IAM 角色

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/agentgateway.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/ml.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/networkservices.viewer"

部署智能体

python3 deploy_gcp_agent.py create

将上一个命令的输出中打印的代理身份导出为环境变量：

#Paste identity of your Agent, it will be printed as the output of the previous command
export AGENT_IDENTITY="principal://PRINCIPAL_ID"
echo $AGENT_IDENTITY

11. 允许通过网关实现代理出站流量

允许新创建的代理向 googleapis.com 发送出站流量。

注意：您可以使用 Agent Gateway 可观测性来选择性地将端点添加到许可名单。为简单起见，此 Codelab 允许访问所有 API。

配置明确的 IAM 出站流量政策规则可授予代理通过 Agent Gateway 和 IAP 代理路由 API 调用的权限，以访问外部 Google Cloud 服务。

创建 IAM 政策

cat > agent-access-rules.json << EOF
{
  "conditions": {
    "iap.googleapis.com": {
      "description": "Allow access to agent",
      "expression": "(destination.agent_registry.location == 'global') || (destination.unregistered.host.endsWith('googleapis.com'))",
      "title": "agenttogapis"
    }
  },
  "description": "agenttogapis",
  "effect": "ALLOW",
  "excludedPrincipals": [],
  "operation": {
    "excludedPermissions": [],
    "permissions": [
      "iap.googleapis.com/resources.egressViaIAP"
    ]
  },
  "principals": [
    "${AGENT_IDENTITY}"
  ]
}
EOF

更新访问权限政策

检查您是否已有访问权限政策：

gcloud iam access-policies list --project=${PROJ_ID} --location=global

设置访问权限政策名称：

export IAM_ACCESS_POLICY="agent-access-policy"

要创建新政策，请执行以下操作：

gcloud iam access-policies create ${IAM_ACCESS_POLICY} \
  --details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

或者，您也可以更新现有政策：

gcloud iam access-policies update ${IAM_ACCESS_POLICY} \
  --add-details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

12. 测试代理

在 Google Cloud 控制台中验证代理操作，可确认端到端通信、IAM 政策和 VPC Service Controls 边界是否正常运行。现在，您可以测试代理了：

在 Google Cloud 控制台中，前往代理部署页面。
选择已部署的智能体 (gcp_agent_...)。
打开园地标签页。
在提示字段中，输入：List storage buckets in the current project.
验证代理是否通过专用 Agent Gateway 成功返回了存储桶列表。
验证由于访问遭拒，代理无法从其他项目检索存储桶。您可以在 Cloud Audit Logs 或 VPC Service Controls 违规信息中心内检查拒绝情况。

13. 清理

为避免系统因本 Codelab 中使用的资源而向您的 Google Cloud 账号收取费用，请删除您创建的项目：

gcloud projects delete ${PROJ_ID}

14. 恭喜

恭喜！您已成功在 Google Cloud 上安全 VPC Service Controls 边界内配置了代理和 Agent Gateway。

后续操作

探索 VPC Service Controls 中的精细入站和出站规则。
使用 Agent Gateway 配置访问权限政策和语义政策。
集成 Model Armor 以实现高级安全过滤。