로컬로 또는 다른 플랫폼에서 Extensible Service Proxy 실행

OpenAPI | gRPC

이 페이지에서는 로컬 머신, Amazon Web Services(AWS)와 같은 다른 클라우드 제공업체 또는 Google Cloud에 없는 Kubernetes 클러스터에서 Extensible Service Proxy(ESP) 인스턴스를 구성하고 실행하는 방법을 설명합니다.

Linux나 macOS 컴퓨터 또는 가상 머신(VM)에서 ESP를 실행할 수 있습니다. Microsoft Windows는 지원되지 않습니다. 애플리케이션과 ESP를 동일한 호스트 또는 다른 호스트에 배포할 수 있습니다. ESP 로컬 인스턴스를 호스팅하면 다음을 수행할 수 있습니다.

프로덕션 플랫폼에 배포하기 전에 ESP를 사용해봅니다.
보안 설정이 구성되어 올바르게 작동하고 측정항목과 로그가 예상대로 Endpoints > 서비스 페이지에 나타나는지 확인합니다.

기본 요건

이 페이지에서는 먼저 사용자가 다음을 수행했다고 가정합니다.

ESP 컨테이너를 로컬로 또는 VM에 배포하는 경우 Docker가 설치되어 있어야 합니다. 자세한 내용은 Docker 설치를 참조하세요.
ESP를 실행하는 호스트에 연결할 수 있는 호스트에 또는 로컬로 API가 배포되어 있어야 합니다.
API에 대한 관리형 서비스를 만들 수 있도록 Cloud Endpoints를 구성하고 구성을 배포했습니다.

ESP로 테스트하기 위해 API가 필요한 경우 선택사항: 샘플 API 사용 섹션에서 샘플 코드를 구성 및 배포할 수 있습니다. API를 이미 구성하고 배포한 경우 서비스 계정 만들기로 건너뛰세요.

선택사항: 샘플 API 사용

이 섹션에서는 Endpoints용 getting-started Python 버전 샘플을 로컬로 구성 및 배포하는 방법을 단계별로 설명합니다. ESP로 테스트하기 위한 API가 없는 경우에만 이 섹션의 단계를 수행하세요.

Cloud Endpoints getting-started 샘플은 다른 언어로도 제공됩니다. 원하는 언어로 된 getting-started 샘플의 GitHub 위치에 대해서는 샘플 페이지를 참조하세요. 로컬에서 실행하려면 샘플 README.md 파일의 안내를 따르고 이 섹션의 안내를 따라 Endpoints를 구성하고 Endpoints 구성을 배포합니다.

필요한 소프트웨어 받기

Python 개발 환경을 아직 설정하지 않은 경우 Python 개발 환경 설정의 안내를 참조하세요. 다음이 설치되어 있어야 합니다.

샘플 코드 가져오기

샘플 앱 저장소를 로컬 머신에 클론합니다.

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

샘플 코드가 있는 디렉토리로 변경합니다.
```
cd python-docs-samples/endpoints/getting-started
```

Endpoints 구성

샘플 코드 디렉터리에서 openapi.yaml 구성 파일을 엽니다.

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

host 필드에서 YOUR-PROJECT-ID를 Google Cloud 프로젝트 ID로 바꿉니다.
중요: 이 프로젝트는 서비스 계정 만들기에서 선택하는 프로젝트와 같아야 합니다.
openapi.yaml 파일을 저장합니다.

Endpoints 구성 배포

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

gcloud CLI 업데이트
```
gcloud components update
```
gcloud CLI(gcloud)에 Google Cloud의 데이터 및 서비스에 액세스할 수 있는 권한이 있는지 확인합니다.
```
gcloud auth login
```
새 브라우저 탭이 열리면 계정을 선택합니다.
기본 프로젝트를 프로젝트 ID로 설정합니다.
```
gcloud config set project YOUR-PROJECT-ID
```
YOUR-PROJECT-ID를 openapi.yaml 파일에서 지정한 Google Cloud 프로젝트의 프로젝트 ID로 바꿉니다.

