이 문서에서는 Agent Gateway 리소스의 배포 후 유지보수 태스크를 설명합니다. 아직 게이트웨이를 만들지 않았으면 Agent Gateway 설정을 참조하세요.
시작하기 전에
Agent Gateway 리소스를 관리하기 전에 다음 기본 요건을 확인하세요.
- 게이트웨이, 연결 템플릿, 승인 정책, 승인 확장 프로그램을 보고, 업데이트하고, 삭제하는 데 필요한 권한이 있는지 확인합니다. 전체 권한 목록은 필수 권한을 참조하세요.
- 프로젝트에서 필요한 서비스를 사용 설정합니다. 자세한 내용은 필수 API를 참조하세요.
- 게이트웨이에서 워크로드를 연결 해제하려면 Gemini Enterprise Agent Platform 배포의 에이전트 런타임 또는 Gemini Enterprise 앱을 관리할 수 있는 권한도 있어야 합니다.
게이트웨이 보기 및 검사
Google Cloud프로젝트에서 Agent Gateway 리소스를 나열하고 게이트웨이의 구성, 연결된 확장 프로그램, 출력 전용 메타데이터를 검사할 수 있습니다.
콘솔
Google Cloud 콘솔에서 게이트웨이 페이지로 이동합니다.
선택한 프로젝트의 게이트웨이 목록을 봅니다.
게이트웨이 이름을 클릭하여 세부정보 페이지를 엽니다.
- 세부정보 탭에서 개요, 액세스 승인, AI 보안, 서비스 확장 프로그램, VPC 구성 섹션을 검토합니다.
- 모니터링 가능성 탭에서 게이트웨이 트래픽 및 정책 측정항목을 검토합니다. 자세한 내용은 Agent Gateway 트래픽 모니터링을 참조하세요.
gcloud
특정 리전의 모든 게이트웨이를 나열합니다.
gcloud network-services agent-gateways list \ --location=LOCATION \ --project=PROJECT_ID
다음을 바꿉니다.
LOCATION: 게이트웨이가 배포된 리전입니다(예:us-central1).PROJECT_ID: 게이트웨이를 호스팅하는 Google Cloud프로젝트의 ID입니다.
특정 게이트웨이의 구성을 검사합니다.
gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \ --location=LOCATION \ --project=PROJECT_ID
AGENT_GATEWAY_NAME을 Agent Gateway 리소스 이름으로 바꿉니다.
변경할 수 없는 설정
연결된 Agent Registry 인스턴스, 보안 및 거버넌스 정책과 같은 대부분의 Agent Gateway 구성은 Agent Gateway 업데이트에 설명된 대로 즉시 수정할 수 있습니다. 하지만 특정 핵심 구성은 변경할 수 없으며 대체 게이트웨이를 배포해야 합니다. 게이트웨이를 수정하기 전에 다음 표를 확인하세요.
| 설정 | 변경 가능 여부 | 요구사항 또는 제한사항 |
|---|---|---|
| 게이트웨이 이름 및 리전 | 변경 불가 | 이름 또는 리전을 변경하려면 대체 게이트웨이를 배포합니다. |
제어되는 액세스 경로 ( |
변경 불가 | googleManaged.governedAccessPath에서 생성 시 구성됩니다. 바로 수정할 수 없습니다. |
Private Service Connect 네트워크 연결 ( |
설정 후 변경 불가 | 네트워크 연결을 게이트웨이에 연결한 후에는 변경하거나 삭제할 수 없습니다. |
에이전트 연결 템플릿 및 관련 Cloud DNS 피어링, TLS 트러스트 구성, VPC 이그레스 설정 |
조건부 변경 가능 | 새 템플릿이 여전히 동일한 networkAttachment를 참조하는 한 새 설정으로 다른 연결 템플릿을 참조하도록 게이트웨이 구성을 업데이트할 수 있습니다. |
게이트웨이를 교체하여 변경 불가능한 설정 변경
게이트웨이와 연결된 PSC 네트워크 연결과 같은 변경 불가능한 설정을 변경해야 하는 경우 대체 게이트웨이를 배포하고 워크로드를 새 게이트웨이로 마이그레이션해야 합니다.
- 대체 Agent Gateway를 만들고 Identity and Access Management(IAM) 및 승인 정책을 구성합니다. 자세한 내용은 Agent Gateway 설정을 참조하세요.
대체 게이트웨이를 사용하도록 워크로드를 업데이트합니다.
- Gemini Enterprise 앱: 앱의 보안 > 구성 설정에서 게이트웨이 리소스 이름을 업데이트합니다. Agent Gateway를 통해 Gemini Enterprise 트래픽 라우팅을 참조하세요.
- Agent Runtime 에이전트: 단일 프로젝트 및 리전 내에서 모든 Agent Runtime 에이전트는 동일한 게이트웨이에 바인딩되어야 합니다. 한 게이트웨이에서 다른 게이트웨이로의 직접 인플레이스 업데이트는 지원되지 않습니다. 에이전트를 마이그레이션하려면 다음 안내를 따르세요.
- 모든 바인딩된 에이전트가 트래픽의 100% 를 최신 버전(
trafficConfig.trafficSplitAlwaysLatest)으로 라우팅하는지 확인합니다. reasoningEngines.patch를 사용하여spec.deploymentSpec.agentGatewayConfig를{}로 설정하여 프로젝트 및 리전의 모든 에이전트를 이전 게이트웨이에서 연결 해제하고 각 업데이트 작업이 완료될 때까지 기다립니다.- 각 에이전트에서
reasoningEngines.patch를 호출하여spec.deploymentSpec.agentGatewayConfig를 대체 게이트웨이 리소스 이름으로 설정합니다. 요청 예시는 Agent Gateway를 통해 Agent Runtime 트래픽 라우팅을 참조하세요.
- 모든 바인딩된 에이전트가 트래픽의 100% 를 최신 버전(
모든 워크로드가 이전 게이트웨이 참조를 중지하면 Agent Gateway 삭제의 단계에 따라 이전 게이트웨이를 해제합니다.
Agent Gateway 업데이트
Google Cloud 콘솔에서 직접 또는 gcloud CLI를 사용하여 게이트웨이 구성을 YAML 파일로 내보내고, 변경하고, 파일을 다시 가져와서 특정 Agent Gateway 구성을 업데이트할 수 있습니다.
Agent Registry 업데이트
Google Cloud 콘솔 또는 gcloud CLI에서 연결된 에이전트 레지스트리를 업데이트할 수 있습니다. 게이트웨이는 게이트웨이 리전에 해당하는 단일 리전 레지스트리를 참조해야 합니다. 게이트웨이가 Gemini Enterprise 앱에 연결된 경우 게이트웨이는 해당 앱 위치와 일치하는 단일 레지스트리를 유지해야 합니다.
콘솔
Google Cloud 콘솔에서 게이트웨이 페이지로 이동합니다.
업데이트하려는 게이트웨이의 이름을 클릭합니다.
세부정보 탭의 개요 섹션에서 레지스트리 수정을 클릭합니다.
게이트웨이가 배포된 리전과 일치하는 리전 Agent Registry를 선택한 후 저장을 클릭합니다.
gcloud
gcloud
network-services agent-gateways export를 사용하여 게이트웨이 구성을 agent-gateway.yaml로 내보내고, registries, description 또는 labels를 수정하고(createTime, updateTime, agentGatewayCard, selfLink와 같은 출력 전용 필드 삭제), 게이트웨이의 연결 템플릿 업데이트에 표시된 대로 gcloud network-services agent-gateways import를 사용하여 파일을 다시 가져옵니다.
연결 템플릿 업데이트
gcloud CLI를 사용하여 Agent Gateway 리소스의 연결 템플릿을 업데이트할 수 있습니다.
gcloud
업데이트된 연결 설정으로 새
AgentConnectivityTemplate를 만들고 기존 게이트웨이와 동일한networkAttachment를 사용하는지 확인합니다. 자세한 템플릿 문법 및 구성 안내는 VPC 연결로 Agent Gateway 설정을 참조하세요.기존 게이트웨이 구성을 YAML 파일로 내보냅니다.
gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \ --destination="agent-gateway.yaml" \ --location=LOCATION \ --project=PROJECT_ID
다음을 바꿉니다.
AGENT_GATEWAY_NAME: 업데이트할 게이트웨이의 이름입니다.LOCATION: 게이트웨이가 배포된 리전입니다.PROJECT_ID: 게이트웨이가 배포된 프로젝트 ID입니다.
내보낸
agent-gateway.yaml파일에서 기존protocols,registries,description,labels필드를 그대로 유지하고 출력 전용 필드(createTime,updateTime,agentGatewayCard,selfLink)를 삭제하고 새 템플릿을 참조하도록agentConnectivityTemplate를 업데이트합니다.name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME protocols: - MCP googleManaged: governedAccessPath: AGENT_TO_ANYWHERE registries: - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME다음을 바꿉니다.
PROJECT_NUMBER: 게이트웨이가 배포된 숫자 프로젝트 번호입니다(agentConnectivityTemplate에는 프로젝트 ID가 아닌 프로젝트 번호가 필요함).LOCATION: 게이트웨이의 리전입니다.AGENT_GATEWAY_NAME: 게이트웨이의 이름입니다.NEW_TEMPLATE_NAME: 대체 연결 템플릿의 이름입니다.
업데이트된 YAML 파일을 다시 가져와 변경사항을 적용합니다.
gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \ --source="agent-gateway.yaml" \ --location=LOCATION \ --project=PROJECT_ID
선택사항: 게이트웨이 업데이트가 완료된 후 이전 연결 템플릿을 삭제합니다.
gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \ --location=LOCATION \ --project=PROJECT_ID
IAP 설정 또는 Model Armor 템플릿 수정
게이트웨이에 연결된 승인 확장 프로그램을 업데이트하여 IAP 시행 설정과 Model Armor 템플릿을 수정할 수 있습니다.
콘솔
Google Cloud 콘솔에서 게이트웨이 페이지로 이동합니다.
업데이트하려는 게이트웨이의 이름을 클릭합니다.
세부정보 탭에서 연결된 보안 확장 프로그램을 업데이트합니다.
IAP 시행 모드 변경: 액세스 승인 섹션에서 액세스 승인 옆에 있는 액세스 승인 수정을 클릭합니다. 감사 전용(테스트 실행 모드) 또는 정책 시행을 선택한 후 저장을 클릭합니다.
Model Armor 템플릿 변경: AI 보안 섹션에서 요청 템플릿 옆에 있는 요청 템플릿 수정 또는 응답 템플릿 옆에 있는 응답 템플릿 수정을 클릭합니다. 대체 템플릿을 선택한 다음 저장을 클릭합니다.
gcloud
게이트웨이 리전의 승인 확장 프로그램을 나열하여 확장 프로그램 이름을 식별합니다.
gcloud service-extensions authz-extensions list \ --location=LOCATION \ --project=PROJECT_ID
LOCATION를 게이트웨이의 리전으로 바꾸고PROJECT_ID를 프로젝트 ID로 바꿉니다.확장 프로그램의 현재 구성을 검사합니다.
gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \ --location=LOCATION \ --project=PROJECT_ID \ --format=yaml
IAP 또는 Model Armor
AuthzExtension리소스의 이름으로AUTHZ_EXTENSION_NAME을 바꿉니다.업데이트된 확장 프로그램 사양을
authz-extension.yaml에 저장하고createTime및updateTime와 같은 출력 전용 필드를 생략합니다.IAP 확장 프로그램: 감사 전용 모드의 경우
iamEnforcementMode: "DRY_RUN"를 포함하고 정책을 시행하려면iamEnforcementMode를 삭제합니다.name: AUTHZ_EXTENSION_NAME service: iap.googleapis.com failOpen: false timeout: 1s metadata: iapPolicyVersion: "V2" iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policiesModel Armor 확장 프로그램:
metadata.model_armor_settings에서request_template_id및response_template_id를 업데이트합니다.name: AUTHZ_EXTENSION_NAME service: modelarmor.LOCATION.rep.googleapis.com failOpen: false timeout: 1s metadata: model_armor_settings: '[ { "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID", "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID" } ]'다음을 바꿉니다.
AUTHZ_EXTENSION_NAME: Model ArmorAuthzExtension리소스의 이름입니다.LOCATION: 게이트웨이의 리전입니다.MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿을 호스팅하는 프로젝트 ID입니다.REQUEST_TEMPLATE_ID및RESPONSE_TEMPLATE_ID: 요청 및 응답 템플릿의 ID입니다.
게이트웨이 서비스 계정(
agentGatewayCard.serviceExtensionsServiceAccount)에 새로 참조된 템플릿 프로젝트에 대한roles/modelarmor.user과 게이트웨이 프로젝트에 대한roles/modelarmor.calloutUser및roles/serviceusage.serviceUsageConsumer가 있는지 확인합니다(승인 위임 참조).
업데이트된 확장 프로그램 YAML 파일을 가져옵니다.
gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \ --source="authz-extension.yaml" \ --location=LOCATION \ --project=PROJECT_ID
기존 AuthzPolicy에서 새 승인 정책을 연결하거나 트래픽 일치 규칙을 수정하려면 승인 위임을 참조하세요.
Agent Gateway에서 워크로드 연결 해제
Agent Gateway를 삭제하려면 먼저 게이트웨이를 참조하는 모든 Gemini Enterprise 앱과 Agent Runtime 에이전트를 연결 해제해야 합니다.
Gemini Enterprise 앱 연결 해제
Google Cloud 콘솔에서 Gemini Enterprise 앱에서 Agent Gateway를 연결 해제할 수 있습니다.
Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.
게이트웨이와 연결된 앱의 이름을 클릭합니다.
보안을 클릭합니다.
구성 탭의 Agent Gateway 구성에서 Agent Gateway 리소스 이름 필드를 지웁니다.
저장을 클릭합니다.
Agent Gateway를 연결 해제하면 게이트웨이를 통한 앱의 아웃바운드 트래픽 라우팅이 중지됩니다. 가져온 에이전트와 모델 컨텍스트 프로토콜(MCP) 서버는 Agent Registry에 등록된 상태로 유지되지만 게이트웨이를 다시 연결할 때까지 앱에서 액세스할 수 없습니다. 새 게이트웨이는 동일한 에이전트 레지스트리를 참조해야 합니다.
Agent Runtime 에이전트 연결 해제
Google Cloud 콘솔과 gcloud CLI는 Agent Runtime 게이트웨이 바인딩 수정을 지원하지 않습니다. 에이전트를 계속 실행하면서 배포된 Agent Runtime 에이전트에서 Agent Gateway를 연결 해제하려면 reasoningEngines.patch REST API 메서드를 호출하여 spec.deploymentSpec.agentGatewayConfig를 삭제하면 됩니다.
에이전트가 모든 트래픽을 최신 버전으로 라우팅하는지 확인합니다(
trafficConfig.trafficSplitAlwaysLatest가true로 설정되거나 수동trafficConfig분할이 구성되지 않음). 수동 버전 트래픽 분할이 활성 상태이고 이전의 모든 버전을 되돌릴 수 없게 보관처리하는 경우 게이트웨이 바인딩을 지우거나 변경하면 실패합니다. 자세한 내용은 Agent Gateway 및 버전을 참조하세요.updateMask=spec.deploymentSpec.agentGatewayConfig및 빈agentGatewayConfig객체({})를 사용하여 추론 엔진에PATCH요청을 보냅니다.curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "spec": { "deploymentSpec": { "agentGatewayConfig": {} } } }' \ "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"다음을 바꿉니다.
REGION: 에이전트가 배포된 리전입니다.PROJECT_ID: 에이전트가 배포된 프로젝트 ID입니다.RESOURCE_ID: 에이전트의 리소스 ID입니다.
Agent Gateway 삭제
Agent Gateway는 엄격한 참조 추적을 적용하여 분리된 보안 정책과 손상된 에이전트 트래픽 경로를 방지합니다. 다음 조건 중 하나라도 해당하는 경우 게이트웨이 삭제가 실패하고 Google Cloud 콘솔의 삭제 버튼을 사용할 수 없습니다.
- 하나 이상의 Agent Runtime 에이전트 또는 Gemini Enterprise 앱이 여전히 게이트웨이를 참조합니다.
AuthzPolicy(IAP, Model Armor 또는 커스텀 제공업체) 또는TelemetryPolicy는 여전히 게이트웨이를 타겟팅합니다.- VPC 구성 업데이트 작업이 게이트웨이에서 아직 실행 중입니다.
Agent Gateway를 삭제하고 연결된 리소스를 정리하려면 다음 단계를 순서대로 완료하세요.
콘솔
- Gemini Enterprise 앱이나 Agent Runtime 에이전트가 게이트웨이를 참조하지 않는지 확인합니다. Agent Gateway에서 워크로드 연결 해제의 안내를 따릅니다.
Google Cloud 콘솔에서 게이트웨이 페이지로 이동합니다.
삭제하려는 게이트웨이의 이름을 클릭합니다.
세부정보 탭에서 게이트웨이를 타겟팅하는 모든 정책 연결을 삭제합니다.
- 액세스 승인 섹션이 표시되면 삭제를 클릭한 후 삭제를 확인합니다. 이 작업을 수행하면 IAP
AuthzPolicy와AuthzExtension가 모두 삭제됩니다. - AI 보안 섹션이 표시되면 삭제를 클릭한 후 삭제를 확인합니다. 이 작업을 수행하면 Model Armor
AuthzPolicy와AuthzExtension가 모두 삭제됩니다. - 서비스 확장 프로그램 표를 확인합니다. 커스텀
AuthzPolicy리소스가 연결된 상태로 남아 있으면 이 절차의 gcloud 탭을 사용하여 삭제한 후 계속 진행합니다.
- 액세스 승인 섹션이 표시되면 삭제를 클릭한 후 삭제를 확인합니다. 이 작업을 수행하면 IAP
모든 정책 연결이 삭제되고 VPC 업데이트가 진행 중이 아니면 삭제를 클릭한 후 삭제를 확인합니다.
게이트웨이가 더 이상 프로젝트의 게이트웨이 목록에 표시되지 않는지 확인합니다.
선택사항: 다른 게이트웨이에서 사용하지 않는 경우 사용하지 않는 연결 리소스를 삭제합니다. gcloud 탭을 사용하여
AgentConnectivityTemplate를 삭제하고 네트워크 연결을 삭제합니다.
gcloud
- Gemini Enterprise 앱이나 Agent Runtime 에이전트가 게이트웨이를 참조하지 않는지 확인합니다. Agent Gateway에서 워크로드 연결 해제의 안내를 따릅니다.
승인 정책 및 승인 확장 프로그램을 삭제합니다.
게이트웨이 리전의 승인 정책을 나열하여
target.resources필드가 게이트웨이를 참조하는 정책을 찾고 참조된authzExtensions를 기록합니다.gcloud network-security authz-policies list \ --location=LOCATION \ --project=PROJECT_ID \ --format="yaml(name,target.resources,customProvider.authzExtension.resources)"
LOCATION를 게이트웨이의 리전으로 바꾸고PROJECT_ID를 프로젝트 ID로 바꿉니다.게이트웨이를 타겟팅하는 각
AuthzPolicy를 삭제합니다.gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \ --location=LOCATION \ --project=PROJECT_ID
AUTHZ_POLICY_NAME를 게이트웨이를 타겟팅하는 각 승인 정책의 ID로 바꿉니다(예: 콘솔에서 만든 정책의 경우AGENT_GATEWAY_NAME-iap-authzpolicy또는AGENT_GATEWAY_NAME-aisecurity-authzpolicy).선택사항: 참조하는
AuthzPolicy리소스를 삭제한 후 다른 정책에서 사용하지 않는AuthzExtension리소스를 삭제합니다.gcloud service-extensions authz-extensions delete AUTHZ_EXTENSION_NAME \ --location=LOCATION \ --project=PROJECT_ID
AUTHZ_EXTENSION_NAME를 사용되지 않는 승인 확장 프로그램의 ID로 바꿉니다.
Agent Gateway를 삭제합니다.
gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \ --location=LOCATION \ --project=PROJECT_ID
AGENT_GATEWAY_NAME을 삭제할 게이트웨이의 이름으로 바꿉니다.게이트웨이가 리전 게이트웨이 목록에 더 이상 표시되지 않는지 확인합니다.
gcloud network-services agent-gateways list \ --location=LOCATION \ --project=PROJECT_ID
선택사항: Agent Gateway에서 참조하는 동안에는
AgentConnectivityTemplate를 삭제할 수 없습니다. 게이트웨이를 삭제한 후 사용하지 않는 연결 템플릿을 삭제합니다.gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \ --location=LOCATION \ --project=PROJECT_ID
CONNECTIVITY_TEMPLATE_NAME을 사용하지 않는 연결 템플릿의 이름으로 바꿉니다. 기본 Private Service Connect 네트워크 연결, 비공개 Cloud DNS 영역 또는 인증서 관리자TrustConfig리소스가 더 이상 필요하지 않으면 네트워크 연결 삭제를 참조하세요.