API 게이트웨이 및 gRPC용 Cloud Run 시작하기

이 페이지에서는 gRPC로 Cloud Run 백엔드 서비스를 관리 및 보호하도록 API 게이트웨이를 설정하는 방법을 보여줍니다.

작업 목록

다음 태스크 목록을 사용하여 튜토리얼을 진행하세요. gRPC로 Cloud Run 백엔드 서비스에 대해 API 게이트웨이를 배포하기 위해서는 모든 태스크를 수행해야 합니다.

  1. Google Cloud 프로젝트를 만들거나 선택합니다.
  2. 자체 Cloud Run을 배포하지 않았으면 샘플 백엔드 gRPC 서비스를 배포합니다. 시작하기 전에의 7단계를 참조하세요.
  3. 필요한 API 게이트웨이 서비스를 사용 설정합니다.
  4. API를 설명하는 gRPC API 구성 문서를 만들고 Cloud Run 경로를 구성합니다. gRPC로 API 구성 설정을 참조하세요.
  5. API 구성을 사용하여 API 게이트웨이를 배포합니다. API 게이트웨이 배포를 참조하세요.
  6. 요청을 전송하여 API 배포를 테스트합니다. API에 요청 보내기를 참조하세요.
  7. 서비스에 대한 활동을 추적합니다. API 활동 추적을 참조하세요.
  8. Google Cloud 계정에 요금이 청구되지 않도록 합니다. 삭제를 참조하세요.

시작하기 전에

  1. Google Cloud 콘솔에서 대시보드 페이지로 이동하고 Google Cloud 프로젝트를 선택하거나 만듭니다.

    대시보드 페이지로 이동

  2. 프로젝트에 결제가 사용 설정되어 있는지 확인하세요.

    결제 사용 설정 방법 알아보기

  3. 나중에 필요하므로 프로젝트 ID를 기록합니다. 이 페이지의 나머지 부분에서는 프로젝트 ID를 PROJECT_ID라고 합니다.

  4. 나중에 필요하므로 프로젝트 번호를 기록합니다. 이 페이지의 나머지 부분에서는 프로젝트 번호를 PROJECT_NUMBER라고 합니다.

  5. Google Cloud CLI를 다운로드하고 설치합니다.

    gcloud CLI 다운로드

  6. gRPC Python 빠른 시작의 단계를 따라 gRPC와 gRPC 도구를 설치합니다.

  7. 이 튜토리얼에서 사용할 python-grpc-bookstore-server 예시 백엔드 gRPC Cloud Run 서비스를 배포합니다. gRPC 서비스는 다음 컨테이너 이미지를 사용합니다.

    gcr.io/endpointsv2/python-grpc-bookstore-server:2

    빠른 시작: 사전 빌드된 샘플 컨테이너 배포의 단계에 따라 서비스를 배포합니다. 해당 빠른 시작에 지정된 컨테이너 이미지를 gcr.io/endpointsv2/python-grpc-bookstore-server:2로 바꿔야 합니다.

    서비스 URL과 함께 서비스가 배포된 리전 및 프로젝트 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 서비스를 참조하세요.

gRPC로 API 구성 만들기

