유형 공급자로 API 추가

이 페이지에서는 API를 Google Cloud Deployment Manager에 유형 공급자로 추가하는 방법을 설명합니다. 유형 및 유형 공급자에 대한 자세한 내용은 유형 개요 문서를 참조하세요.

유형 공급자는 타사 API의 모든 리소스를 구성에서 사용할 수 있는 기본 유형으로 Deployment Manager에 노출합니다. CRUD(만들기, 읽기, 업데이트, 삭제)를 지원하는 RESTful API가 이러한 유형을 직접 제공해야 합니다.

Google이 Deployment Manager에서 자동으로 제공하지 않는 API를 사용하려면 API를 유형 공급자로 추가해야 합니다. API에 OpenAPI 사양(이전 명칭 Swagger^©) 또는 Google Discovery 문서가 포함되어 있다면 모든 API를 유형 공급자로 추가할 수 있습니다.

이 문서에서는 고유한 API 서비스를 설정하는 방법을 설명하지 않습니다. 여기에서는 추가하려는 API가 있거나 공개 엔드포인트에서 액세스할 수 있는 실행 중인 API가 이미 생성되어 있다고 가정합니다. 예를 들어 Google Cloud Endpoints를 사용하여 샘플 API를 배포하려면 Cloud Endpoints 빠른 시작을 따르세요.

시작하기 전에

이 가이드의 명령줄 예시를 사용하려면 'gcloud' 명령줄 도구를 설치합니다.
이 가이드의 API 예시를 사용하려면 API 액세스를 설정합니다.
이 가이드의 API 예시를 사용하려면 v2beta API 액세스를 설정합니다.

유형 공급자의 구성요소

유형 공급자는 다음으로 구성됩니다.

이름: 유형 공급자에 사용하려는 이름입니다. 이 이름을 사용하여 유형 및 관련된 API 리소스를 참조합니다.
설명자 문서: 해당 유형의 설명자 문서의 URL입니다. 지원되는 문서에는 Google Discovery 문서 또는 OpenAPI 1.2 사양이 포함됩니다.
인증: API에 필요한 모든 사용자 인증 정보입니다. 기본 인증을 지정할 수 있습니다. API가 Cloud Endpoints 또는 Google Kubernetes Engine(GKE)에서 실행되는 경우 프로젝트의 서비스 계정 사용자 인증 정보를 인증으로 사용할 수도 있습니다.
고급 옵션: 모든 고급 입력 매핑 또는 API 옵션입니다.

이름

유형 공급자의 이름입니다. 이 이름은 이후 구성 및 템플릿에서 유형을 참조하는 데 사용됩니다. 예를 들어 유형 공급자를 만들고 이름을 my-awesome-type-provider로 지정했으면 후속 템플릿에서 다음과 같이 사용하게 됩니다.

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

여기서 my-project는 유형이 속한 프로젝트 ID이고 some-collection은 만들려는 API 리소스의 경로입니다.

설명자 문서

유형 공급자를 위한 설명자 문서는 OpenAPI 1.2 또는 2.0 사양 또는 Google Discovery 문서일 수 있습니다. 예를 들어 다음 URL에서 Compute Engine Beta API를 위한 Google Discovery 문서를 찾을 수 있습니다.

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

Google Discovery 문서 전체 목록을 참조하세요.

OpenAPI 1.2 및 OpenAPI 2.0 문서도 사용 가능합니다.

인증

API에 인증이 필요한 경우 여기에 인증 세부정보를 제공할 수 있습니다. Deployment Manager에서는 사용자 이름과 비밀번호 등 기본 사용자 인증 정보가 지원됩니다. Google Kubernetes Engine과 Google Cloud Endpoints의 경우 Authorization 헤더를 사용하여 프로젝트 서비스 계정의 액세스 토큰을 제공할 수도 있습니다.

기본 사용자 인증 정보를 지정하려면 credentials 섹션에 사용자 이름과 비밀번호를 제공합니다.

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

유형 공급자를 처음 만들 때만 사용자 이름과 비밀번호를 지정하면 됩니다.

Deployment Manager를 사용 중인 동일한 프로젝트의 Google Kubernetes Engine(GKE)에서 실행되는 클러스터가 있는 경우 클러스터를 유형 공급자로 추가하고 Deployment Manager를 사용하여 GKE API에 액세스할 수 있습니다. 이 시나리오에서는 프로젝트의 Google API 서비스 계정의 OAuth 2.0 액세스 토큰을 가져와 Authorization 헤더에 제공할 수 있습니다. 이전의 사용자 인증 정보 섹션과 달리, 요청에서 입력 매핑으로 이를 제공해야 합니다.

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

googleOauth2AccessToken() 메서드는 사용자가 이 유형 공급자를 호출할 때 액세스 토큰을 자동으로 가져옵니다. 전체 예시는 GKE 클러스터 및 유형 샘플을 참조하세요.

동일한 메서드를 사용하여 Google Cloud Endpoints에 인증할 수 있습니다.

