엔드포인트 사용량 제한

이 페이지에서는 기업 관리자가 Google Cloud 리소스 계층 구조 내에서 사용할 수 있는 Google Cloud API 엔드포인트를 제어할 수 있게 해주는 엔드포인트 사용 제한 조직 정책 제약조건에 대한 개요를 제공합니다.

관리자는 이 제약 조건을 사용하여 전역, 위치 또는 리전 기반 엔드포인트와 같이 허용된 Google Cloud API 엔드포인트에 대한 계층적 제한을 정의할 수 있습니다. 예를 들어 전역 bigquery.googleapis.com 엔드포인트에 대한 요청은 거부하지만 위치 기반 LOCATION-biguery.googleapis.com 엔드포인트에 대한 요청은 허용하도록 프로젝트를 구성할 수 있습니다. 전역 API 엔드포인트 사용을 제한하면 조직은 허용된 위치 또는 리전 엔드포인트만 사용하도록 하여 규정 준수 요구사항을 충족할 수 있습니다.

엔드포인트 사용 제한 제약 조건은 차단 목록을 사용하여 설정되며, 명시적으로 거부되지 않은 지원되는 모든 서비스의 API 엔드포인트에 대한 요청을 허용합니다.

이 제약조건은 범위 내 모든 리소스에 대한 런타임 액세스를 제어합니다. 이 제약조건이 포함된 조직 정책이 업데이트되면 정책 범위 내의 모든 리소스에 즉시 적용되고 eventual consistency를 가집니다.

관리자는 이 제약조건이 포함된 조직 정책 업데이트를 신중하게 관리하는 것이 좋습니다. 예를 들어 정책 변경사항이 적용되기 전에 정책 변경사항이 기존 워크플로에 미치는 영향을 모니터링할 수 있도록 테스트 실행 모드에서 정책을 설정하는 것이 좋습니다.

API 엔드포인트 유형

API 엔드포인트 (또는 서비스 엔드포인트)는 bigquery.googleapis.com과 같은 Google Cloud API 서비스의 네트워크 주소를 지정하는 URL입니다. Google Cloud 서비스를 사용하면 전역, 위치, 리전 엔드포인트를 비롯한 다양한 유형의 API 엔드포인트를 사용하여 리소스에 액세스할 수 있습니다. 각 유형에 대한 지원은 서비스에 따라 다릅니다.

• 전역 API 엔드포인트는 URL 호스트 이름에서 위치를 지정하지 않습니다. 예를 들면 다음과 같습니다.

  • storage.googleapis.com
  • content-bigqueryconnection.googleapis.com
  • bigquerydatatransfer.mtls.googleapis.com
  • logging.googleapis.com

  이러한 전역 범위 엔드포인트는 가능한 한 클라이언트와 가까운 곳에서 TLS 세션을 종료하는 고가용성 서비스 엔드포인트를 제공하므로 인터넷을 통해 분산된 클라이언트 집합에서 API 호출을 제공할 때 지연 시간을 최소화합니다.

• 위치 기반 API 엔드포인트는 URL 호스트 이름의 위치를 지정합니다. 예를 들면 다음과 같습니다.

  • us-storage.googleapis.com
  • content-us-west3-bigqueryconnection.googleapis.com
  • us-west1-bigquerydatatransfer.mtls.googleapis.com
  • us-central1-logging.googleapis.com

  이러한 위치 기반 엔드포인트는 위치가 특정된 서비스를 사용해야 하고 비공개 연결을 통해 액세스할 때 전송 중인 데이터가 특정 위치에 유지되도록 하려는 고객에게 가장 유용합니다.

• 리전 API 엔드포인트는 위치를 하위 도메인으로 지정합니다. 예를 들면 다음과 같습니다.

  • storage.us-east2.rep.googleapis.com
  • content-bigqueryconnection.us-west3.rep.googleapis.com
  • bigquerydatatransfer.us-west1.rep.mtls.googleapis.com
  • logging.us-central1.rep.googleapis.com

  이러한 리전 엔드포인트는 위치가 특정된 서비스를 사용해야 하고 비공개 연결 또는 공개 인터넷을 통해 액세스할 때 전송 중인 데이터가 특정 위치에 유지되도록 하려는 고객에게 가장 유용합니다.

제한사항

엔드포인트 사용 제한 제약 조건은 특정 API 엔드포인트를 사용하여 리소스에 액세스하는 기능을 제어합니다. 다음과 같은 다른 유사한 제약 조건과 혼동해서는 안 됩니다.

• 리소스 위치 제한 제약조건: 리소스를 생성할 수 있거나 생성할 수 없는 위치를 제어합니다.
• 사용할 수 있는 리소스 서비스를 제어하는 리소스 서비스 사용 제한 제약조건

기존 서빙 인프라를 손상시키지 않으려면 비프로덕션 프로젝트와 폴더에서 새 조직 정책을 테스트한 후 조직 내에서 정책을 점진적으로 적용해야 합니다.

이 제약조건은 제품 및 리소스 유형의 특정 하위 집합에 적용됩니다. 지원 서비스의 목록과 각 서비스의 동작에 대한 세부 사항은 지원되는 API 엔드포인트 섹션을 참조하세요.

데이터 스토리지 약정은 Google Cloud 서비스 약관 및 서비스별 약관을 참고하세요. 엔드포인트 사용 제한 제약 조건이 포함된 조직 정책은 데이터 상주 약정이 아닙니다.

조직 정책 설정

