API 백엔드 배포

OpenAPI | gRPC

이 페이지에서는 API의 백엔드 코드와 확장 가능 서비스 프록시(ESP)를 Google Kubernetes Engine, Compute Engine, App Engine 가변형 환경에 배포하는 방법을 설명합니다.

배포 단계는 API를 호스팅하는 플랫폼에 따라 다르지만, ESP에 서비스 이름과 배포된 최신 Cloud Endpoints 서비스 구성을 사용하도록 ESP를 구성하는 옵션을 제공하는 단계는 항상 있습니다. ESP는 이 정보를 사용하여 API의 Endpoints 구성을 가져올 수 있습니다. 이 구성을 통해 Endpoints에서 API를 관리할 수 있게 ESP가 요청과 응답을 프록시할 수 있습니다.

참고: Extensible Service Proxy V2 (ESPv2)는 GKE와 Kubernetes에도 배포될 수 있습니다. ESPv2는 App Engine 가변형 환경을 지원하지 않습니다.

기본 요건

이 페이지에서는 먼저 사용자가 다음 작업을 완료했다고 가정합니다.

• Google Cloud 프로젝트를 만들었습니다.
• 엔드포인트 구성
• Endpoints 구성을 배포했습니다.

배포 준비

App Engine

다음 단계에 설명된 간단한 구성 단계를 추가하면 Endpoints에서 관리하도록 API를 배포하는 것이 App Engine 가변형 환경에 애플리케이션을 배포하는 것과 같아집니다. App Engine 문서에 따라 다음을 수행하세요.

• 구성 파일을 정리합니다.
• app.yaml 구성 파일을 만듭니다.
• 애플리케이션이 마이크로서비스를 기반으로 하는 경우 각 서비스의 app.yaml 파일을 구성하는 방법에 대한 자세한 내용은 여러 서비스 애플리케이션 배포 문서를 참조하세요.

gcloud app deploy 명령어를 사용하여 App Engine에 API를 배포합니다. 이 명령어는 Container Builder 서비스를 사용하여 컨테이너 이미지를 자동으로 빌드한 다음 이 이미지를 App Engine 가변형 환경에 배포합니다.

배포하기 전에

• Google Cloud 프로젝트의 소유자가 App Engine 애플리케이션을 만들어야 합니다.
• 사용자 계정에 필요한 권한이 있는지 확인합니다.

Compute Engine

Endpoints에서 API를 관리하려면 ESP와 API의 백엔드 서버 코드를 설치하고 구성해야 합니다. Container Registry에서 무료로 사용할 수 있는 ESP Docker 이미지를 실행할 수 있도록 Compute Engine VM 인스턴스에 Docker를 설치해야 합니다.

배포하기 전에

다음은 API와 ESP를 Compute Engine에 배포하기 위해 수행해야 하는 단계를 간략하게 요약한 것입니다. 대개 Compute Engine에서 백엔드 서버 코드를 실행하기 위해 일반적으로 수행하는 모든 단계를 수행합니다.

1. VM 인스턴스를 만들고 구성하고 시작합니다. Compute Engine 문서를 참조하세요.
2. VM 인스턴스에 Docker Enterprise Edition(EE) 또는 Docker Community Edition(CE)을 설치합니다. Docker 설치를 참조하세요.
3. 백엔드 서버 코드용 Docker 컨테이너를 만듭니다. Cloud Build 문서를 참조하세요.
4. Container Registry 또는 다른 레지스트리로 컨테이너를 푸시합니다.
5. 다음 작업이 가능한지 확인합니다.
   • VM 인스턴스에 연결합니다.
   • Docker 이미지를 실행하여 VM 인스턴스에서 백엔드 서버를 시작합니다. Docker 실행 참조를 확인하세요.
   • API에 요청을 보냅니다.

GKE

Google Cloud Console에서 클러스터를 만들 때 기본적으로 클러스터 서비스 계정에 부여된 OAuth 범위에는 Endpoints에서 필요한 범위가 포함됩니다.

