스키마 사용

스키마는 Deployment Manager 템플릿의 사양을 기술합니다. 템플릿에 스키마가 존재할 경우, Deployment Manager는 스키마를 사용하여 사용자가 해당 템플릿을 상호작용하는 방법을 적용합니다. 스키마는 특정 템플릿을 사용해야 할 경우, 구성 파일이 충족해야 하는 규칙 집합을 정의합니다.

스키마를 사용하면 템플릿 규칙을 정의하는 것 외에도, 템플릿의 각 계층을 검토하고 학습할 필요 없이 개발자가 작성한 템플릿을 사용자가 사용할 수 있습니다. 사용자는 단순히 스키마에 정의된 요구사항만 검토하면 되고, 해당 템플릿에 설정 가능하거나 필요한 속성이 무엇인지 확인할 필요가 없습니다.

예를 들어 템플릿이 항상 특정한 필수 속성 집합을 정의해야 하고, 이러한 각 속성에 고유 사양이 포함되도록 스키마를 만들 수 있습니다. 한 속성은 문자열만 포함하고, 다른 속성은 100 미만의 정수만 포함하도록 지정할 수 있습니다. 사용자가 자신의 구성에 개발자의 템플릿을 적용하려는 경우 사용자는 스키마를 검토하고 자신의 구성에 올바른 속성을 설정하면 됩니다.

시작하기 전에

이 가이드의 명령줄 예시를 사용하려면 'gcloud' 명령줄 도구를 설치합니다.
이 가이드의 API 예시를 사용하려면 API 액세스를 설정합니다.
기본 템플릿을 만드는 방법을 이해합니다.
구성을 만드는 방법을 이해합니다.
JSON 스키마를 이해합니다.

스키마 예

Jinja 템플릿 엔진에 대해 작성된 예시 스키마입니다. 다른 템플릿 엔진을 사용하는 경우 파일 확장자가 다르며 템플릿 구문도 다를 수 있습니다.

다음은 vm-instance-with-network.jinja.schema라는 간단한 스키마 파일입니다.

info:
  title: VM Template
  author: Jane
  description: Creates a new network and instance
  version: 1.0

imports:
- path: vm-instance.jinja # Must be a relative path

required:
- IPv4Range

properties:
  IPv4Range:
    type: string
    description: Range of the network

  description:
    type: string
    default: "My super great network"
    description: Description of network

스키마가 이 템플릿 vm-instance-with-network.jinja에 적용됩니다.

resources:
- name: vm-1
  type: vm-instance.jinja

- name: a-new-network
  type: compute.v1.network
  properties:
    IPv4Range: {{ properties['IPv4Range'] }}
    description: {{ properties['description'] }}

사용자가 해당 구성에서 이 템플릿을 사용하고자 하는 경우 스키마를 검토하여 정의해야 하는 필수 속성(IPv4Range) 1개와 생략하거나 포함할 수 있는 선택적인 속성(description) 1개가 있음을 확인할 수 있습니다. 그런 다음에는 해당하는 구성 파일을 만들고 IPv4Range라는 속성만 제공하면 됩니다.

imports:
- path: vm-instance-with-network.jinja

resources:
- name: vm-1
  type: vm-instance-with-network.jinja
  properties:
    IPv4Range: 10.0.0.1/16

스키마 구조

아래는 예제 스키마 문서입니다. Deployment Manager는 스키마를 YAML 형식으로 작성하도록 권장하지만, JSON으로 작성된 스키마도 Deployment Manager에서 허용됩니다.

Deployment Manager는 JSON 스키마 사양의 초안 4에 따라 작성된 스키마를 허용합니다.

<mongodb.py.schema>
info:
  title: MongoDB Template
  author: Jane
  description: Creates a MongoDB cluster
  version: 1.0

imports:
  - path: helper.py
    name: mongodb_helper.py

required:
  - name

properties:
  name:
    type: string
    description: Name of your Mongo Cluster

  size:
    type: integer
    default: 2
    description: Number of Mongo Slaves

  zone:
    type: string
    default: us-central1-a
    description: Zone to run
    metadata: gce-zone

유효한 스키마 파일은 2개의 최상위 필드인 info 및 imports가 추가된 JSON 스키마 파일입니다. 다음은 각 필드 및 해당 콘텐츠에 대한 간단한 설명입니다.

정보

info 속성에는 스키마에 대한 메타 정보가 포함됩니다. 여기에는 제목, 버전 번호, 설명 등과 같은 정보가 포함됩니다.

이 속성에서 최소한 제목과 설명은 제공해야 합니다.

imports

imports 필드에는 이 스키마를 사용하는 템플릿에 필요한 해당 파일 목록이 포함됩니다. imports 목록이 있는 스키마가 포함된 템플릿을 업로드하면 Deployment Manager는 imports 속성의 모든 파일이 템플릿과 함께 업로드되었는지 확인합니다.

