gcloud CLI를 사용하여 서비스 트래픽 보호

이 페이지에서는 API 게이트웨이에 API를 배포하여 백엔드 서비스 트래픽을 보호하는 방법을 보여줍니다.

아래 단계에 따라 Google Cloud 콘솔을 사용해서 새 API를 배포하여 Cloud Run Functions에서 백엔드 서비스에 액세스합니다. 이 빠른 시작에서는 또한 API 키를 사용하여 무단 액세스로부터 백엔드를 보호하는 방법을 설명합니다.

시작하기 전에

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

참고: 이 빠른 시작에서 만든 리소스를 보관할 계획이 없으면 기존 프로젝트를 선택하는 대신 새 프로젝트를 만들어야 합니다. 작업이 끝나면 프로젝트를 삭제하여 프로젝트와 관련된 모든 리소스를 삭제할 수 있습니다.
프로젝트에 결제가 사용 설정되어 있는지 확인합니다.
결제 사용 설정 방법 알아보기
Google Cloud CLI가 머신에 다운로드되고 설치되었는지 확인합니다.
gcloud CLI 다운로드
gcloud 구성요소를 업데이트합니다.
```
gcloud components update
```
기본 프로젝트를 설정합니다. PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
```
gcloud config set project PROJECT_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 서비스를 참조하세요.

API 백엔드 배포

API 게이트웨이는 배포된 백엔드 서비스 앞에 설정되어 모든 수신 요청을 처리합니다. 이 빠른 시작에서는 API 게이트웨이가 수신 호출을 아래 표시된 함수를 포함하는 helloGET이라는 Cloud Run 함수 백엔드로 라우팅합니다.

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

빠른 시작: Google Cloud CLI 사용의 단계에 따라 샘플 Cloud Run Functions 코드를 다운로드하고 Cloud Run Functions 백엔드 서비스를 배포합니다.

API 만들기

이제 API 게이트웨이에서 API를 만들 준비가 되었습니다.

다음 명령어를 입력합니다. 각 항목의 의미는 다음과 같습니다.
- API_ID는 API의 이름을 지정합니다. API ID 이름 지정 가이드라인은 API 이름 지정 요구사항을 참조하세요.
- PROJECT_ID은 Google Cloud 프로젝트 이름을 지정합니다.
```
gcloud api-gateway apis create API_ID --project=PROJECT_ID
```
예를 들면 다음과 같습니다.
```
gcloud api-gateway apis create my-api --project=my-project
```

성공적으로 완료되었으면 다음 명령어를 사용하여 새 API에 대한 세부정보를 볼 수 있습니다.

gcloud api-gateway apis describe API_ID --project=PROJECT_ID

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

gcloud api-gateway apis describe my-api --project=my-project

이 명령어는 다음을 반환합니다.

  createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

managedService 속성 값을 기록해 둡니다. 이 값은 이후 단계에서 API를 사용 설정하는 데 사용됩니다.

API 구성 만들기

API 게이트웨이를 사용하여 배포된 API 백엔드에 대한 트래픽을 관리할 수 있으려면 API 구성이 필요합니다.

특수한 주석이 포함된 OpenAPI 사양을 사용해서 API 구성을 만들어 원하는 API 게이트웨이 동작을 정의할 수 있습니다. 이 빠른 시작에 사용되는 OpenAPI 사양에는 Cloud Run Functions 백엔드에 대한 라우팅 명령이 포함되어 있습니다.

# openapi2-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

이 OpenAPI 사양을 업로드하고 gcloud CLI를 사용해서 API 구성을 만들려면 다음 안내를 따르세요.

명령줄에서 openapi2-functions.yaml이라는 새 파일을 만듭니다.
위에 표시된 OpenAPI 사양의 콘텐츠를 복사해서 새로 생성된 파일에 붙여넣습니다.
다음과 같이 파일을 수정합니다.
1. title 필드에서 API_ID를 API 이름으로 바꾸고 optional-string을 선택한 간략한 설명으로 바꿉니다. 이 필드 값은 이 API에 대해 액세스 권한을 부여하는 API 키를 만들 때 사용됩니다.
2. address 필드에서 GCP_REGION을 배포된 함수의 GCP 리전으로 바꾸고 PROJECT_ID를 Google Cloud 프로젝트의 이름으로 바꿉니다.
다음 명령어를 입력합니다. 각 항목의 의미는 다음과 같습니다.
- CONFIG_ID는 API 구성의 이름을 지정합니다.
- API_ID는 API의 이름을 지정합니다.
- API_DEFINITION은 OpenAPI 사양의 파일 이름을 지정합니다.
- PROJECT_ID은 Google Cloud 프로젝트 이름을 지정합니다.
- SERVICE_ACCOUNT_EMAIL은 구성된 인증으로 백엔드의 토큰을 서명하는 데 사용되는 서비스 계정을 지정합니다. 자세한 내용은 서비스 계정 구성을 참조하세요.
  참고: Cloud Run Functions 백엔드에 대해 API 구성을 만드는 데 사용되는 서비스 계정에는 cloudfunctions.invoker 역할이 할당되어 있어야 합니다.
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
예를 들면 다음과 같습니다.
```
gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com
```
API 구성이 다운스트림 시스템에 전파되기 때문에 이 작업은 완료하는 데 몇 분 정도 걸릴 수 있습니다. 복잡한 API 구성을 만들기 위해서는 최대 10분까지 걸릴 수 있습니다.

참고: 이 명령어를 실행하고 FAILED_PRECONDITION: Service Account ... does not exist 형태로 오류가 표시되면 서비스 계정 구성을 참조해서 서비스에 대해 서비스 계정이 사용 설정되었는지 확인합니다.
참고: 지정된 API에 대해 한 번에 하나만 API 구성을 만들 수 있습니다. 동일한 API에 대해 새 구성을 만들려면 구성 만들기가 완료될 때까지 기다려야 합니다.

API 구성이 생성되었으면 다음 명령어를 실행하여 세부정보를 확인할 수 있습니다.

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

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

gcloud api-gateway api-configs describe my-config \
  --api=my-api --project=my-project

출력에는 아래 예시에 표시된 것처럼 이름 및 상태를 포함하여 API 구성 세부정보가 표시됩니다.

createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

게이트웨이 만들기

이제 게이트웨이에서 API 구성을 배포합니다. 게이트웨이에 API 구성을 배포하면 API 클라이언트가 API에 액세스하기 위해 사용할 수 있는 외부 URL이 정의됩니다.

다음 명령어를 실행하여 바로 전에 만든 API 구성을 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 리전입니다.
참고:
허용되는 값은 다음과 같습니다.
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
PROJECT_ID은 Google Cloud 프로젝트 이름을 지정합니다.

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

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

성공적으로 완료되었으면 다음 명령어를 사용하여 게이트웨이에 대한 세부정보를 확인합니다.

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

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

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1 --project=my-project

이 명령어는 다음을 반환합니다.

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

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

API 배포 테스트

이제 게이트웨이 배포 후 생성된 URL을 사용해서 API로 요청을 보낼 수 있습니다.

다음 curl 명령어를 입력합니다. 각 항목의 의미는 다음과 같습니다.

DEFAULT_HOSTNAME은 배포된 게이트웨이 URL의 호스트 이름 부분을 지정합니다.
hello는 API 구성에 지정된 경로입니다.

curl https://DEFAULT_HOSTNAME/hello

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

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

출력은 다음과 같습니다.

Hello World!

지금까지 API 게이트웨이 만들기와 배포를 성공적으로 완료했습니다!

API 키를 사용하여 액세스 보안

API 백엔드 액세스를 보호하기 위해서는 프로젝트와 연결된 API 키를 생성하고 이 키에 API 호출 액세스 권한을 부여합니다. 자세한 내용은 API 키를 사용하여 API 액세스 제한을 참조하세요.

이 빠른 시작에서 사용되는 Google Cloud 프로젝트와 연결된 API 키가 아직 없으면 API 키 만들기의 단계에 따라 하나 추가할 수 있습니다.

API 키를 사용하여 게이트웨이에 대한 액세스를 보호하려면 다음 안내를 따르세요.

서비스에 대해 API 키 지원을 사용 설정합니다. 다음 명령어를 입력합니다. 각 항목의 의미는 다음과 같습니다.
- MANAGED_SERVICE_NAME은 API를 배포할 때 만든 관리형 서비스의 이름을 지정합니다. gcloud apigee-gateway apis describe 명령어를 사용해서 나열된 관리형 서비스 속성에서 확인할 수 있습니다.
- PROJECT_ID은 Google Cloud 프로젝트 이름을 지정합니다.
```
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
```
예를 들면 다음과 같습니다.
```
gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
```

모든 트래픽에 대해 API 키 검증 보안 정책을 적용하도록 API 구성을 만드는 데 사용된 OpenAPI 사양을 수정합니다. 아래와 같이 security 유형 및 securityDefinitions를 추가합니다.

  # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"

securityDefinition은 사양에 정의된 모든 경로에 액세스를 요청할 때 key라는 쿼리 매개변수로 API 키가 전달되도록 API를 구성합니다.

다음 명령어를 사용하여 수정된 OpenAPI 사양으로 새 API 구성을 만듭니다.

gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

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

gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com

다음 명령어를 실행하여 새 API 구성으로 기존 게이트웨이를 업데이트합니다.

gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

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

gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

API 키 테스트

수정된 API를 만들고 배포한 후 요청을 시도합니다.

다음 curl 명령어를 입력합니다. 각 항목의 의미는 다음과 같습니다.

DEFAULT_HOSTNAME은 배포된 게이트웨이 URL의 호스트 이름 부분을 지정합니다.
hello는 API 구성에 지정된 경로입니다.

curl https://DEFAULT_HOSTNAME/hello

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

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

이렇게 하면 다음 오류가 발생합니다.

UNAUTHENTICATED: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.

이제 다음 curl 명령어를 입력합니다. 각 항목의 의미는 다음과 같습니다.

DEFAULT_HOSTNAME은 배포된 게이트웨이 URL의 호스트 이름 부분을 지정합니다.
hello는 API 구성에 지정된 경로입니다.
API_KEY는 이전 단계에서 만든 API 키를 지정합니다.

curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

이제 API의 응답에 Hello World!가 표시됩니다.

수고하셨습니다. 지금까지 API 게이트웨이를 사용한 API 백엔드 보호가 성공적으로 완료되었습니다. 이제 추가 API 키를 생성하여 새 API 클라이언트 온보드를 시작할 수 있습니다.

삭제

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

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

다음 단계

API 게이트웨이 정보 자세히 알아보기
개발 환경 구성 살펴보기
서비스 간 인증 알아보기