gcloud CLI를 사용하여 서비스 트래픽 보호
이 페이지에서는 API 게이트웨이에 API를 배포하여 백엔드 서비스 트래픽을 보호하는 방법을 보여줍니다.
아래 단계에 따라 Google Cloud CLI를 사용해서 새 API를 배포하여 Cloud Functions에서 백엔드 서비스에 액세스합니다. 이 빠른 시작에서는 또한 API 키를 사용하여 무단 액세스로부터 백엔드를 보호하는 방법을 설명합니다.
시작하기 전에
Google Cloud 콘솔에서 대시보드 페이지로 이동하고 Google Cloud 프로젝트를 선택하거나 만듭니다.
프로젝트에 결제가 사용 설정되어 있는지 확인합니다.
Google Cloud 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.comgcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud 서비스에 대한 자세한 내용은 gcloud 서비스를 참조하세요.
API 백엔드 배포
API 게이트웨이는 배포된 백엔드 서비스 앞에 설정되어 모든 수신 요청을 처리합니다. 이 빠른 시작에서는 API 게이트웨이가 수신 호출을 아래 표시된 함수를 포함하는 helloGET이라는 Cloud 함수 백엔드로 라우팅합니다.
/**
* 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 Functions 코드를 다운로드하고 Cloud Function 백엔드 서비스를 배포합니다.
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 함수 백엔드에 대한 라우팅 명령이 포함되어 있습니다.
# 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 사양의 콘텐츠를 복사해서 새로 생성된 파일에 붙여넣습니다.
다음과 같이 파일을 수정합니다.
title필드에서 API_ID를 API 이름으로 바꾸고 optional-string을 선택한 간략한 설명으로 바꿉니다. 이 필드 값은 이 API에 대해 액세스 권한을 부여하는 API 키를 만들 때 사용됩니다.address필드에서 GCP_REGION을 배포된 함수의 GCP 리전으로 바꾸고 PROJECT_ID를 Google Cloud 프로젝트의 이름으로 바꿉니다.
다음 명령어를 입력합니다. 각 항목의 의미는 다음과 같습니다.
- CONFIG_ID는 API 구성의 이름을 지정합니다.
- API_ID는 API의 이름을 지정합니다.
- API_DEFINITION은 OpenAPI 사양의 파일 이름을 지정합니다.
- PROJECT_ID은 Google Cloud 프로젝트 이름을 지정합니다.
- SERVICE_ACCOUNT_EMAIL은 구성된 인증으로 백엔드의 토큰을 서명하는 데 사용되는 서비스 계정을 지정합니다. 자세한 내용은 서비스 계정 구성을 참조하세요.
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분까지 걸릴 수 있습니다.
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 리전입니다.
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
- MANAGED_SERVICE_NAME은 API를 배포할 때 만든 관리형 서비스의 이름을 지정합니다.
- 모든 트래픽에 대해 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 게이트웨이 정보 자세히 알아보기
- 개발 환경 구성 살펴보기
- 서비스 간 인증 알아보기