구성을 배포합니다.

gcloud endpoints services deploy openapi.yaml

Service Management는 openapi.yaml 파일의 host 필드에서 지정한 텍스트를 사용하여 이름이 echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog인 새 Endpoints 서비스(존재하지 않는 경우)를 만든 후 OpenAPI 구성 파일에 따라 서비스를 구성합니다.

서비스 생성 및 구성 시 Service Management는 터미널에 정보를 출력합니다. openapi.yaml 파일의 경로에 API 키가 필요하지 않다는 경고는 무시해도 됩니다. 성공적으로 완료되면 서비스 구성 ID와 서비스 이름을 대괄호 안에 표시하는 다음과 같은 줄이 표시됩니다.

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

앞의 예시에서 2017-02-13r0은 서비스 구성 ID이고 echo-api.endpoints.example-project-12345.cloud.goog는 서비스 이름입니다.

로컬 서버 시작

virtualenv를 만들어 활성화하고 애플리케이션 종속 항목을 설치합니다.
```
virtualenv env
source env/bin/activate
pip install -r requirements.txt
```
서버를 시작합니다.
```
python main.py
```

다른 터미널 창을 열고 curl을 사용하여 요청을 보냅니다.

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

API가 받은 메시지를 되풀이하고 다음과 같이 응답합니다.

{
"message": "hello world"
}

서비스 계정 만들기

API 관리 기능을 제공하기 위해 ESP 및 ESPv2에는 서비스 인프라의 서비스가 필요합니다. 이러한 서비스를 호출하려면 ESP와 ESPv2가 액세스 토큰을 사용해야 합니다. GKE 또는 Compute Engine과 같은 Google Cloud 환경에 ESP 또는 ESPv2를 배포하면 ESP와 ESPv2가 Google Cloud 메타데이터 서비스를 통해 액세스 토큰을 얻습니다.

로컬 데스크톱, 온프레미스 Kubernetes 클러스터, 기타 클라우드 제공업체와 같은 Google Cloud 환경이 아닌 환경에 ESP 또는 ESPv2를 배포하는 경우 비공개 키가 포함되어 있는 서비스 계정 JSON 파일을 제공해야 합니다. ESP와 ESPv2는 서비스 계정을 사용해 액세스 토큰을 생성하여 API 관리에 필요한 서비스를 호출합니다.

Google Cloud Console 또는 Google Cloud CLI를 사용하여 서비스 계정과 비공개 키 파일을 만들 수 있습니다.

콘솔

Google Cloud Console에서 서비스 계정 페이지를 엽니다.
서비스 계정 페이지로 이동
프로젝트 선택을 클릭합니다.
API가 생성된 프로젝트를 선택하고 열기를 클릭합니다.
+ 서비스 계정 만들기를 클릭합니다.
서비스 계정 이름 필드에 서비스 계정 이름을 입력합니다.
만들기를 클릭합니다.
계속을 클릭합니다.
완료를 클릭합니다.
새로 만든 서비스 계정의 이메일 주소를 클릭합니다.
키를 클릭합니다.
키 추가를 클릭한 후 새 키 만들기를 클릭합니다.
만들기를 클릭합니다. JSON 키 파일이 컴퓨터에 다운로드됩니다.

키 파일은 서비스 계정으로 인증하는 데 사용될 수 있으므로 키 파일을 안전하게 저장해야 합니다. 원하는 경우 이 파일을 이동하고 이름을 변경할 수 있습니다.
닫기를 클릭합니다.

`gcloud`

