엔드포인트 등록

에이전트 레지스트리를 사용하면 외부 REST API와 같은 대상 URL을 관리형 엔드포인트로 수동으로 등록하여 에이전트 Fleet이 연결할 수 있는 대상을 중앙에서 제어할 수 있습니다.

us 및 eu 멀티 리전 위치에서는 엔드포인트 등록이 지원되지 않습니다. 지원되는 리전 또는 global 위치를 사용해야 합니다. 자세한 내용은 Agent Registry 위치를 참조하세요.

시작하기 전에

  1. Agent Registry 설정

  2. Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다.

  3. 이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정합니다.

필요한 역할

Agent Registry에 엔드포인트를 등록하는 데 필요한 권한을 얻으려면 관리자에게 Agent Registry가 사용 설정된 거버넌스 프로젝트에 대한 Agent Registry API 편집자 (roles/agentregistry.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

엔드포인트 등록

엔드포인트는 커스텀 외부 대상이므로 수동 등록을 사용하여 Agent Registry에 추가합니다.

콘솔

  1. Google Cloud 콘솔에서 에이전트 레지스트리로 이동합니다.

    에이전트 레지스트리로 이동

  2. 프로젝트 선택 도구에서 에이전트 레지스트리를 설정한 Google Cloud 프로젝트를 선택합니다.

  3. 엔드포인트 탭을 선택합니다.

  4. 엔드포인트 추가를 클릭합니다.

  5. 엔드포인트 세부정보 패널에서 표시 이름, 설명, 지리적 리전, 도착 URL을 입력합니다.

    필요한 경우 이 패널에서 연결 테스트를 클릭하여 도착 URL에 대한 연결을 테스트합니다.

  6. 저장을 클릭합니다.

gcloud

사용하는 사양 플래그에 따라 구성요소가 속하는 리소스 컬렉션이 결정됩니다. 플래그와 리소스 컬렉션의 전체 매핑은 [서비스 리소스 및 검색 리소스](/agent-registry/data-model#service-resources)를 참고하세요.

에이전트 레지스트리에 엔드포인트를 추가하려면 gcloud agent-registry services create 명령어와 --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) 이름은 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
  • PROJECT_ID: 프로젝트 ID입니다.
  • REGION: 레지스트리 리전입니다.
  • DISPLAY_NAME: 엔드포인트의 인간이 읽을 수 있는 이름입니다(예: My External API).
  • ENDPOINT_URL: 대상 URL입니다(예: https://api.example.com/v1/data).
  • PROTOCOL: 인터페이스의 프로토콜 바인딩 유효한 값은 http-json, grpc 또는 jsonrpc입니다.

Service 리소스가 생성되면 에이전트 레지스트리는 에이전트와 조정자가 검색하고 사용할 수 있는 읽기 전용 Endpoint 리소스를 자동으로 생성합니다.

Terraform

구성하는 사양 블록에 따라 구성요소가 속하는 리소스 컬렉션이 결정됩니다. 사양과 리소스 컬렉션의 전체 매핑은 [서비스 리소스 및 검색 리소스](/agent-registry/data-model#service-resources)를 참고하세요.

외부 엔드포인트를 등록하려면 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). 이름은 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
  • DISPLAY_NAME: 엔드포인트의 인간이 읽을 수 있는 이름입니다(예: My External API).
  • ENDPOINT_URL: 대상 URL입니다(예: https://api.example.com/v1/data).
  • PROTOCOL: 인터페이스의 프로토콜 바인딩 유효한 값은 HTTP_JSON, GRPC 또는 JSONRPC입니다.

복합 Google API 엔드포인트 등록

교차 프로젝트 아키텍처에서 중앙 거버넌스 프로젝트는 Agent Registry 및 Agent Gateway와 같은 공유 인프라를 호스팅하고 별도의 Google Cloud 프로젝트는 에이전트 컴퓨팅 인스턴스를 호스팅합니다.

이그레스 모드에서 Agent Gateway를 통해 에이전트 트래픽을 라우팅하면 아웃바운드 네트워크 트래픽이 기본적으로 차단됩니다. 별도의 Google Cloud 프로젝트에 있는 에이전트가 필수Google Cloud API와 통신할 수 있도록 중앙 거버넌스 프로젝트에서 여러 API 인터페이스를 단일 복합 Service 리소스로 그룹화할 수 있습니다.

인터페이스를 단일 엔드포인트로 그룹화하면 전체 핵심 Google API 제품군에 대해 단일 IAP (Identity-Aware Proxy) 정책 바인딩을 관리할 수 있으므로 정책 관리가 간소화됩니다.

복합 Google API 엔드포인트를 등록하려면 다음 단계를 따르세요.

gcloud

gcloud agent-registry services create 명령어를 사용하여 중앙 거버넌스 프로젝트에서 여러 인터페이스 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). 이름은 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
  • 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(예: core-gapi-services) 이름은 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
  • DISPLAY_NAME: 인간이 읽을 수 있는 이름입니다(예: Core Google APIs).
  • 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 블록을 반복합니다.

다음 단계