API 게이트웨이 배포 모델

API 구성요소 정보

API 게이트웨이에서 정의되는 API는 두 가지 주요 구성요소로 구성됩니다.

  1. API 구성: API 정의를 업로드할 때 생성된 API 구성입니다. API 정의는 OpenAPI 사양으로 생성됩니다. API가 Cloud Run에서 gRPC 서비스를 관리하는 경우 gRPC 서비스 정의 및 구성을 사용하여 API를 정의할 수 있습니다.

    API 정의를 업로드할 때마다 API 게이트웨이가 새 API 구성을 만듭니다. 즉, API 구성을 만들 수 있지만 이를 나중에 수정할 수는 없습니다. 나중에 OpenAPI 사양 또는 gRPC 서비스 정의에서 API 정의를 수정하고 수정된 API 정의를 업로드하면 새로운 API 구성이 생성됩니다.

  2. 게이트웨이: 배포된 API 구성을 호스팅하는 Envoy 기반의 고성능 확장 가능한 프록시입니다. 게이트웨이에 API 구성을 배포하면 API 클라이언트가 API에 액세스하기 위해 사용되는 외부 연결용 URL이 생성됩니다.

다음 이미지는 이러한 구성요소를 보여줍니다.

API 게이트웨이 창의 API 정의에 3개의 API 구성 구성요소 및 3개의 게이트웨이 구성요소가 표시되어 있습니다.

게이트웨이에 API 구성 배포 정보

API 구성을 게이트웨이에 배포하여 API 클라이언트가 API에 액세스할 수 있게 합니다.

3개 샘플 API에서 API 구성이 게이트웨이에 배포되어, API 클라이언트가 API에 액세스할 수 있습니다.

게이트웨이:

  • 특정 GCP 리전에 배포됩니다. 리전은 GCP에서 사용자가 리소스를 배포할 수 있는 특정 지리적 리전입니다.

  • API 구성을 호스팅해야 합니다. API 구성이 없는 비어 있는 게이트웨이는 만들 수 없습니다. 하지만 게이트웨이가 생성된 다음에는 게이트웨이를 업데이트해서 하나의 API 구성을 다른 API 구성으로 바꿀 수 있습니다.

  • 단일 API 구성만 호스팅할 수 있습니다. 동일한 게이트웨이에 API 구성을 여러 개 배포할 수 없습니다.

그런 후 배포된 각 게이트웨이를 개별적으로 관리합니다. 각 게이트웨이에 대해 다음을 수행할 수 있습니다.

  • 게이트웨이 시작/중지/삭제
  • 로그 및 측정항목 보기
  • trace 정보 보기

GCP 리전 선택

각 게이트웨이는 GCP에서 특정 지리적 리전에 배포됩니다. API 게이트웨이는 배포에 대해 다음 GCP 리전을 지원합니다.

  • asia-northeast1
  • australia-southeast1
  • europe-west1
  • europe-west2
  • us-east1
  • us-east4
  • us-central1
  • us-west2
  • us-west3
  • us-west4

asia-east1에서 이전에 생성된 API 게이트웨이 지원은 2022년 11월 1일 종료됩니다. 현재 asia-east1에서 실행 중인 게이트웨이를 검토해서 이를 삭제하거나 필요에 따라 새 위치에 다시 만들어야 합니다.

배포된 API 구성의 엔드포인트 정의

API 구성을 게이트웨이에 배포하면 API 게이트웨이가 gateway.dev 도메인의 게이트웨이에 대해 고유한 URL을 만듭니다. 그러면 API 클라이언트가 아래 형식으로 URL을 사용해서 배포된 API 구성에 액세스할 수 있습니다.

https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev

여기서 GATEWAY_ID는 게이트웨이의 이름이고, HASH는 API를 배포할 때 생성된 고유한 해시 코드이고, REGION_CODE는 게이트웨이를 배포한 GCP 리전의 코드입니다.

예를 들면 다음과 같습니다.

my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

