배포 환경 구성

이 문서에서는 API 게이트웨이 개발 환경을 구성하는 방법을 설명합니다.

기본 요건

API 게이트웨이에서 API를 만들려면 먼저 다음을 확인해야 합니다.

  • 편집자 또는 소유자 역할이 있는 Google Cloud 프로젝트를 만들었습니다. 초기 배포 후에는 사용자, 그룹 또는 서비스 계정에 더 제한적인 서비스 구성 편집자 역할을 부여할 수 있습니다.

  • 아래 설명된 대로 Google Cloud CLI가 준비되었습니다.

  • 아래 설명된 대로 필수 Google 서비스가 사용 설정되었습니다,

  • 아래 설명된 대로 API 구성을 만드는 데 사용되는 서비스 계정을 구성합니다.

배포용 Google Cloud CLI 준비

배포용으로 gcloud를 준비하려면 다음 안내를 따르세요.

  1. gcloud CLI를 설치하고 초기화합니다.
  2. gcloud CLI를 업데이트합니다. 
    gcloud components update
  3. gcloud CLI가 데이터와 서비스에 액세스할 수 있는 권한이 있는지 확인합니다. 
    gcloud auth login

    새 브라우저 탭이 열리고 계정을 선택하라는 메시지가 나타납니다.

  4. 기본 프로젝트를 설정합니다. PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다. 
    gcloud config set project PROJECT_ID

필수 서비스 사용 설정

API 게이트웨이를 사용하려면 다음 Google 서비스를 사용 설정해야 합니다.

이름 제목
apigateway.googleapis.com API 게이트웨이 API
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

필수 서비스가 사용 설정되어 있는지 확인하려면 다음을 사용하세요.

gcloud services list

필수 서비스가 나열되지 않으면 서비스를 사용 설정하세요.

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

gcloud 서비스에 대한 자세한 내용은 gcloud 서비스를 참조하세요.

서비스 계정 구성

게이트웨이에 배포된 API 구성은 게이트웨이 서비스 계정에 연결된 권한으로 실행됩니다.

일반적으로는 API 게이트웨이에 사용되는 것과 동일한 프로젝트에 개별 서비스 계정을 만드는 것이 좋습니다. 그런 후 백엔드 서비스에 액세스하는 데 필요한 권한만 서비스 계정에 할당합니다. 이런 방식으로 API 구성과 연결되는 권한을 제한합니다.

API 게이트웨이의 경우 API 구성 또는 게이트웨이를 만들거나 업데이트하려면 서비스 계정 객체에 대한 iam.serviceAccounts.actAs 권한이 필요합니다. 이 권한은 서비스 계정 사용자 역할에 포함되어 있습니다.

사용자의 서비스 계정에 역할 및 권한을 추가하기 위한 명령어는 다음과 같습니다.

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
  --member user:USER_EMAIL \
  --role roles/iam.serviceAccountUser

각 항목의 의미는 다음과 같습니다.

  • SERVICE_ACCOUNT_EMAIL은 SA_NAME@PROJECT_ID.iam.gserviceaccount.com 형식의 서비스 계정의 이메일입니다.
  • USER_EMAIL은 사용자의 이메일 주소입니다.

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

gcloud iam service-accounts add-iam-policy-binding my-service-account@my-project.iam.gserviceaccount.com \
  --member user:myemail@email.com \
  --role roles/iam.serviceAccountUser

또한 백엔드 서비스에 액세스하는 데 필요한 권한이 게이트웨이 서비스 계정에 있어야 합니다. 예를 들면 다음과 같습니다.

  • Cloud Function 백엔드의 경우 서비스 계정에 Cloud Functions 호출자 역할을 할당해야 합니다.
  • Cloud Run 백엔드의 경우 서비스 계정에 Cloud Run 호출자 역할을 할당해야 합니다.
  • App Engine 백엔드의 경우 IAP 액세스 설정의 단계에 따라 게이트웨이에 연결된 서비스 계정에 IAP 보안 웹앱 사용자 역할을 부여해야 합니다.

API 구성과 연결된 권한을 제한하면 백엔드 시스템의 보안 수준을 높일 수 있습니다. 자세한 내용은 Identity and Access Management(IAM) 문서를 참조하세요.

서비스 계정을 만든 후에는 --backend-auth-service-account 옵션을 사용하여 API 구성을 만들 때 서비스 계정의 이메일 주소를 지정합니다.

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION --project=PROJECT_ID \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

API 구성 만들기에 대한 자세한 내용은 API 만들기를 참조하세요.

기본 서비스 계정 사용

일부 GCP 제품은 기본 서비스 계정을 정의합니다. 예를 들어 Compute Engine을 사용 중이고 프로젝트에 Compute Engine API를 사용 설정했으면 기본 Compute Engine 서비스 계정이 생성됩니다. 기본 서비스 계정은 해당 이메일 주소로 식별될 수 있습니다.

PROJECT_NUMBER-compute@developer.gserviceaccount.com

기본 서비스 계정에 필요한 권한을 할당하는 경우 API 구성을 만들 때 --backend-auth-service-account 옵션을 생략할 수 있습니다.

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION --project=PROJECT_ID

자세한 내용은 Compute Engine 기본 서비스 계정 사용을 참조하세요.

OpenID Connect 사용

API 게이트웨이에서 백엔드 서비스로의 요청에는 인증이 사용될 수 있습니다. 이러한 요청은 게이트웨이의 서비스 계정으로 서명된 OpenID Connect(OIDC) 토큰을 사용하여 보호됩니다. 인증 및 승인을 위해 OIDC 토큰을 허용하도록 백엔드 서비스가 올바르게 구성되었는지 확인합니다. Cloud Functions, Cloud Run, IAP(Identity Aware Proxy)에서 이 옵션이 제공됩니다.

다음 단계