• Service Control: 사용 설정됨
• Service Management: 읽기 전용

gcloud container clusters create 명령어나 타사 구성 파일을 사용하여 클러스터를 만들 때 다음 범위를 지정해야 합니다.

• "https://www.googleapis.com/auth/servicecontrol"
• "https://www.googleapis.com/auth/service.management.readonly"

자세한 내용은 액세스 범위란 무엇인가요?를 참조하세요.

배포하기 전에

배포 매니페스트 파일에 작은 섹션을 추가하면 컨테이너 클러스터에서 컨테이너형 애플리케이션과 함께 ESP Docker 이미지를 실행할 수 있습니다. 다음은 API와 ESP를 GKE에 배포하기 전에 수행해야 하는 단계를 간략하게 요약한 것입니다. 대개 GKE에서 백엔드 서버 코드를 실행하기 위해 일반적으로 수행하는 모든 단계를 수행합니다.

1. 컨테이너식 애플리케이션을 컨테이너 클러스터에 배포합니다. GKE 문서에 설명되어 있는 일반적인 단계는 다음과 같습니다.
   1. 앱을 Docker 이미지로 패키지화합니다.
   2. 레지스트리에 이미지를 업로드합니다.
   3. 컨테이너 클러스터를 만듭니다.
   4. 클러스터에 앱을 배포합니다.
   5. 인터넷에 앱을 노출합니다.
2. 다음 작업이 가능한지 확인합니다.
   • API의 서버를 시작합니다.
   • API에 요청을 보냅니다.

API 및 ESP 배포

App Engine

App Engine에 API와 ESP를 배포하려면 다음 안내를 따르세요.

1. API의 서비스 이름을 가져옵니다. 이 이름은 OpenAPI 문서의 host 필드에 지정한 이름입니다.
2. app.yaml 파일을 수정하여 서비스 이름을 포함하는 endpoints_api_service 섹션을 추가합니다. 가이드의 app.yaml 파일을 모델로 사용할 수 있습니다.
   자바

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Python

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Go

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   PHP

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
     # previously run the deploy command, you can list your existing configuration
     # ids using the 'configs list' command as follows:
     #
     #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
     #
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ruby

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   NodeJS

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   ENDPOINTS-SERVICE-NAME을 API의 서비스 이름으로 바꿉니다. 예를 들면 다음과 같습니다.

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     

   rollout_strategy: managed 옵션은 배포된 최신 서비스 구성을 사용하도록 ESP를 구성합니다. 이 옵션을 지정하면 새 서비스 구성을 배포하고 최대 5분 후 ESP가 변경사항을 감지하고 자동으로 사용하기 시작합니다. ESP에 사용할 특정 구성 ID 대신 이 옵션을 지정하는 것이 좋습니다.

   애플리케이션이 마이크로서비스를 기반으로 하는 경우 모든 app.yaml 파일에 endpoints_api_service 섹션을 포함해야 합니다.

3. app.yaml 파일을 저장합니다.
4. App Engine에 백엔드 코드와 ESP를 배포합니다.

   gcloud app deploy
   

app.yaml 파일에 endpoints_api_service 섹션을 추가했기 때문에 gcloud app deploy 명령어는 App Engine 가변형 환경에 별도의 컨테이너로 ESP를 배포하고 구성합니다. 모든 요청 트래픽이 ESP를 통해 라우팅되며, ESP는 백엔드 서버 코드를 실행하는 컨테이너의 요청과 응답을 프록시합니다.

특정 구성 ID를 사용하도록 ESP를 구성하려면 다음 안내를 따르세요.

1. app.yaml 파일의 endpoints_api_service 섹션에서 config_id 필드를 추가하고 이를 특정 구성 ID로 설정합니다.
2. rollout_strategy: managed를 삭제하거나 rollout_strategy를 fixed로 설정합니다. fixed 옵션은 ESP가 config_id에 지정된 서비스 구성을 사용하도록 구성합니다.
3. gcloud app deploy 명령어를 사용하여 API와 ESP를 재배포합니다.

