Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как развернуть агента и шлюз агента с помощью Управления зонами безопасности VPC

1. Введение

В этой практической работе рассказывается о том, как настроить среду Google Cloud, чтобы создать агента и шлюз агента с периметрами управления зонами безопасности VPC. Вы создаете периметр Управления зонами безопасности VPC, настраиваете сеть и DNS, развертываете шлюз агента с авторизацией запросов через прокси-сервер с идентификацией (IAP) и тестируете агента безопасным образом.

Что вы создадите

В этой практической работе вы создадите безопасную архитектуру Google Cloud для Gemini Enterprise Agent Platform и Agent Gateway, которая будет выполнять следующие действия:

Использует Управление зонами безопасности VPC, чтобы защитить ресурсы проекта от несанкционированной утечки данных.
Настраивает доступ к сервисам Google с частным IP-адресом, Private Service Connect (PSC) и частные зоны Cloud DNS для частной маршрутизации API.
Предоставляет шлюз агента с централизованным проксированием трафика, правилами исходящего трафика и конфигурацией протокола.
Применяет правила авторизации запросов прокси-сервера с идентификацией (IAP).
Развертывает и безопасно тестирует агента Agent Engine через частное подключение.

Что вы узнаете

Как включить необходимые API Google Cloud для платформы агентов и безопасности
Как настроить периметр Управления зонами безопасности VPC и правила входящего доступа.
Как настроить подключение к частной сети и частные записи DNS.
Как создать шлюз агента и шаблоны подключения агентов.
Как настроить расширения и правила для авторизации запросов на покупку в приложении.
Как безопасно развернуть и протестировать агента Agent Engine.

Что вам понадобится

Установите и обновите до последней версии интерфейс командной строки Google Cloud.
На вашем рабочем месте установлен Python 3.
Git, установленный на рабочей станции.
Активная организация Google Cloud и разрешения для платежного аккаунта.

2. Требования

В этом разделе описаны основные требования к инструментам командной строки и конфигурации среды, которые необходимо выполнить перед запуском скриптов установки.

Убедитесь, что Google Cloud CLI установлен и обновлен до последней версии, а затем выполните аутентификацию с помощью аккаунта Google. Обновите компоненты Google Cloud CLI, чтобы использовать новейшие функции сервисов сети и управления зонами безопасности VPC.

gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL

Чтобы настроить и развернуть фреймворк пользовательского агента, убедитесь, что установлен Python 3. Инструкции приведены в разделе Установка модулей Python:

python3 --version

Убедитесь, что Git установлен, чтобы клонировать образец репозитория, содержащий код настройки и шаблоны конфигурации. Инструкции приведены в разделе Установка Git.

3. Как настроить проект Google Cloud

Создание изолированного проекта в организации гарантирует, что все ресурсы, сети и разрешения, используемые в этой практической работе, останутся в пределах проекта и будут управляемыми. Подробнее о том, как создавать проекты и управлять ими…

Инициализируйте новый проект 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

Получите Application Default Credentials, выполнив вход:

gcloud auth application-default login

Проверьте конфигурацию:

gcloud config list

Включить оплату

Чтобы использовать сервисы, свяжите активный платежный аккаунт с новым проектом.

Включение платежных функций – обязательное условие для использования квоты API и инициализации облачной инфраструктуры Google Cloud, такой как шлюзы агентов, виртуальные частные облака и вычислительные узлы. Подробную информацию о конфигурациях оплаты можно найти в документации по Google Cloud Billing.

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. Включить сервисы

Включите все необходимые API Google Cloud для агента, шлюза агента, сети, безопасности и функций наблюдаемости.

Активация 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. Экспорт переменных среды

Определите многократно используемые переменные среды для региона, идентификатора проекта, номера проекта, идентификатора организации и идентификатора пользователя. Установка переменных оболочки стандартизирует команды конфигурации ресурсов на разных этапах, что позволяет свести к минимуму ошибки при ручной замене во время выполнения скрипта.

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

Создайте периметр управления зонами безопасности VPC, чтобы изолировать ресурсы проекта и предотвратить утечку данных. Подробнее об управлении зонами безопасности VPC…

Как получить правила доступа

Получите идентификатор правила Access Context Manager, связанного с вашей организацией. Правила Access Context Manager определяют границы организации, к которым прикрепляются и применяются периметры Управления зонами безопасности VPC.

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

Как экспортировать правила доступа

Задайте правила доступа в конфигурации gcloud CLI и соберите список поддерживаемых сервисов с ограниченным доступом. Сбор всех поддерживаемых сервисов позволяет создать набор правил для ограниченного периметра, который предотвращает несанкционированный доступ к конечным точкам API Google Cloud.

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"

