スキーマを使用する

スキーマは、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

有効なスキーマファイルとは、JSON スキーマファイルであり、info と imports という 2 つの最上位フィールドが追加されているものです。各フィールドの簡単な説明と有効なコンテンツについて以下に示します。

情報

info プロパティは、スキーマに関するメタ情報を格納します。タイトル、バージョン番号、説明などの情報が含まれます。

最低限の条件として、このプロパティではタイトルと説明を指定します。

imports

imports フィールドは、このスキーマを使用するテンプレートに必要な関連ファイルのリストを格納します。インポートのリストを含むスキーマを使用してテンプレートをアップロードすると、Deployment Manager は imports プロパティのすべてのファイルがテンプレートとともにアップロードされたことを確認します。

このインポートフィールドでファイルを指定する場合、構成の imports フィールドから省略できます。上記の例では、imports フィールドは vm-instance.jinja という名前のファイルをインポートします。

imports:
- path: vm-instance.jinja

対応する構成ファイルでは、vm-instance.jinja ファイルのインポートについては省略できます。このファイルは、Deployment Manager がテンプレートのスキーマを検査するときに自動的にインポートされます。

インポートパスは、スキーマファイルの場所を基準とした相対パスで指定する必要があります。テンプレート、スキーマ、構成を同じディレクトリに保存しておくと、ディレクトリを共有したときや移動したときに、各ファイルにおけるインポートの有効性を維持できます。

必須

required フィールドには、スキーマを使用するテンプレートに必要な、プロパティフィールドの要素のリストが含まれます。この required フィールドに指定されていない要素は、省略可能な要素と判断されます。

properties

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 スキーマ検証キーワードと重複しない限り、必要なプロパティを任意に作成し、スキーマに追加できます。

たとえば、いずれかのプロパティにアノテーションを付ける metadata フィールドを追加できます。

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 という名前にする必要があります。1 つのテンプレートに対して存在できるスキーマは 1 つに限られます。

スキーマの構造で説明したとおり、スキーマには 1 つまたは複数のフィールドを含めることができます。また、JSON 形式でスキーマを記述することもできます。JSON スキーマのサンプルについては、JSON スキーマのドキュメントをご覧ください。