다음을 입력하여 Google Cloud 프로젝트의 프로젝트 ID를 표시합니다.
```
gcloud projects list
```
다음 명령어에서 PROJECT_ID를 바꿔 기본 프로젝트를 API가 있는 프로젝트로 설정합니다.
```
gcloud config set project PROJECT_ID
```
중요: API가 있는 동일한 프로젝트에서 서비스 계정을 만들어야 합니다.
Google Cloud CLI(gcloud)에 Google Cloud의 데이터 및 서비스에 액세스할 수 있는 권한이 있는지 확인합니다.
```
gcloud auth login
```
계정이 2개 이상이면 API가 포함된 Google Cloud 프로젝트에 있는 계정을 선택해야 합니다. gcloud auth list를 실행하면 선택한 계정이 프로젝트의 활성 계정으로 표시됩니다.
서비스 계정을 만들려면 다음 명령어를 실행합니다. 여기서 SERVICE_ACCOUNT_NAME과 My Service Account는 사용하려는 이름과 표시 이름으로 바꿉니다.
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"
```
이 명령어는 서비스 계정의 이메일 주소를 다음 형식으로 할당합니다.

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

다음 명령어에 이 이메일 주소가 필요합니다.

서비스 계정 키 파일을 만듭니다.

gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

필수 IAM 역할 추가

이 섹션에서는 ESP 및 ESPv2에 사용되는 IAM 리소스와 연결된 서비스 계정이 이러한 리소스에 액세스하는 데 필요한 IAM 역할을 설명합니다.

엔드포인트 서비스 구성

ESP 및 ESPv2는 엔드포인트 서비스 구성을 사용하는 Service Control을 호출합니다. 엔드포인트 서비스 구성은 IAM 리소스입니다. ESP 및 ESPv2가 여기에 액세스하려면 서비스 컨트롤러 역할이 필요합니다.

IAM 역할은 프로젝트가 아닌 엔드포인트 서비스 구성에 있습니다. 한 프로젝트에 여러 엔드포인트 서비스 구성이 포함될 수 있습니다.

다음 gcloud 명령어를 사용하여 엔드포인트 서비스 구성의 연결된 서비스 계정에 역할을 추가합니다.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

여기서
* SERVICE_NAME은 엔드포인트 서비스 이름입니다.
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com은 연결된 서비스 계정입니다.

Cloud Trace

ESP 및 ESPv2는 Cloud Trace 서비스를 호출하여 Trace를 프로젝트로 내보냅니다. 이 프로젝트를 trace 프로젝트라고 부릅니다. ESP에서 trace 프로젝트와 엔드포인트 서비스 구성을 소유하는 프로젝트는 동일합니다. ESPv2에서 trace 프로젝트는 --tracing_project_id 플래그로 지정될 수 있으며, 기본적으로 배포 프로젝트로 지정됩니다.

ESP 및 ESPv2에 Cloud Trace를 사용 설정하려면 Cloud Trace 에이전트 역할이 필요합니다.

다음 gcloud 명령어를 사용하여 연결 서비스 계정에 역할을 추가합니다.

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

여기서
* TRACING_PROJECT_ID는 trace 프로젝트 ID입니다.
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com은 연결 서비스 계정입니다. 자세한 내용은 역할 및 권한이란 무엇인가요?를 참조하세요.

명령어에 대한 자세한 내용은 gcloud iam service-accounts를 참조하세요.

컨테이너에서 ESP 실행

이 섹션에서는 ESP 컨테이너를 배포하는 방법을 설명합니다. 사용하는 절차는 ESP 컨테이너를 배포하는 위치에 따라 달라집니다.

ESP를 Docker 컨테이너에서 로컬로 또는 다른 플랫폼에서 실행
Kubernetes 클러스터의 컨테이너에서 ESP 실행

다음 예시에서 ESP 옵션 --http_port는 gRPC 서비스에 HTTP/JSON 트랜스코딩을 구성한 경우에만 작동합니다. 자세한 내용은 gRPC로 HTTP/JSON 트랜스코딩을 참조하세요.

ESP를 Docker 컨테이너에서 로컬로 또는 다른 플랫폼에서 실행

서비스 계정의 비공개 키가 포함된 JSON 파일의 이름을 service-account-creds.json으로 바꾸고 $HOME/Downloads/에 복사합니다(다른 디렉터리에 다운로드된 경우). 이렇게 하면 전체 경로 이름이 다음 docker run 명령어의 --service_account_key 값과 일치합니다.
다음 docker run 명령어에서 YOUR_SERVICE_NAME을 서비스 이름으로 바꿉니다.

Linux

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://localhost:8080 \
    --service_account_key=/esp/service-account-creds.json

mac OS

macOS에서는 Docker --net="host" 옵션이 작동하지 않습니다. 대신 --net="host"를 --publish 8082:8082로 바꿔 호스트에서 컨테이너로 명시적인 포트 매핑을 수행해야 합니다. 또한 localhost를 특수 macOS 전용 DNS 이름인 docker.for.mac.localhost로 바꿔야 합니다. 자세한 내용은 Docker 문서의 사용 사례 및 해결 방법을 참조하세요.

sudo docker run \
  --detach \
  --name="esp" \
  --publish=8082:8082 \
  --volume=$HOME/Downloads:/esp \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --http2_port=8083 \
  --backend=grpc://docker.for.mac.localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

다른 플랫폼

sudo docker run \
  --detach \
  --name="esp" \
  --net="host" \
  --volume=$HOME/Downloads:/esp \
  --publish=8082 \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --http2_port=8083 \
  --backend=grpc://IP_Address:PORT \
  --service_account_key=/esp/service-account-creds.json

다음 표에는 앞의 명령어에 사용된 Docker 옵션이 설명되어 있습니다. 예에서 사용된 ESP 옵션에 대한 자세한 내용은 ESP 시작 옵션을 참조하세요.

옵션	설명
`--detach`	이 Docker 옵션은 분리 모드에서 컨테이너를 시작하므로, 컨테이너가 백그라운드에서 실행됩니다.
`--name="esp"`	이 Docker 옵션에서는 컨테이너에 쉽게 액세스할 수 있는 이름을 제공합니다. 예를 들어 컨테이너의 로그를 보려면 `docker logs esp`를 실행하면 됩니다.
`--net="host"`	이 Docker 옵션은 Docker 컨테이너가 호스트 머신과 동일한 네트워크 구성을 사용하므로 호스트 머신의 localhost를 호출할 수 있음을 나타냅니다. macOS에서 로컬로 ESP를 실행하는 데는 이 옵션이 작동하지 않습니다.
`--publish=8082:8082`	macOS에서 ESP를 로컬로 실행하려면 `--net="host"` 대신 이 Docker 옵션을 사용하여 포트를 명시적으로 호스트에서 컨테이너로 매핑합니다.
`--volume=` `$HOME/Downloads:/esp`	이 Docker 옵션은 로컬 `$HOME/Downloads` 디렉터리를 컨테이너의 `/esp` 디렉터리에 매핑합니다. 이 매핑은 `--service_account_key` ESP 옵션에 사용됩니다.

Kubernetes 클러스터의 컨테이너에서 ESP 실행

이 섹션에서는 Google Cloud에 없는 Kubernetes 클러스터에 ESP를 배포하는 방법을 설명합니다.

API가 Endpoints에서 관리되도록 하려면 API 컨테이너와 동일한 Kubernetes pod에 ESP 컨테이너를 배포합니다. ESP 및 API를 실행하는 pod 집합은 app: my-api와 같은 라벨 선택기를 사용하여 Kubernetes 서비스 아래에 그룹화됩니다. Kubernetes 서비스는 클라이언트 요청 부하를 프록시 포트로 분산하는 액세스 정책을 지정합니다.

서비스 계정의 비공개 키가 포함된 JSON 파일의 이름을 service-account-creds.json으로 바꾸고 $HOME/Downloads/에 복사합니다(다른 디렉터리에 다운로드된 경우). 그러면 전체 경로 이름이 다음 단계의 명령어와 일치하게 됩니다.
다음 명령어를 실행하여 Kubernetes 보안 비밀을 만들고 보안 비밀을 Kubernetes 볼륨으로 마운트합니다.
```
kubectl create secret generic service-account-creds \
  --from-file=$HOME/Downloads/service-account-creds.json