В этой практической работе вы настроите среду так, чтобы по умолчанию не возникало проблем с доступом к Управлению зонами безопасности VPC. Однако, чтобы помочь вам устранять неполадки во время тестирования, сервис "Управление зонами безопасности VPC" предоставляет подробные журналы отказов и инструменты для анализа правил.

Как устранять проблемы с отказами Управления зонами безопасности VPC

Во время тестирования следуйте приведенным ниже советам по устранению неполадок.

Включите панель нарушений, чтобы отслеживать последние нарушения в вашей среде.
Отслеживайте в журналах аудита Cloud Audit Logs записи об отказе в доступе (403) к зонам безопасности VPC.
Выявляйте нарушения с помощью уникального идентификатора или токена нарушения в Анализаторе нарушений.
Подробные инструкции можно найти в видео об устранении неполадок с управлением зонами безопасности VPC.

7. Как настроить сеть

Настройте параметры сети VPC, чтобы обеспечить частную связь с Google API и сервисами. Правильная конфигурация сети гарантирует, что сетевой трафик между агентами, шлюзами и API Google Cloud остается в частных внутренних сетях. Подробные сведения о шаблонах сетей приведены в документации по VPC Google Cloud.

Как включить доступ к сервисам Google с частным IP-адресом

Включите доступ к сервисам Google с частным IP-адресом в подсети по умолчанию, чтобы экземпляры ВМ и внутренние рабочие нагрузки могли обращаться к API Google с помощью внутренних IP-адресов вместо общедоступных.

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

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

Как создать сетевое подключение PSC

Создайте сетевое подключение 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, чтобы перенаправлять трафик googleapis.com через частные диапазоны IP-адресов. Частные зоны DNS переопределяют общедоступные запросы домена для googleapis.com, направляя весь исходящий трафик на частные внутренние виртуальные IP-адреса (VIP) в вашей сети VPC. Подробнее о частных зонах 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 – это централизованный прокси-сервер для управления трафиком агентов, правилами исходящего трафика, обработкой протоколов и безопасным обнаружением сервисов. Сведения об архитектуре можно найти в статье Обзор шлюза агента.

Схема архитектуры, на которой показано, как агент направляет запросы через шлюз агента, авторизацию запросов IAP и сетевое подключение PSC в периметре Управления зонами безопасности VPC.

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}

Как создать шлюз агента

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}

Как проверить креатив

Убедитесь, что ресурс шлюза агента успешно развернут и настроен. Описание развернутого шлюза агента подтверждает, что его рабочее состояние активно, и проверяет, правильно ли прикреплены связанные шаблоны подключения и реестры.

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

9. Как создать авторизацию с помощью встроенных покупок

Настройте правила авторизации запросов Identity-Aware Proxy (IAP) и расширения сервисов, чтобы проверять учетные данные запросов перед предоставлением доступа к шлюзу агента. Подробнее о защите доступа к облачным сервисам…

Блок-схема, показывающая, как Agent Gateway делегирует авторизацию запроса 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}

Как создать правило авторизации и привязать его к шлюзу агента

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}

В этой практической работе вы настроите приложение так, чтобы по умолчанию доступ к покупкам в приложении не был запрещен. Однако для удобства тестирования Agent Gateway предоставляет подробные сведения о случаях отказа в доступе.

Как устранять неполадки и отслеживать отказы в авторизации IAP

Включите Log Analytics в корзине ведения журнала по умолчанию:

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

Откройте панель управления Observability 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.

Примечание. Вы можете выборочно добавить конечные точки в белый список, используя функцию наблюдения за шлюзом агента. В этой практической работе для простоты разрешен доступ ко всем API.

Настройка явных правил исходящего трафика IAM предоставляет агенту разрешение направлять вызовы API через шлюз агента и прокси IAP для доступа к внешним сервисам 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 работают правильно. Теперь вы можете протестировать агента:

В консоли Google Cloud перейдите на страницу Развертывания агентов.
Выберите развернутого агента (gcp_agent_...).
Откройте вкладку Тестовая площадка.
В поле запроса введите: List storage buckets in the current project.
Убедитесь, что агент успешно возвращает список сегментов через частный шлюз агента.
Убедитесь, что агент не может получить доступ к сегментам из другого проекта из-за запрета на доступ. Вы можете проверить отказ в журналах аудита Cloud или на панели управления нарушениями Управления зонами безопасности VPC.

13. Организовать

Чтобы избежать списания средств с аккаунта Google Cloud за ресурсы, использованные в этой практической работе, удалите созданный проект:

gcloud projects delete ${PROJ_ID}

14. Поздравляю!

Поздравляем! Вы успешно настроили агента и шлюз агента в защищенном периметре Управления зонами безопасности VPC в Google Cloud.

Что дальше?

Изучите подробные правила для входящего и исходящего трафика в Управлении зонами безопасности VPC.
Настройте доступ и семантические правила с помощью шлюза агента.
Интегрируйте Model Armor для расширенной фильтрации контента в целях безопасности.