업데이트된 서비스 구성을 배포하는 경우 새로운 구성을 사용하기 위해 ESP를 다시 시작해야 하므로, 너무 오래 특정 구성 ID를 사용하도록 ESP를 구성한 상태로 두지 않는 것이 좋습니다.

특정 구성 ID를 삭제하려면 다음 안내를 따르세요.

1. app.yaml 파일에서 config_id 옵션을 삭제합니다.
2. rollout_strategy: managed 옵션을 추가합니다.
3. gcloud app deploy 명령어를 실행합니다.

rollout_strategy: managed 옵션을 사용할 경우 app.yaml 파일에 config_id: YOUR_SERVICE_CONFIG_ID를 포함하지 마세요. 그러면 gcloud app deploy가 실패하고 다음 오류가 발생합니다.

config_id is forbidden when rollout_strategy is set to "managed".

App Engine 가변형 환경에 API를 처음 배포하면 가상 머신(VM)과 기타 인프라가 설정되므로 지연이 발생할 수 있습니다. 자세한 내용은 App Engine 문서의 성공적인 배포 보장을 참조하세요.

Compute Engine

Docker를 사용하는 Compute Engine에 API와 ESP를 배포하려면 다음 안내를 따르세요.

1. VM 인스턴스에 연결합니다. INSTANCE_NAME은 VM 인스턴스의 이름으로 바꿉니다.

   gcloud compute ssh INSTANCE_NAME

2. esp_net이라는 자체 컨테이너 네트워크를 만듭니다.

   sudo docker network create --driver bridge esp_net

3. 백엔드 서버 코드의 이미지 인스턴스를 실행하고 esp_net 컨테이너 네트워크에 연결합니다.

   sudo docker run \
       --detach \
       --name=YOUR_API_CONTAINER_NAME \
       --net=esp_net \
       gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0

   • YOUR_API_CONTAINER_NAME은 컨테이너 이름으로 바꿉니다.
   • YOUR_PROJECT_ID를 이미지를 푸시할 때 사용한 Google Cloud 프로젝트 ID로 바꿉니다.
   • YOUR_IMAGE를 이미지 이름으로 바꿉니다.
4. API의 서비스 이름을 가져옵니다. 이 이름은 OpenAPI 문서의 host 필드에 지정한 이름입니다.
5. ESP Docker 이미지의 인스턴스를 실행합니다.

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --backend=YOUR_API_CONTAINER_NAME:8080

   • SERVICE_NAME은 서비스 이름으로 바꿉니다.
   • YOUR_API_CONTAINER_NAME은 API의 컨테이너 이름으로 바꿉니다.

   --rollout_strategy=managed 옵션은 배포된 최신 서비스 구성을 사용하도록 ESP를 구성합니다. 이 옵션을 지정하면 새 서비스 구성을 배포하고 최대 5분 후 ESP가 변경사항을 감지하고 자동으로 사용하기 시작합니다. ESP에 사용할 특정 구성 ID 대신 이 옵션을 지정하는 것이 좋습니다.

특정 구성 ID를 사용하도록 ESP를 구성하려면 다음 안내를 따르세요.

1. --version 옵션을 포함하고 이를 특정 구성 ID로 설정합니다.
2. --rollout_strategy=managed 옵션을 삭제하거나 --rollout_strategy를 fixed로 설정합니다. fixed 옵션은 ESP가 --version에 지정된 서비스 구성을 사용하도록 구성합니다.
3. docker run 명령어를 다시 실행합니다.

--rollout_strategy=managed와 --version 옵션을 모두 지정하면 ESP가 --version에 지정된 구성으로 시작되지만 그 후에는 관리 모드로 실행되어 최신 구성을 사용하게 됩니다.

