ESPv2를 사용하여 Knative serving용 Cloud Endpoints gRPC 설정

Knative serving이 사용 설정된 GKE 클러스터 만들기

Google Cloud에서 클러스터를 만들고 Knative serving용으로 사용 설정하려면 다음 안내를 따르세요.

1. 다음 명령어를 사용하여 새 클러스터를 만듭니다.

   gcloud container clusters create CLUSTER_NAME \ 
     --addons=HttpLoadBalancing,CloudRun \ 
     --machine-type=n1-standard-4 \ 
     --num-nodes=3

   CLUSTER_NAME을 클러스터에 사용할 이름으로 바꿉니다.

   이 안내에서는 클러스터 자동 확장을 사용 설정하여 수요에 맞게 클러스터의 크기를 조절할 수 없지만 Google Cloud의 Knative serving은 인스턴스를 자동으로 확장합니다.

2. 클러스터 만들기가 완료될 때까지 기다립니다. 만드는 과정에서 다음과 비슷한 메시지가 표시됩니다.

   Creating cluster CLUSTER_NAME...done. 
   Created [https://container.googleapis.com/v1/projects/ESP_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME].

   출력의 NODE_VERSION 열 아래에 클러스터 버전도 표시됩니다. 예를 들면 1.15.11-gke.1 또는 1.14.10-gke.27입니다. 이 문서의 뒷부분에서 사용할 수 있도록 클러스터 버전을 기록해 둡니다.

3. 새 클러스터 및 클러스터 위치를 사용하도록 gcloud 기본값을 설정하면 이후 gcloud CLI를 사용할 때 이 두 값을 지정하지 않아도 됩니다.

   gcloud config set run/cluster CLUSTER_NAME
   gcloud config set run/cluster_location ZONE

4. 새 클러스터에 대한 세부 정보를 확인하려면 다음 명령어를 사용하세요.

   gcloud container clusters describe CLUSTER_NAME

5. 다음 명령어를 사용하여 클러스터의 사용자 인증 정보를 가져옵니다.

   gcloud container clusters get-credentials CLUSTER_NAME

샘플 gRPC Cloud Run 서비스 배포

'grpc-bookstore' Cloud Run for Anthos 샘플 컨테이너를 방금 만든 클러스터에 배포하려면 다음 안내를 따르세요.

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

2. 이 gRPC 서버 샘플 에는 Python 'grpc-bookstore 서비스'의 사전 빌드 Docker 이미지가 포함되어 있습니다. gcr.io/endpointsv2/python-grpc-bookstore-server:2. 다음 명령어를 사용하여 클러스터에 'grpc-bookstore'를 배포합니다.

   gcloud run deploy GRPC_SERVICE \
     --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2 \
     --platform=gke \
    --connectivity=internal \
     --use-http2

   외부에서 서비스에 액세스할 수 없도록 이를 내부 서비스로 지정합니다.

   GRPC_SERVICE를 서비스에 사용할 이름으로 바꿉니다. 예를 들면 다음과 같습니다.

   gcloud run deploy grpc-bookstore \
     --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2 \
     --platform=gke \
     --connectivity=internal \
     --use-http2

   작업을 마치면 다음 메시지가 표시됩니다.

   Service [grpc-bookstore] revision [grpc-bookstore-00001-nuk] has been deployed and is serving 100 percent of traffic at http://grpc-bookstore.default.svc.cluster.local

   내부 서비스를 만들면 GKE는 외부 요청이 아닌 클러스터 자체에서 시작된 요청에 대해서만 결정할 수 있는 DNS 이름(이 예시에서는 grpc-bookstore.default.svc.cluster.local)을 만듭니다. 클러스터에서는 이 DNS에 외부적으로 액세스할 수 없습니다. 자세한 내용은 Cloud Run 서비스를 참조하세요.

3. 서비스가 올바르게 작동하는지 확인하려면 동일한 Docker 이미지가 포함된 pod를 클러스터에 배포합니다. 이미지에는 내부 서비스를 테스트하는 데 사용할 수 있는 'grpc-bookstore'의 gRPC 클라이언트 코드가 포함되어 있습니다.

   1. 다음 kubectl 명령어를 사용하여 위와 배포한 것과 동일한 클러스터에 pod를 배포합니다.

      kubectl run grpc --generator=run-pod/v1 \
        --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2

      이 이미지에는 클러스터 내에서 클라이언트 요청을 수행하는 데 사용할 수 있는 bookstore_client.py 스크립트가 포함되어 있습니다.

      참고: 최신 버전의 kubectl에서는 명령어에 다음 경고가 표시될 수 있습니다.

      Flag --generator has been deprecated, has no effect and will be removed in the future".

      이 경고는 무시해도 됩니다.

   2. 이전 단계에서 Docker 이미지를 배포할 때 클러스터에 생성된 'grpc-bookstore' pod의 이름을 가져옵니다.

      kubectl get pods

      다음과 같은 형식으로 출력이 표시됩니다.

      NAME   READY    STATUS    RESTARTS   AGE
      grpc   1/1      Running   0          23h

      여기서 grp는 'grpc-bookstore' pod의 이름입니다. 계속하기 전에 pod의 상태가 실행 중인지 확인합니다.

   3. 다음 명령어를 사용하여 'grpc-bookstore' 서비스에 클라이언트 요청을 수행합니다.

      kubectl exec grpc -ti -- python3 bookstore_client.py \
        --host grpc-bookstore.default.svc.cluster.local --port=80

      이 명령어는 클러스터에서 내부적으로 bookstore_client.py 스크립트를 실행하여 호스트 이름 grpc-bookstore.default.svc.cluster.local의 'grpc-bookstore' 서비스에 gRPC 요청을 수행합니다.

      모두 제대로 작동하면 다음과 같은 형식으로 응답이 표시됩니다.

      ListShelves: shelves {
        id: 1
        theme: "Fiction"
      }
      shelves {
        id: 2
        theme: "Fantasy"
      }

Endpoints 구성

백엔드 서비스의 노출 영역과 모든 인증 요구사항을 설명하는 gRPC API 사양이 있어야 합니다.

gRPC API 사양의 이름 필드 설정 정보

gRPC API 사양의 name 필드에서 Cloud Run for Anthos 서비스에 액세스하는 데 사용할 Endpoints 서비스 이름을 지정합니다. Endpoints 서비스 이름은 도메인 이름 형식입니다.

API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

Endpoints 서비스 이름은 도메인 이름에 해당하므로 이름은 다음 규칙을 따라야 합니다.

• 소문자, 숫자, 마침표 또는 대시만 포함해야 합니다.
• 대시로 시작해서는 안 됩니다.
• 밑줄을 포함해서는 안 됩니다.

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

grpc-boostore-api.endpoints.ESP_PROJECT_ID.cloud.goog

gRPC API 사양 만들기

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

1. my-anthos-grpc와 같이 gRPC API 사양에 대한 새 디렉터리를 만듭니다. 그런 다음 해당 디렉터리로 지속적 배포합니다.

2. gRPC 클라이언트 코드가 새 디렉터리에 호스팅되는 git 저장소를 클론합니다.

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

3. 작업 디렉터리를 변경합니다.

   cd python-docs-samples/endpoints/bookstore-grpc/

   이 디렉터리에는 bookstore.proto 파일이 포함되어 있습니다. 이 파일은 Bookstore 서비스의 API를 정의합니다.

4. 서비스 .proto 파일에서 독립적인 protobuf 설명어 파일을 만듭니다.

   1. 작업 디렉터리 아래에 generated_pb2 디렉터리를 만듭니다.

   2. 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를 변경합니다.

5. 현재 작업 디렉터리(bookstore.proto가 포함된 디렉터리)에서 api_config_anthos.yaml 파일을 수정하여 다음 콘텐츠를 파일에 추가합니다.

   type: google.api.Service
   config_version: 3
   #
   # Name of the service configuration.
   #
   name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
   #
   # API title to appear in the user interface (Google Cloud console).
   #
   title: Bookstore gRPC API In Cloud Run Anthors
   apis:
   - name: endpoints.examples.bookstore.Bookstore
   #
   # Create a DNS record to map your service name to IP address
   #
   endpoints:
     - name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
       target: IP_ADDRESS
   #
   # Specify the backend address to route to
   #
   backend:
     rules:
       - selector: "*"
         address: grpc://GRPC_SERVICE.default.svc.cluster.local
         disable_auth: true
   #
   # API usage restrictions.
   #
   usage:
     rules:
     # ListShelves methods can be called without an API Key.
     - selector: endpoints.examples.bookstore.Bookstore.ListShelves
       allow_unregistered_calls: true

   들여쓰기 간격은 yaml 형식에서 중요합니다.

6. name 필드에서 Cloud Run for Anthos 서비스에 액세스하는 데 사용하는 Endpoints API의 도메인 이름을 다음 형식으로 지정합니다.

   API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

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

   grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog

7. endpoints 섹션은 cloud.goog 도메인의 Endpoints 서비스에 DNS 항목을 다음 형식으로 등록합니다.

   endpoints:
     - name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
       target: IP_ADDRESS

   IP_ADDRESS는 클러스터에 대한 istio-ingress 서비스의 IP입니다. 이 IP 주소를 확인하려면 다음 단계를 따르세요.

   1. Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

      Google Kubernetes Engine으로 이동

   2. 서비스 목록을 표시하려면 왼쪽 탐색 패널에서 서비스 및 인그레스를 클릭합니다.

   3. 클러스터 버전이 1.15.3-gke.19 이상, 1.14.3-gke.12 이상 또는 1.13.10-gke.8 이상인 경우 istio-ingress 서비스까지 아래로 스크롤합니다. 다른 모든 클러스터 버전의 경우 istio-ingressgateway 서비스까지 아래로 스크롤합니다.

   4. 포트 설정이 없는 경우 부하 분산기 옆에 표시된 외부 IP 주소를 복사합니다. 예를 들어 IP가 XX.XXX.XX.XXX:15020이면 :15020를 생략합니다. 다른 IP 주소가 표시된 경우 무시합니다.

8. backend 섹션의 address 필드는 proto 스키마가 grpc://인 Cloud Run 'grpc-bookstore'서비스의 내부 DNS 이름을 지정하고이 서비스에 대한 인증을 사용 중지합니다.

   address: grpc://GRPC_SERVICE.default.svc.cluster.local
   disable_auth: true

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

   address: grpc://grpc-bookstore.default.svc.cluster.local
   disable_auth: true

   이는 ESPv2에서 Cloud Run for Anthos 서비스 호출이 클러스터 내에서 내부 호출로 이루어지므로 인증이 필요하지 않기 때문에 필요합니다.

9. api_config_authos.yaml 파일에서 title 속성 값은 다음과 같습니다.

   title: Bookstore gRPC API In Cloud Run Anthos

   구성을 배포하면 title 속성 값이 Endpoints 서비스 이름이 됩니다.

10. gRPC API 문서 저장

Endpoints에 필요한 OpenAPI 문서 필드에 대한 자세한 내용은 Endpoints 구성을 참조하세요.

Endpoints 구성 배포

Endpoints 구성을 배포하려면 gcloud endpoints services deploy 명령어를 사용합니다. 이 명령어는 Service Management를 사용하여 관리형 서비스를 만듭니다.

Endpoints 구성을 배포하려면 다음 안내를 따르세요.

1. gRPC 문서가 포함된 디렉터리에 있는지 확인합니다.

2. 구성을 업로드하고 관리형 서비스를 만듭니다.

   gcloud endpoints services deploy api_descriptor.pb api_config_anthos.yaml \ 
     --project ESP_PROJECT_ID

   그러면 api_config_anthos.yaml 파일의 name 필드에 지정한 이름으로 새 Endpoints 서비스가 생성됩니다. Endpoints 서비스는 OpenAPI 문서에 따라 구성됩니다.

   Endpoints 서비스를 만들고 구성 할 때 Service Management는 터미널에 정보를 출력합니다. 배포가 완료되면 다음과 유사한 메시지가 표시됩니다.

   Service Configuration [CONFIG_ID] uploaded for service [API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog]

   CONFIG_ID는 배포 시 만들어진 고유한 Endpoints 서비스 구성 ID입니다. 예를 들면 다음과 같습니다.

   Service Configuration [2019-02-01r0] uploaded for service [grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog] 

   서비스 구성 ID는 날짜 스탬프 뒤에 버전 번호가 있는 형태입니다. 당일에 api_config_anthos.yaml을 다시 배포하면 서비스 구성 ID에서 버전 번호가 증가합니다. Google Cloud 콘솔의 Endpoints > 서비스 페이지에서 서비스 구성 및 배포 기록을 확인할 수 있습니다.

   오류 메시지가 나타나면 Endpoints 구성 배포 문제 해결을 참조하세요.

필수 서비스 확인

대부분의 경우 gcloud endpoints services deploy 명령어를 사용하여 이러한 필수 서비스를 사용 설정할 수 있습니다. 하지만 다음과 같은 경우에는 gcloud 명령어가 성공적으로 완료되더라도 필수 서비스가 사용 설정되지 않습니다.

• Terraform과 같은 타사 애플리케이션을 사용하고 이러한 서비스를 포함하지 않은 경우

• 이러한 서비스가 명시적으로 중지된 기존 Google Cloud 프로젝트에 Endpoints 구성을 배포한 경우

다음 명령어를 사용하여 필수 서비스가 사용 설정되어 있는지 확인합니다.

gcloud services list

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

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

Endpoints 서비스도 사용 설정해야 합니다.

gcloud services enable ENDPOINTS_SERVICE_NAME

ENDPOINTS_SERVICE_NAME을 확인하려면 다음 중 하나를 수행합니다.

• Endpoints 구성을 배포한 후 Cloud 콘솔의 Endpoints 페이지로 이동합니다. 가능한 ENDPOINTS_SERVICE_NAME 목록이 서비스 이름 열 아래에 표시됩니다.

• OpenAPI의 경우 ENDPOINTS_SERVICE_NAME은 OpenAPI 사양의 host 필드에 지정한 항목입니다. gRPC의 경우 ENDPOINTS_SERVICE_NAME은 gRPC 엔드포인트 구성의 name 필드에 지정한 항목입니다.

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

새 ESPv2 Knative serving 이미지 빌드

Endpoints 서비스 구성을 새 ESPv2 Docker 이미지에 빌드합니다. 이 이미지를 만든 후 클러스터에 배포할 수 있습니다.

새 ESPv2 Docker 이미지에 서비스 구성을 빌드하려면 다음 단계를 따르세요.

1. gcloud CLI가 설치된 로컬 머신에 이 스크립트를 다운로드하고 다음과 같이 실행합니다.

   chmod +x gcloud_build_image 
   ./gcloud_build_image -s API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog \ 
   -c CONFIG_ID -p ESP_PROJECT_ID

   이 스크립트는 gcloud 명령어를 사용하여 서비스 구성을 다운로드하고 서비스 구성을 새 ESPv2 이미지에 빌드하며 새 이미지를 프로젝트 Container Registry에 업로드합니다. 스크립트는 출력 이미지 이름에 ESP_VERSION으로 표시된 ESPv2의 최신 출시 버전을 자동으로 사용합니다. 출력 이미지가 다음으로 업로드됩니다.

   gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID

ESPv2 Knative serving 이미지 배포

ESPv2 Knative serving 서비스 이미지를 클러스터에 배포합니다.

1. 새 이미지로 ESPv2 Knative serving 서비스를 배포합니다.

   gcloud run deploy ESP_V2_SERVICE_NAME \ 
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
     --platform gke \
     --use-http2 \
     --project=ESP_PROJECT_ID

   ESP_PROJECT_ID에는 ESPv2 서비스에 사용할 이름을 지정합니다. 이 예시에서는 ESP_V2_SERVICE_NAME을 espv2로 설정합니다.

2. CORS 사용 설정과 같은 ESPv2 시작 옵션을 추가로 사용하도록 Endpoints를 구성하려는 경우 ESPv2_ARGS 환경 변수에서 인수를 전달하면 됩니다.

   gcloud run deploy ESP_V2_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ 
     --platform gke --use-http2 \
     --project ESP_PROJECT_ID

   사용 가능한 옵션 목록과 여러 옵션을 지정하는 방법을 비롯하여 ESPv2_ARGS 환경 변수 설정에 대한 자세한 내용 및 예시는 Extensible Service Proxy V2 플래그를 참조하세요.

ESPv2 Knative serving 서비스에 대한 도메인 매핑 만들기

요청 시 host 헤더를 생략하려면 ESPv2 서비스에 도메인 매핑을 추가합니다.

1. Cloud Run으로 이동

2. 커스텀 도메인 관리를 선택합니다.

3. 매핑 추가를 선택합니다.

4. 드롭 다운에서 서비스 도메인 매핑 추가를 선택합니다.

5. 매핑 추가 팝업의 매핑할 서비스 선택 필드에서 ESPv2 서비스를 선택합니다.

6. 도메인 이름 입력 필드에 Endpoints를 통해 Knative serving 서비스에 액세스하는 데 사용할 도메인 이름을 지정합니다. 예를 들어 다음과 같이 지정합니다.

   API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

   여기서 API_NAME은 Endpoints API의 이름입니다. 이 예시에서는 'hello-api'를 사용할 수 있습니다.

   grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog

7. 계속을 클릭합니다. 매핑 요약이 표시됩니다.

8. 완료를 선택하여 매핑을 저장합니다.

API에 요청 보내기

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

1. api_config_anthos.yaml과 같이 gRPC 문서가 포함된 디렉터리에 있는지 확인합니다.

2. 종속 항목을 설치합니다.

   pip3 install virtualenv
   virtualenv env
   source env/bin/activate
   pip3 install -r requirements.txt

3. 샘플 API로 요청을 전송합니다.

   python3 bookstore_client.py --host API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog --port 80

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

   python3 bookstore_client.py --host grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog --port 80

   모두 제대로 작동하면 다음과 같은 형식으로 응답이 표시됩니다.

   ListShelves: shelves {
     id: 1
     theme: "Fiction"
   }
   shelves {
     id: 2
     theme: "Fantasy"
   }

   • Endpoints > 서비스 페이지에서 API의 활동 그래프를 봅니다.

     Endpoints 서비스 페이지로 이동

     요청이 그래프에 반영되는 데 잠시 시간이 걸릴 수 있습니다.

   • 로그 탐색기 페이지에서 API의 요청 로그를 봅니다.

     로그 탐색기 페이지로 이동

성공 응답을 받지 못하면 응답 오류 문제해결을 참조하세요.

이제 Endpoints에 API를 배포하고 테스트를 마쳤습니다.

HTTPS를 사용하도록 Endpoints API 구성

Google Cloud의 Knative serving에서는 기본적으로 자동 TLS 지원이 사용 중지됩니다. 따라서 이 예시에서는 ESPv2를 통해 Endpoints API에 액세스할 때 HTTP를 사용하여 호출합니다.

HTTPS를 사용하여 요청을 지원하도록 ESPv2를 구성할 수 있습니다. 내부 백엔드 서비스인 'hello'가 아닌 외부 서비스인 ESPv2에서 HTTPS 지원을 구성합니다.

ESPv2에서 HTTPS를 지원하려면 다음을 수행해야 합니다.

1. 도메인을 소유해야 합니다. 도메인이 없다면 Google 또는 다른 도메인 공급업체에서 도메인을 얻을 수 있습니다.

2. ESPv2 서비스에 대한 도메인 매핑을 만들고 도메인 매핑 페이지의 안내에 따라 DNS 레코드를 업데이트합니다.

   Google Domains에서 도메인을 가져온 경우 해당 도메인을 DNS 서버로 사용합니다. 그렇지 않으면 Cloud DNS 또는 원하는 DNS 서버를 사용합니다. Google Domains에서 도메인을 사용하는 것이 가장 쉬운 방법입니다.

3. Endpoints OpenAPI 사양:

   1. *.cloud.goog 대신 도메인을 참조하도록 name 필드를 설정합니다.

   2. endpoints 태그와 두 개의 하위 속성을 삭제합니다.

자세한 안내 및 가이드는 HTTPS 및 자동 TLS 인증서 사용 설정을 참조하세요.

API 활동 추적

1. Google Cloud 콘솔의 Endpoints > 서비스 페이지에서 API의 활동 그래프를 봅니다.

   Endpoints 활동 그래프 보기

   요청이 그래프에 반영되는 데 잠시 시간이 걸릴 수 있습니다.

2. 로그 탐색기 페이지에서 API의 요청 로그를 봅니다.

   Endpoints 요청 로그 보기

API의 개발자 포털 만들기

Cloud Endpoints 포털을 사용하여 샘플 API와 상호작용하는 데 사용할 수 있는 웹사이트인 개발자 포털을 만들 수 있습니다. 자세한 내용은 Cloud Endpoints 포털 개요를 참조하세요.