API 구성 배포를 위한 서비스 계정 구성

게이트웨이에 배포된 API 구성은 API 구성을 만드는 데 사용된 서비스 계정에 부여된 역할에 연결된 권한으로 실행됩니다. 따라서 일반적으로 API 구성을 만들기 위해 개별 서비스 계정을 정의합니다. 그런 후 서비스 계정에 백엔드 서비스 액세스에 필요한 역할만 할당됩니다. 이렇게 해서 API 구성과 연결되는 권한을 제한할 수 있습니다.

백엔드 서비스에 액세스하는 데 필요한 역할 외에도 서비스 계정에 다음 권한을 부여해야 합니다.

  • iam.serviceAccounts.actAs 권한. 이 권한은 서비스 계정 사용자 역할에 포함되어 있습니다.

  • 백엔드 서비스에 액세스하는 데 필요한 권한. 예를 들어 백엔드가 Cloud 함수로 구현되는 경우 서비스 계정에 최소한 Cloud Functions 호출자 역할을 할당해야 합니다. Cloud Run 백엔드의 경우에는 Cloud Run 호출자 역할입니다. API 구성과 연결된 권한을 제한하면 백엔드 시스템의 보안 수준을 높일 수 있습니다.

자세한 내용은 개발 환경 구성을 참조하세요.

Scale-to-zero 정보

API 게이트웨이는 scale-to-zero 서비스입니다. 즉, 트래픽이 없으면 모든 게이트웨이 인스턴스가 삭제됩니다. 트래픽이 증가하면 필요에 따라 로드 처리를 위해 새 인스턴스가 생성됩니다. Scale-to-zero는 GCP에서 자동으로 제어되며, 사용자가 이를 구성하거나 관리할 필요가 없습니다.

부하 분산기 사용

리전에 배포되는 각 게이트웨이에는 게이트웨이에 배포된 API에 대한 클라이언트 요청을 관리하기 위해 통합 부하 분산기가 포함되어 있습니다. 사용자가 각 게이트웨이에 대해 개별 부하 분산기를 만들 필요가 없습니다.

다른 리전에 있는 게이트웨이에 동일한 API를 배포할 때는 부하 분산기를 만들어야 합니다. 그러면 부하 분산기가 API 요청을 다른 리전으로 전달합니다. 자세한 내용은 아래에서 여러 리전에 API 배포를 참조하세요.

API에 대한 SSL 액세스 구성

API 게이트웨이는 게이트웨이에 배포된 API에 대한 HTTPS 액세스를 지원합니다. API가 gateway.dev 도메인에 배포되기 때문에 Google이 게이트웨이와 통합된 부하 분산기에서 SSL 인증서를 만들고 관리합니다. 사용자가 자신의 고유 인증서를 만들거나 업로드할 필요가 없습니다.

도메인 이름 서버 구성

기본적으로 API 클라이언트는 위에 표시된 것처럼 배포된 API에 액세스하도록 gateway.dev 도메인에 요청을 수행합니다.

커스텀 도메인 이름은 API 게이트웨이용 HTTP(S) 부하 분산미리보기과 함께 사용될 경우 API 게이트웨이에 사용됩니다. 도메인 이름을 맞춤설정하려면 커스텀 도메인 이름을 사용해서 부합 분산기를 만들고 배포된 API의 gateway.dev 도메인으로 요청을 전달합니다. 자세한 내용은 API 게이트웨이에 커스텀 도메인 사용을 참조하세요.

동일한 API에서 여러 API 구성 배포

하나의 게이트웨이에는 API 구성을 하나만 배포할 수 있습니다. 하지만 동일 API 내에서 여러 게이트웨이에 여러 API 구성을 배포할 수 있습니다.

이 섹션에서는 단일 API 내에서 여러 게이트웨이에 여러 API 구성을 배포할 수 있는 두 가지 시나리오에 대해 설명합니다.

동일한 리전의 여러 게이트웨이에 API 구성 배포