업데이트된 서비스 구성을 배포하는 경우 새로운 구성을 사용하기 위해 ESP를 다시 시작해야 하므로, 너무 오래 특정 구성 ID를 사용하도록 ESP를 구성한 상태로 두지 않는 것이 좋습니다.

특정 구성 ID를 삭제하려면 다음 안내를 따르세요.

1. docker run의 ESP 플래그에서 --version 옵션을 삭제합니다.
2. --rollout_strategy=managed 옵션을 추가합니다.
3. docker run 명령어를 실행하여 ESP를 다시 시작합니다.

ESP를 시작할 때 지정할 수 있는 옵션의 전체 목록은 ESP 시작 옵션을 참조하세요.

GKE

GKE에 ESP를 배포하려면 다음 안내를 따르세요.

1. API의 서비스 이름을 가져옵니다. 이 이름은 OpenAPI 문서의 host 필드에 지정한 이름입니다.
2. 배포 매니페스트 파일(deployment.yaml 파일)을 열고 containers 섹션에 다음을 추가합니다.

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed"
     ]

   SERVICE_NAME을 API의 서비스 이름으로 바꿉니다.

   --rollout_strategy=managed" 옵션은 ESP가 배포된 최신 서비스 구성을 사용하도록 구성합니다. 이 옵션을 지정하면 새 서비스 구성을 배포하고 최대 5분 후 ESP가 변경사항을 감지하고 자동으로 사용하기 시작합니다. ESP에 사용할 특정 구성 ID 대신 이 옵션을 지정하는 것이 좋습니다.

3. kubectl create 명령어를 사용하여 Kubernetes 서비스를 시작합니다.

   kubectl create -f deployment.yaml

특정 구성 ID를 사용하도록 ESP를 구성하려면 다음 안내를 따르세요.

1. 배포 매니페스트 파일에 --version 옵션을 추가하고 이를 특정 구성 ID로 설정합니다.
2. --rollout_strategy=managed를 삭제하거나 --rollout_strategy를 fixed로 설정합니다. fixed 옵션은 ESP가 --version에 지정된 서비스 구성을 사용하도록 구성합니다.
3. kubectl create -f deployment.yaml 명령어를 사용하여 Kubernetes 서비스를 시작합니다.

--rollout_strategy=managed와 --version 옵션을 모두 지정하면 ESP가 --version에 지정된 구성으로 시작되지만 그 후에는 관리 모드로 실행되어 최신 구성을 사용하게 됩니다.

업데이트된 서비스 구성을 배포하는 경우 새로운 구성을 사용하기 위해 ESP를 다시 시작해야 하므로, 너무 오래 특정 구성 ID를 사용하도록 ESP를 구성한 상태로 두지 않는 것이 좋습니다.

특정 구성 ID를 삭제하려면 다음 안내를 따르세요.

1. 배포 매니페스트 파일에서 --version 옵션을 삭제합니다.
2. --rollout_strategy=managed를 추가합니다.
3. kubectl create -f deployment.yaml 명령어를 사용하여 Kubernetes 서비스를 시작합니다.

ESP를 시작할 때 지정할 수 있는 옵션의 전체 목록은 ESP 시작 옵션을 참조하세요.

API 활동 추적

ESP와 API 백엔드를 배포한 후에는 curl 또는 Postman과 같은 도구를 사용하여 API에 요청을 보낼 수 있습니다. 성공 응답을 받지 못하면 응답 오류 문제해결을 참조하세요.

요청을 보낸 후 다음을 수행할 수 있습니다.

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

  Endpoints 서비스 페이지로 이동

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

• Cloud Logging 페이지에서 API의 요청 로그를 봅니다.
  

  로그 탐색기 페이지로 이동

다음 단계

• App Engine 가변형 환경 배포 문제해결
• Compute Engine에서 Endpoints 문제해결
• Google Kubernetes Engine에서 Endpoints 문제해결