bookstore-grpc 샘플에는 로컬로 복사하고 구성해야 하는 파일이 포함되어 있습니다.

  1. 서비스 .proto.파일에서 독립적인 protobuf 설명자 파일을 만듭니다.
    1. 예시 저장소에서 bookstore.proto 사본을 현재 작업 디렉터리에 저장합니다. 이 파일은 Bookstore 서비스의 API를 정의합니다.
    2. 작업 디렉터리 아래에 다음 디렉터리를 만듭니다. mkdir generated_pb2
    3. protoc 프로토콜 버퍼 컴파일러를 사용하여 설명자 파일 api_descriptor.pb를 만듭니다. bookstore.proto를 저장한 디렉터리에서 다음 명령어를 실행합니다.
      python3 -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto
      

      앞의 명령어에서 --proto_path는 현재 작업 디렉터리로 설정됩니다. gRPC 빌드 환경에서 .proto 입력 파일에 다른 디렉터리를 사용할 경우 컴파일러가 bookstore.proto 파일이 저장된 디렉터리를 검색하도록 --proto_path를 변경합니다.

  2. 현재 작업 디렉터리(bookstore.proto가 포함된 같은 디렉터리)에 api_config.yaml이라는 텍스트 파일을 만듭니다. 편의상 이 페이지는 gRPC API 구성 문서를 해당 파일 이름으로 참조하지만 원하는 경우 다른 이름을 지정할 수 있습니다. 파일에 다음 내용을 추가합니다.
    # The configuration schema is defined by the service.proto file.
    # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto
    
    type: google.api.Service
    config_version: 3
    name: "*.apigateway.PROJECT_ID.cloud.goog"
    title: API Gateway + Cloud Run gRPC
    apis:
      - name: endpoints.examples.bookstore.Bookstore
    usage:
      rules:
      # ListShelves methods can be called without an API Key.
      - selector: endpoints.examples.bookstore.Bookstore.ListShelves
        allow_unregistered_calls: true
    backend:
      rules:
        - selector: "*"
          address: grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app
    
    들여쓰기 간격은 yaml 형식에서 중요합니다. 예를 들어 name 필드는 type과 동일한 수준이어야 합니다.
  3. name 필드에서 *.apigateway.PROJECT_ID.cloud.goog라는 서비스를 입력합니다. PROJECT_ID는 Google Cloud project ID의 이름입니다.

  4. backend.rules 섹션의 address 필드에서 grpcs://python-grpc-bookstore-server-HASH-uc.a.run.apppython-grpc-bookstore-server 백엔드 gRPC Cloud Run 서비스의 실제 URL로 바꿉니다. 여기서 HASH는 서비스를 만들 때 생성된 고유한 해시 코드입니다.

    이 예시에서는 시작하기 전에에서 만든 gRPC Bookstore 백엔드 서비스를 사용한다고 가정합니다. 필요한 경우 이 값을 Cloud Run 서비스의 URL로 바꿉니다.

  5. gRPC API 구성 문서를 저장합니다.
  6. API 구성을 만듭니다.
    gcloud api-gateway api-configs create CONFIG_ID \
    --api=API_ID --project=PROJECT_ID \
    --grpc-files=api_descriptor.pb,api_config.yaml
    각 항목의 의미는 다음과 같습니다.
    • CONFIG_ID는 API 구성의 이름을 지정합니다.
    • API_ID는 API의 이름을 지정합니다.
    • PROJECT_ID은 Google Cloud 프로젝트 이름을 지정합니다.
    예를 들면 다음과 같습니다.
    gcloud api-gateway api-configs create grpc-config \
    --api=grpc-test --project=my-test-project \
    --grpc-files=api_descriptor.pb,api_config.yaml

API 게이트웨이 배포

gRPC API 구성을 게이트웨이에 배포하기 위해 다음 명령어를 실행합니다.

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

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

  • GATEWAY_ID는 게이트웨이의 이름을 지정합니다.
  • API_ID는 이 게이트웨이와 연결된 API 게이트웨이 API의 이름을 지정합니다.
  • CONFIG_ID는 게이트웨이에 배포된 API 구성의 이름을 지정합니다.
  • GCP_REGION은 배포된 게이트웨이의 Google Cloud 리전입니다.

  • PROJECT_ID은 Google Cloud 프로젝트 이름을 지정합니다.

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

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

성공적으로 완료되면 다음 명령어를 사용해서 게이트웨이에 대한 세부정보를 확인할 수 있습니다.

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

이 명령어 결과에서 defaultHostname 속성 값을 기록해 둡니다. 이 값은 다음 단계에서 배포를 테스트하기 위해 사용되는 게이트웨이 URL의 호스트 이름 부분입니다.

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

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

API에 요청 보내기

샘플 API에 요청을 전송하려면 Python으로 작성된 샘플 gRPC 클라이언트를 사용할 수 있습니다.

  1. gRPC 클라이언트 코드가 호스팅된 git 저장소를 클론합니다.

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
  2. 작업 디렉토리를 다음과 같이 변경합니다.

    cd python-docs-samples/endpoints/bookstore-grpc/
  3. 종속 항목을 설치합니다.

    pip3 install virtualenv
    virtualenv env
    source env/bin/activate
    pip3 install -r requirements.txt
  4. 샘플 API로 요청을 전송합니다.

    python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

    프로토콜 식별자 없이 DEFAULT_HOSTNAME에서 게이트웨이의 defaultHostname 속성을 지정합니다. 예를 들면 다음과 같습니다.

    python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

API 활동 추적

  1. Google Cloud 콘솔의 API 게이트웨이 페이지에서 API의 활동 그래프를 확인합니다. API를 클릭하여 개요 페이지에서 활동 그래프를 확인합니다. 요청이 그래프에 반영되는 데 잠시 시간이 걸릴 수 있습니다.

  2. 로그 탐색기 페이지에서 API의 요청 로그를 확인합니다. 로그 탐색기 페이지 링크는 Google Cloud 콘솔의 API 게이트웨이 페이지에서 찾을 수 있습니다.

    API 게이트웨이 페이지로 이동

    API 게이트웨이 페이지에서 다음을 수행합니다.

    1. 확인할 API를 선택합니다.
    2. 세부정보 탭을 클릭합니다.
    3. 로그 아래의 링크를 클릭합니다.

지금까지 gRPC를 사용해서 API 게이트웨이에서 API를 배포하고 테스트했습니다.

삭제

이 빠른 시작에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 다음 안내를 따르세요.

또는 튜토리얼에 사용된 Google Cloud 프로젝트를 삭제할 수도 있습니다.