조직 정책을 설정, 변경 또는 삭제하려면 조직 정책 관리자 역할이 있어야 합니다.

조직 정책 제약조건은 조직, 폴더, 프로젝트 수준에서 설정할 수 있습니다. 각 정책은 해당 리소스 계층 구조 내 모든 리소스에 적용되지만 리소스 계층 구조의 하위 수준에서 재정의될 수 있습니다.

정책 평가에 대한 자세한 내용은 계층 구조 평가 이해를 참조하세요.

엔드포인트 사용 제한 제약조건은 일종의 목록 제약조건입니다. 제약조건의 denied_values 목록에서 엔드포인트를 추가하고 삭제할 수 있습니다.

constraint: constraints/gcp.restrictEndpointUsage
listPolicy:
    deniedValues:
    - storage.googleapis.com
    - content-bigqueryreservation.googleapis.com
    - bigquerystorage.mtls.googleapis.com
    - logging.googleapis.com

gcloud resource-manager org-policies set-policy \
--RESOURCE_TYPE='RESOURCE_ID' /tmp/policy.yaml

constraint: constraints/gcp.restrictEndpointUsage
etag: CKCRl6oGEPjG-tMB
listPolicy:
  deniedValues:
  - storage.googleapis.com
  - content-bigqueryreservation.googleapis.com
  - bigquerystorage.mtls.googleapis.com
  - logging.googleapis.com
updateTime: '2023-11-04T04:29:20.444507Z'

차단된 API 엔드포인트에 대한 요청이 리소스에 액세스하려고 시도하면 요청이 실패하고 이 실패의 이유를 설명하는 오류가 반환됩니다.

테스트 실행 모드의 조직 정책 만들기

테스트 실행 모드의 조직 정책은 정책 위반이 감사 로그로 작성되지만 위반 작업이 거부되지 않는 조직 정책 유형입니다. 엔드포인트 사용량 제한 제약조건을 사용하여 테스트 실행 모드의 조직 정책을 만들어 활성 정책을 적용하기 전에 제약조건이 조직에 미치는 영향을 모니터링합니다. 자세한 내용은 테스트 실행 모드의 조직 정책 만들기를 참조하세요.

오류 메시지

엔드포인트를 거부하도록 조직 정책을 설정하면 리소스 계층 구조 내에서 해당 엔드포인트를 사용하는 작업이 실패합니다. 이 실패 이유를 설명하는 오류가 반환됩니다. 또한 추가 모니터링, 알림 또는 디버깅을 위해 감사 로그 항목이 생성됩니다.

오류 메시지 예시

다음 예시에서는 정책 적용으로 인해 API 엔드포인트 storage.googleapis.com을 사용한 curl 요청이 실패합니다.

curl -X GET \
-H "Authorization: Bearer OAUTH2_TOKEN" \
-o "SAVE_TO_LOCATION" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"

Access to projects/foo-123 through endpoint storage.googleapis.com was denied by
the constraints/gcp.endpointUsageRestriction organization policy constraint. To
access this resource, please use an allowed endpoint.

감사 로그 항목 예시

다음 감사 로그 항목 예시는 리소스에 대한 액세스가 거부된 경우를 보여줍니다.

{
  logName: "projects/my-projectid/logs/cloudaudit.googleapis.com%2Fpolicy"
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    status: {
      code: 7
      message: "Access to projects/my-projectid through endpoint bigquery.googleapis.com was denied by the constraints/gcp.restrictEndpointUsage organization policy constraint. To access this resource, please use an allowed endpoint."
    }
    serviceName: "bigquery.googleapis.com"
    methodName: "google.cloud.bigquery.v2.TableDataService.InsertAll"
    resourceName: "projects/my-projectid"
    authenticationInfo: {
      principalEmail: "user_or_service_account@example.com"
    }
  }
  requestMetadata: {
    callerIp: "123.123.123.123"
  }
  policyViolationInfo: {
    orgPolicyViolationInfo: {
      violationInfo: [
        {
          constraint: "constraints/gcp.restrictEndpointUsage"
          checkedValue: "bigquery.googleapis.com"
          policyType: LIST_CONSTRAINT
        }
      ]
    }
  }
  resource: {
    type: "audited_resource"
    labels: {
      project_id: "224034263908"
      method: "google.cloud.bigquery.v2.TableDataService.InsertAll"
      service: "bigquery.googleapis.com"
    }
  }
  severity: "ERROR"
  timestamp: "2024-12-05T01:15:30.332519510Z"
  receiveTimestamp: "2024-08-15T17:55:01.159788588Z"
  insertId: "42"
}

지원되는 API 엔드포인트

다음 API 엔드포인트는 엔드포인트 사용 제한 제약조건에서 지원됩니다.

값 그룹

값 그룹은 엔드포인트 제한을 더 간단하게 정의할 수 있도록 Google에서 선별한 그룹 및 API 엔드포인트 모음입니다. 값 그룹은 관련 API 엔드포인트를 여러 개 포함하며 새 엔드포인트를 수용하도록 조직 정책을 변경하지 않아도 시간이 갈수록 Google에서 확장합니다.

조직 정책에 값 그룹을 사용하려면 in: 문자열을 항목의 프리픽스로 지정하세요. 값 프리픽스 사용에 대한 자세한 내용은 제약조건 사용을 참조하세요. 조직 정책을 설정하기 위한 호출에서 그룹 이름이 검증됩니다. 잘못된 그룹 이름을 사용하면 정책 설정이 실패합니다.

다음 표에는 현재 사용 가능한 그룹 목록이 나와 있습니다.