API를 빌드할 때 API 개발자는 다음과 같이 일반적으로 개발, 스테이징 및 프로덕션 환경을 만듭니다. 각 항목의 의미는 다음과 같습니다.

  • 개발 환경은 개발자가 API를 만드는 데 사용됩니다.
  • 스테이징 환경은 프로덕션 출시를 준비하면서 API를 테스트하는 데 사용됩니다.
  • 프로덕션 환경에서는 외부 API 클라이언트가 API에 액세스하도록 허용됩니다.

이러한 유형의 개발 환경을 지원하기 위해 여러 API 구성을 정의합니다. 예를 들어 개발 환경에서 여러 API 구성을 개발 중이고, 스테이징 환경에서 API 구성 하나를 테스트 중이고, 프로덕션 환경에 API 구성 하나가 배포된 상태일 수 있습니다.

API 게이트웨이를 사용하면 단일 API 내에서 여러 API 구성을 만들고 각 API 구성을 서로 다른 게이트웨이에 배포할 수 있습니다.

API 1에서는 API Config Dev, API Config Stage, API Config Prod라는 3개의 API 구성이 각각 3개의 게이트웨이에 배포되어 있습니다.

이 예시에서는 dev, stage, prod라는 3개의 API 구성이 있습니다. 그리고 각 API 구성을 서로 다른 게이트웨이에 배포하고, 각 게이트웨이는 자신의 고유 엔드포인트 URL을 정의합니다.

여러 리전에 API 구성 배포

여러 GCP 리전에 하나의 API를 배포하는 경우가 종종 있습니다. 여러 리전에 배포를 수행할 때는 몇 가지 이점이 있습니다. 클라이언트에 지리적으로 가까운 리전에서 실행되는 API로 요청이 전달되기 때문에 요청 지연 시간이 감소되고, 한 리전의 실패가 다른 리전에서 실행되는 API에 영향을 주지 않기 때문에 안정성이 향상됩니다.

여러 리전에 API를 배포하려면 각 리전의 게이트웨이에 API 구성을 배포합니다. 각 API 구성은 해당 리전의 백엔드 서비스를 참조해야 하기 때문에 배포된 리전에 한정됩니다.

다음 이미지에서 API 1과 2는 단일 리전에 배포되고 API 3은 여러 리전 간에 배포됩니다.

API 1 및 API 2는 Region 1에 배포되고 API 3은 부하 분산기를 사용하여 Region 1, Region 2, Region 3에 배포됩니다.

이 예시에서 API 3의 게이트웨이에 배포되는 각 API 구성은 다음 형식의 고유한 URL 엔드포인트를 갖습니다.

https://my-gateway1-a12bcd345e67f89g0h.uc.gateway.dev
https://my-gateway2-b12cde345f67g89h0i.en.gateway.dev
https://my-gateway3-c12bde345g67h89i0j.uw.gateway.dev

그런 후 API에 대한 요청을 처리하고 요청을 적절한 리전으로 전달하도록 API 게이트웨이용 HTTP(S) 부하 분산미리보기을 사용해서 부하 분산기를 구성합니다. 자세한 내용은 API 게이트웨이를 위한 멀티 리전 배포 만들기를 참조하세요.

API 업데이트

OpenAPI 사양에서 API 정의를 수정한 후 사양을 업로드하여 배포된 API를 업데이트할 수 있습니다. 새 사양을 업로드하면 새 API 구성이 생성됩니다.

API 게이트웨이는 제로 다운타임 업데이트 모델을 지원합니다. 즉, 업데이트된 API 구성을 배포하는 동안 API가 계속 요청을 처리합니다. 하지만 새 API 구성을 배포하는 동안 일정 기간에는 일부 요청이 이전 버전의 API 구성으로 처리될 수 있습니다.

여러 리전 및 게이트웨이에 API 구성을 배포한 경우에는 각 리전에 업데이트된 API 구성을 개별적으로 다시 배포해야 합니다.

다음 단계