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

이 페이지에서는 로컬 머신, 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 개발 환경 설정의 안내를 참조하세요. 다음이 설치되어 있어야 합니다.

샘플 코드 가져오기

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

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. 샘플 코드가 있는 디렉토리로 변경합니다.

    cd python-docs-samples/endpoints/getting-started
    

Endpoints 구성

  1. 샘플 코드 디렉터리에서 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"
  2. host 필드에서 YOUR-PROJECT-ID를 Google Cloud 프로젝트 ID로 바꿉니다.

  3. openapi.yaml 파일을 저장합니다.

Endpoints 구성 배포

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

  1. Cloud SDK를 업데이트합니다.

    gcloud components update
    
  2. Cloud SDK(gcloud)에 Google Cloud의 데이터와 서비스에 액세스할 수 있는 권한이 있는지 확인합니다.

    gcloud auth login
    

    새 브라우저 탭이 열리면 계정을 선택합니다.

  3. 기본 프로젝트를 프로젝트 ID로 설정합니다.

    gcloud config set project YOUR-PROJECT-ID
    

    YOUR-PROJECT-IDopenapi.yaml 파일에서 지정한 Google Cloud 프로젝트의 프로젝트 ID로 바꿉니다.

  4. 구성을 배포합니다.

    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는 서비스 이름입니다.

로컬 서버 시작

  1. virtualenv를 만들어 활성화하고 애플리케이션 종속 항목을 설치합니다.

    virtualenv env
    source env/bin/activate
    pip install -r requirements.txt
    
  2. 서버를 시작합니다.

    python main.py
    
  3. 다른 터미널 창을 열고 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 관리에 필요한 서비스를 호출합니다.

Cloud Console 또는 gcloud 명령줄 도구를 사용하여 서비스 계정과 비공개 키 파일을 만들고 서비스 계정에 다음 역할을 할당할 수 있습니다.

Console

  1. Cloud Console에서 서비스 계정 페이지를 엽니다.

    서비스 계정 페이지로 이동

  2. 프로젝트 선택을 클릭합니다.
  3. API가 생성된 프로젝트를 선택하고 열기를 클릭합니다.
  4. + 서비스 계정 만들기를 클릭합니다.
  5. 서비스 계정 이름 필드에 서비스 계정 이름을 입력합니다.
  6. 만들기를 클릭합니다.
  7. 계속을 클릭합니다.
  8. 완료를 클릭합니다.
  9. 새로 만든 서비스 계정을 선택하고 오른쪽의 작업 메뉴를 클릭한 후 키 만들기 메뉴 항목을 클릭합니다.
  10. '비공개 키 만들기' 팝업 패널에서 키 유형을 선택하고 기본 유형인 JSON을 사용합니다.
  11. 만들기를 클릭합니다.

이렇게 하면 서비스 계정이 생성되고 개인 키가 JSON 파일로 다운로드됩니다.

gcloud

  1. 다음을 입력하여 Google Cloud 프로젝트의 프로젝트 ID를 표시합니다.

    gcloud projects list
  2. 다음 명령어에서 PROJECT_ID를 바꿔 기본 프로젝트를 API가 있는 프로젝트로 설정합니다.

    gcloud config set project PROJECT_ID

  3. Cloud SDK(gcloud)에 Google Cloud의 데이터와 서비스에 액세스할 수 있는 권한이 있는지 확인합니다.

    gcloud auth login

    계정이 두 개 이상 있으면 API가 포함된 Google Cloud 프로젝트에 있는 계정을 선택해야 합니다. gcloud auth list를 실행하면 선택한 계정이 프로젝트의 활성 계정으로 표시됩니다.

  4. 서비스 계정을 만들려면 다음 명령어를 실행합니다. 여기서 SERVICE_ACCOUNT_NAMEMy Service Account는 사용하려는 이름과 표시 이름으로 바꿉니다.

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME 
    --display-name "My Service Account"

    이 명령어는 서비스 계정의 이메일 주소를 다음 형식으로 할당합니다.

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

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

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

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

필수 IAM 역할을 추가합니다.

ESP 및 ESPv2 베타에 사용되는 서비스 계정에는 다음 IAM 역할이 필요합니다.

서비스 계정에 서비스 컨트롤러와 Cloud Trace 에이전트 IAM 역할을 추가하려면 다음 안내를 따르세요.

콘솔

  1. Cloud Console에서 서비스 계정을 생성한 프로젝트를 선택합니다.
  2. IAM/Iam 페이지를 엽니다.

    IAM/Iam 페이지로 이동

    . 페이지에 모든 서비스 계정을 포함한 모든 IAM 구성원이 나열됩니다.
  3. 서비스 계정을 선택하고 오른쪽의 수정 핀을 클릭합니다.
  4. 권한 수정 패널이 열립니다.
  5. + 다른 역할 추가를 클릭합니다.
  6. 역할 선택을 클릭하고 서비스 관리 > 서비스 컨트롤러를 선택합니다.
  7. + 다른 역할 추가를 클릭합니다.
  8. 역할 선택을 클릭하고 Cloud Trace > Cloud Trace 에이전트를 선택합니다.
  9. 'Save(저장)'를 클릭합니다.
  10. 이제 IAM 페이지에서 서비스 계정의 역할 열에 서비스 컨트롤러Cloud Trace 에이전트 역할이 표시됩니다.

gcloud

  1. 서비스 컨트롤러 역할을 추가합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/servicemanagement.serviceController
  2. Cloud Trace 에이전트 역할을 추가하여 Cloud Trace를 사용 설정합니다.

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

자세한 내용은 역할 및 권한이란 무엇인가요?를 참조하세요.

See
[`gcloud iam service-accounts`](/sdk/gcloud/reference/iam/service-accounts/){: track-type="tutorial" track-name="internalLink" track-metadata-position="body" }
for more information about the commands.

컨테이너에서 ESP 실행

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

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

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

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

  2. 다음 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 서비스는 클라이언트 요청 부하를 프록시 포트로 분산하는 액세스 정책을 지정합니다.

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

  2. 다음 명령어를 실행하여 Kubernetes 보안 비밀을 만들고 보안 비밀을 Kubernetes 볼륨으로 마운트합니다.

    kubectl create secret generic service-account-creds \
    --from-file=$HOME/Downloads/service-account-creds.json
    

    성공하면 다음 메시지가 표시됩니다. secret "service-account-creds" created

  3. 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 시작 옵션을 참조하세요.

  4. 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를 테스트하려면 다음 안내를 따르세요.

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

    사용자 인증 정보 페이지로 이동

  2. 사용자 인증 정보 만들기를 클릭하고 API 키를 선택합니다.

  3. 키를 복사한 후 다음 환경 변수 문에 붙여 넣습니다.

    export KEY=AIza...
    
  4. 키와 함께 요청을 보냅니다.

    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 인스턴스 삭제를 참조하세요.

다음 단계