```
성공하면 secret "service-account-creds" created 메시지가 표시됩니다.

Kubernetes 구성 파일에서 다음을 추가합니다. 여기에서 YOUR_APP_NAME은 API 이름으로 바꾸고 YOUR_SERVICE_NAME은 서비스 이름으로 바꿉니다.

spec:
replicas: 1
template:
  metadata:
    labels:
      app: "YOUR_APP_NAME"
  spec:
    volumes:
      - name: service-account-creds
        secret:
          secretName: service-account-creds
          containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:1
        args: [
          "--http_port=8082",
          "--http2_port=8083",
          "--backend=grpc://127.0.0.1:8081",
          "--service=YOUR_SERVICE_NAME",
          "--rollout_strategy=managed",
          "--service_account_key=/etc/nginx/creds/service-account-creds.json"
        ]
        ports:
          - containerPort: 8080
        volumeMounts:
          - mountPath: /etc/nginx/creds
            name: service-account-creds
            readOnly: true

예에서 사용된 ESP 옵션에 대한 자세한 내용은 ESP 시작 옵션을 참조하세요.

Kubernetes에 ESP를 배포합니다. YOUR_CONFIGURATION_FILE을 Kubernetes 구성 파일의 이름으로 바꿉니다.
```
kubectl apply -f YOUR_CONFIGURATION_FILE
```

요청 보내기

서비스 계정 파일이 올바르고 포트가 올바르게 매핑되었는지 확인하기 위해 API에 일부 요청을 보내고 요청이 ESP를 통과하는지 확인합니다. 다음을 실행하여 ESP 로그를 확인할 수 있습니다.

sudo docker logs esp

다음 예시는 샘플 API에 요청을 보냅니다. 이 샘플 API를 사용하지 않는 경우 유사한 테스트를 실행하는 것이 좋습니다.

포트 8082에서 요청을 수신하도록 ESP 컨테이너를 구성했습니다. http://localhost:8080에서 직접 서버에 요청을 보내면 요청은 ESP를 우회합니다. 예를 들면 다음과 같습니다.

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

응답:

  {
    "message": "hello world"
  }

ESP를 통과하는 요청을 http://localhost:8082에 보내고 API 키를 보내지 않으면 ESP가 요청을 거부합니다. 예를 들면 다음과 같습니다.

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo

응답:

  {
   "code": 16,
   "message": "Method doesn't allow unregistered callers (callers without
    established identity). Please use API Key or other form of API consumer
    identity to call this API.",
   "details": [
    {
     "@type": "type.googleapis.com/google.rpc.DebugInfo",
     "stackEntries": [],
     "detail": "service_control"
    }
   ]
  }

API 키로 API를 테스트하려면 다음 안내를 따르세요.

API 사용자 인증 정보 페이지에서 API 키를 만듭니다.

사용자 인증 정보 페이지로 이동
사용자 인증 정보 만들기를 클릭하고 API 키를 선택합니다.
키를 복사한 후 다음 환경 변수 문에 붙여 넣습니다.
```
export KEY=AIza...
```

키와 함께 요청을 보냅니다.

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo?key=$KEY

성공적인 응답이 표시됩니다.

{
  "message": "hello world"
}

삭제

docker 도구를 사용하여 esp Docker 컨테이너를 종료 및 제거합니다.

    sudo docker stop esp
    sudo docker rm esp

배포된 서비스 구성을 삭제하려면 API 및 API 인스턴스 삭제를 참조하세요.

다음 단계

ESP에 SSL 지원을 추가하는 방법 알아보기