(선택사항) 커스텀 인증 기관 루트

사용자는 API를 Deployment Manager에 유형 공급자로 추가하기를 원하고 API의 HTTPS 엔드포인트는 공개적으로 신뢰할 수 있는 인증 기관(CA)에서 제공하지 않는 인증서를 사용하여 연결을 암호화하는 경우 다음 예시와 같이 API를 구성에 추가할 수 있습니다.

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

여기서 my-gke-cluster은 사용 중인 GKE 클러스터입니다. 자세한 예시는 GKE 공급자 클러스터 샘플을 참조하세요.

고급 유형 옵션

특정 API는 특이성으로 인해 Deployment Manager가 API의 모든 속성을 Deployment Manager에 배포하기 어려울 수 있습니다. 이상적인 시나리오에서는 개발자가 설명자 문서를 제공하고, Deployment Manager는 개발자의 추가 작업 없이 API 요청 경로 및 관련 API 속성을 자동으로 이해합니다. 복잡한 API의 경우 Deployment Manager가 대부분의 API를 이해할 수 있지만 명확하지 않은 API 동작에 대해서는 개발자가 입력 매핑을 명시적으로 지정해야 할 수 있습니다.

입력 매핑에 대한 자세한 내용은 고급 API 옵션 문서를 참조하세요.

유형 공급자 만들기

유형 공급자를 만들려면 원하는 유형 공급자 이름, 설명자 URL, 모든 필수 인증 사용자 정보가 포함된 요청 페이로드를 사용하여 Deployment Manager에 요청을 수행합니다.

gcloud

gcloud CLI를 사용하여 유형 공급자를 만들려면 type-providers create 명령어를 사용합니다.

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

각 매개변수는 다음과 같습니다.

[TYPE_PROVIDER_NAME]은 이 유형에 지정하려는 이름입니다.
[URL]은 이 유형을 지원하는 설명자 문서에 대한 정규화된 URL입니다. 예를 들면 다음과 같습니다.
```
http://petstore.swagger.io/v2/swagger.json
```

사용자 인증 정보 또는 고급 API 옵션을 제공하려면 YAML로 작성된 API 옵션 파일을 만들고 --api-options-file 플래그를 사용하면 됩니다. 예를 들어 파일은 다음과 같이 표시됩니다.

collectionOverrides:
- collection: /emailAddresses/v1beta/people
  options:
    inputMappings:
    - methodMatch: ^create$
      fieldName: emailAddress.displayName
      value: $.resource.properties.displayName
      location: BODY
    - methodMatch: ^update$
      fieldName: displayName
      value: $.resource.properties.displayName
      location: PATH
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        displayName:
          type: string
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

gcloud 명령어는 다음과 같습니다.

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

커스텀 인증 기관(CA)을 사용하여 인증하려면 다음 예시와 같이 CA를 gcloud 명령어에 플래그로 추가할 수 있습니다.

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

API

API에서 기본 유형을 만들려면 요청 본문에 descriptorUrl 및 선택적 구성 옵션이 포함된 POST 요청을 수행합니다. 예를 들면 다음과 같습니다.

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "methodMatch":"^update$",
            "value":"$.resource.properties.displayName"
          }
        ],
        "virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

자세한 내용은 insert 메서드의 문서를 참조하세요.

유형 공급자 테스트

유형 공급자가 예상한 대로 작동하는지 확인하려면 다음 안내를 따르세요.

구성에서 새로운 유형 공급자를 호출합니다.
유형 공급자가 제공한 각 컬렉션을 배포하여 API가 예상한 대로 작동하는지 확인합니다. 컬렉션은 지정된 유형 공급자의 API 리소스입니다.
각 컬렉션에 대해 업데이트를 수행합니다.
각 컬렉션을 삭제합니다.

사용자가 유형 공급자에서 유형을 인스턴스화하면 실제로 기본 API에 명시적으로 요청하는 대신 Deployment Manager에 요청을 보내게 됩니다. 그러면 Deployment Manager가 제공된 정보로 요청을 만들어 사용자 대신 API에 요청합니다. 발생 가능한 가장 일반적인 문제는 Deployment Manager가 자동으로 인식하기 어려운 속성이 API에 포함된다는 점입니다. 예를 들어 일부 API에는 API 응답에서만 추출할 수 있는 속성이 포함됩니다. 다른 API는 작업에 따라 다른 값이 포함된 동일한 필드 이름을 사용할 수 있습니다. 이러한 경우에는 Deployment Manager가 이러한 시나리오를 처리할 수 있는 방법을 명시적으로 지정해야 합니다.

API에 이러한 특성이 포함된 경우, 입력 매핑을 사용하여 Deployment Manager의 모호성을 명확하게 해야 합니다.

다음 단계

유형 공급자 호출 방법을 알아봅니다.
유형 공급자를 다른 프로젝트와 공유합니다.
유형에 대해 알아봅니다.
구성 만들기에 대해 알아봅니다.
배포를 만듭니다.
고급 API 옵션에 대해 알아봅니다.