이 imports 필드에 파일을 지정할 때는 구성의 imports 필드에서 이를 생략할 수 있습니다. 위 예시에서 imports 필드는 vm-instance.jinja라는 파일을 가져옵니다.

imports:
- path: vm-instance.jinja

해당 구성 파일에서 사용자는 vm-instance.jinja 파일 가져오기를 생략할 수 있습니다. Deployment Manager가 템플릿의 스키마를 검사할 때 이 파일을 자동으로 가져오기 때문입니다.

가져오기 경로는 스키마 파일 위치를 기준으로 해야 합니다. 이렇게 하면 템플릿, 스키마, 구성을 동일한 디렉토리에 저장하고, 디렉토리가 공유되거나 이동될 때에도 파일이 올바른 가져오기 경로를 갖도록 보장할 수 있습니다.

필수

required 필드에는 스키마를 사용하는 템플릿에 필요한 속성 필드의 요소 목록이 포함됩니다. 이 required 필드에 지정되지 않은 요소는 모두 선택 항목으로 고려됩니다.

속성

properties 필드에는 이 문서의 JSON 스키마 규칙이 포함됩니다. 템플릿 사용자가 properties 필드에 설명된 요소를 설정할 수 있습니다. 이러한 속성에는 다음과 같이, 지원되는 모든 JSON 스키마 검증을 사용할 수 있습니다.

type(문자열, 부울, 정수, 숫자 등)
default
minimum / exclusiveMinimum / maximum / exclusiveMaximum
minLength / maxLength
pattern
not X / allOf X, Y / anyOf X, Y / oneOf X, Y

사용자가 속성에 사용 가능한 값이 무엇인지 알 수 있도록 적어도 필드의 type 및 description을 포함하는 것이 좋습니다. 선택적인 속성의 경우에는 default 값도 포함하는 것이 좋습니다.

검증 키워드 목록은 JSON 스키마 검증 문서를 참조하세요.

임의 메타데이터 설정

기본적으로 Deployment Manager는 유효한 JSON 스키마가 아닌 모든 필드를 무시합니다. 특수한 필드 또는 속성을 포함하도록 스키마를 확장해야 할 경우, 해당 필드 또는 속성이 다른 JSON 스키마 검증 키워드와 겹치지 않는 한, 임의로 속성을 만들고 이를 스키마에 추가할 수 있습니다.

예를 들어 속성 중 하나에 주석을 다는 메타데이터 필드를 추가할 수 있습니다.

properties:
  zone:
    type: string
    default: us-central1-a
    description: Zone to run
    metadata: a-special-property

또는 Deployment Manager 외부의 다른 애플리케이션에서 사용할 수 있는 특별한 변수를 만들 수 있습니다.

properties:
  size:
    type: integer
    default: 2
    description: Number of Mongo Slaves
    variable-x: ultra-secret-sauce

스키마 만들기

스키마는 스키마가 설명하는 대상 템플릿을 따라 이름이 지정된 별개의 문서입니다. 스키마 이름은 해당 템플릿의 이름과 같아야 하며 .schema가 끝에 추가됩니다.

TEMPLATE_NAME.EXTENSION.schema

예를 들어 템플릿 이름이 vm-instance.py이면 해당 스키마 파일 이름은 vm-instance.py.schema이어야 합니다. 템플릿마다 스키마는 하나만 존재할 수 있습니다.

스키마는 스키마 구조 섹션에 설명된 필드를 하나 이상 포함할 수 있습니다. 또는 JSON으로 스키마를 작성할 수도 있습니다. JSON 스키마의 예시는 JSON 스키마 문서를 참조하세요.

스키마 사용

gcloud

Google Cloud CLI를 사용하여 배포를 만들 때 Deployment Manager는 자동으로 구성의 모든 관련 템플릿을 업로드합니다. 마찬가지로, 추가된 .schema 형식으로 식별된 스키마 파일이 있으면, 리소스 생성을 시도하기 전에 Deployment Manager가 이 스키마를 업로드하고 스키마에 따라 배포를 검증합니다.

스키마를 사용하려면 템플릿 및 구성과 동일한 로컬 디렉토리에 이를 포함하고, 일반적인 방식으로 배포를 만듭니다. gcloud CLI는 스키마 파일을 검색하고 이를 Deployment Manager로 전달합니다.

API

API에서 배포 만들기 안내를 따르고 템플릿을 포함할 때와 같이 요청 본문에 스키마 파일을 인라인을 포함합니다.

다음 단계

템플릿에 대해 알아봅니다.
템플릿 속성을 사용하여 콘텐츠를 추상화합니다.
환경 변수를 사용하여 프로젝트 및 배포에 대한 정보를 채웁니다.
프로젝트에 템플릿을 복합 유형으로 영구 추가합니다.