Agent Registry에서 엔드포인트는 에이전트가 액세스하는 대상 URL( 일반적으로 REST API)을 나타냅니다. 이러한 대상을 Agent Registry 내에서 관리형 에이전트 구성요소로 등록하면 에이전트 Fleet이 연결할 수 있는 외부 엔드포인트를 중앙에서 관리할 수 있습니다.
이 문서에서는 레지스트리에 외부 엔드포인트를 명시적으로 등록하는 방법을 설명합니다.
시작하기 전에
시작하기 전에 Agent Registry를 설정합니다. 이러한 작업을 수행하려면 프로젝트 ID가 필요합니다.
이 문서에서 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정해야 합니다.
필요한 역할
Agent Registry에 엔드포인트를 등록하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Agent Registry API 편집자 (roles/agentregistry.editor) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
엔드포인트 등록
엔드포인트는 커스텀 외부 대상이므로 수동 등록을 사용하여 Agent Registry에 추가합니다.
콘솔
콘솔 Google Cloud 에서 Agent Registry로 이동합니다.
엔드포인트 탭을 선택합니다.
엔드포인트 추가 를 클릭합니다.
엔드포인트 세부정보 패널에서 표시 이름, 설명, 지리적 리전, 도착 URL을 입력합니다.
선택적으로 이 패널에서 연결 테스트 를 클릭하여 도착 URL에 대한 연결을 테스트합니다.
저장 을 클릭합니다.
gcloud
endpoint-spec-type이 no-spec인 Service 리소스를 만듭니다.
엔드포인트를 등록하고 인터페이스 연결 세부정보를 정의합니다.
gcloud agent-registry services create ENDPOINT_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--endpoint-spec-type=no-spec \
--interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
다음을 바꿉니다.
ENDPOINT_NAME: 엔드포인트에 지정할 이름(예:my-external-api)PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.DISPLAY_NAME: 사람이 읽을 수 있는 엔드포인트 이름입니다.ENDPOINT_URL: 대상 URL(예:https://api.example.com/v1/data)PROTOCOL: 인터페이스의 프로토콜 바인딩입니다. 유효한 값은http-json,grpc또는jsonrpc입니다.
Service 리소스가 생성되면 Agent Registry는 에이전트와
오케스트레이터가 검색하고 사용할 수 있는 소비자 측에 읽기 전용 Endpoint 리소스를 자동으로
생성합니다.
Terraform
외부 엔드포인트를 등록하려면 endpoint_spec 블록으로 google_agent_registry_service 리소스를 구성합니다.
resource "google_agent_registry_service" "endpoint" {
location = "REGION"
service_id = "ENDPOINT_NAME"
display_name = "DISPLAY_NAME"
description = "An external REST API registered using Terraform."
interfaces {
url = "ENDPOINT_URL"
protocol_binding = "PROTOCOL"
}
endpoint_spec {
type = "NO_SPEC"
}
}
output "endpoint_resource_name" {
description = "The generated read-only Endpoint resource name."
value = google_agent_registry_service.endpoint.registry_resource
}
다음을 바꿉니다.
REGION: 레지스트리 리전입니다.ENDPOINT_NAME: 엔드포인트에 지정할 고유 이름(예:my-external-api)DISPLAY_NAME: 사람이 읽을 수 있는 엔드포인트 이름입니다.ENDPOINT_URL: 대상 URL(예:https://api.example.com/v1/data)PROTOCOL: 인터페이스의 프로토콜 바인딩입니다. 유효한 값은HTTP_JSON,GRPC또는JSONRPC입니다.
복합 Google API 엔드포인트 등록
교차 프로젝트 아키텍처에서 중앙 거버넌스 프로젝트는 Agent Registry 및 Agent Gateway와 같은 공유 인프라를 호스팅하고 개별 워크로드 프로젝트는 에이전트 컴퓨팅 인스턴스를 호스팅합니다.
이그레스 모드에서
Agent Gateway
를 통해 에이전트 트래픽을 라우팅하면 기본적으로 아웃바운드 네트워크 트래픽이 차단됩니다. 워크로드 프로젝트의 에이전트가 essential Google Cloud APIs와 통신하도록 하려면 중앙 거버넌스 프로젝트에서 여러 API 인터페이스를 단일 복합 Service 엔드포인트로 그룹화할 수 있습니다.
인터페이스를 단일 엔드포인트로 그룹화하면 전체 핵심 Google API 제품군에 대해 단일 IAP 정책 바인딩을 관리할 수 있으므로 정책 관리가 간소화됩니다.
다음 단계에 따라 복합 Google API 엔드포인트를 등록합니다.
gcloud
중앙 거버넌스 프로젝트에서 여러 인터페이스 URL로 엔드포인트를 등록합니다.
gcloud agent-registry services create SERVICE_NAME \
--project=CENTRAL_PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--description="DESCRIPTION" \
--endpoint-spec-type=no-spec \
--interfaces=protocolBinding=jsonrpc,url=API_URL \
--interfaces=protocolBinding=jsonrpc,url=ADDITIONAL_API_URL
다음을 바꿉니다.
SERVICE_NAME: 서비스 식별자(예:core-gapi-services)CENTRAL_PROJECT_ID: Agent Registry 및 Agent Gateway를 호스팅하는 중앙 거버넌스 프로젝트의 프로젝트 ID입니다.REGION: 게이트웨이와 레지스트리가 있는 리전 입니다.DISPLAY_NAME: 사람이 읽을 수 있는 이름(예:Core Google APIs)DESCRIPTION: 간단한 설명(예:Essential Google APIs for agent operations)API_URL: 기본 Google API의 URL(예:https://telemetry.googleapis.com)ADDITIONAL_API_URL: 에이전트에 필요한 각 추가 Google API URL 또는 변형(예:https://cloudresourcemanager.googleapis.com,https://iamcredentials.googleapis.com,https://agentregistry.googleapis.com또는 리전 및 mTLS 변형(예:https://telemetry.mtls.googleapis.com))에 대해--interfaces플래그를 반복합니다.
Terraform
Terraform을 사용하여 복합 Google API 엔드포인트를 등록하려면 여러 interfaces 블록으로 google_agent_registry_service 리소스를 정의합니다.
resource "google_agent_registry_service" "core_gapi_services" {
project = "CENTRAL_PROJECT_ID"
location = "REGION"
service_id = "SERVICE_NAME"
display_name = "DISPLAY_NAME"
description = "DESCRIPTION"
endpoint_spec {
type = "NO_SPEC"
}
interfaces {
url = "API_URL"
protocol_binding = "JSONRPC"
}
# Add an interfaces block for each additional Google API URL
interfaces {
url = "ADDITIONAL_API_URL"
protocol_binding = "JSONRPC"
}
}
다음을 바꿉니다.
CENTRAL_PROJECT_ID: 중앙 거버넌스 프로젝트의 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.SERVICE_NAME: 서비스 ID입니다.DISPLAY_NAME: 사람이 읽을 수 있는 이름입니다.DESCRIPTION: 서비스 설명입니다.API_URL: 기본 Google API의 URL(예:https://telemetry.googleapis.com)ADDITIONAL_API_URL: 에이전트에 필요한 각 추가 Google API URL 또는 변형(예:https://cloudresourcemanager.googleapis.com,https://iamcredentials.googleapis.com,https://agentregistry.googleapis.com또는 리전 및 mTLS 변형(예:https://telemetry.mtls.googleapis.com))에 대해interfaces블록을 반복합니다.
다음 단계
- 등록된 엔드포인트를 관리하고 검색하는 방법을 알아봅니다.
- 등록된 엔드포인트에 대한 IAM 이그레스 정책을 구성 하는 방법을 알아봅니다.