スキーマを使用する

スキーマは、Deployment Manager テンプレートの仕様を記述します。テンプレートに対してスキーマが存在する場合、Deployment Manager はスキーマを使用して、ユーザーがテンプレートを利用する方法を規定します。スキーマは、特定のテンプレートを使用するために構成ファイルが満たすべき一連のルールを定義したものです。

スキーマは、テンプレートのルールを定義するほか、ユーザーがテンプレートを利用するためのインターフェースを提供します。ユーザーはテンプレートの各レイヤについて検討したり、理解したりする必要はありません。ユーザーは、スキーマに定義されている要件を検討するだけでよく、それぞれのテンプレートに設定可能なプロパティや必須のプロパティについて理解する必要がありません。

たとえば、対応するテンプレートで特定の必須プロパティセットを常に定義する必要があること、さらにプロパティごとに指定が異なることを示すスキーマを作成できます。たとえば、あるプロパティは文字列にする必要があり、別のプロパティは 100 未満の整数にする必要があるように設定できます。テンプレートを構成ファイルに適用する際、ユーザーはスキーマを検討することで、構成ファイル内で適切なプロパティを設定できます。

始める前に

このガイドのコマンドラインの例を使用する場合は、gcloud コマンドラインツールをインストールします。
このガイドの API の例を使用する場合は、API アクセスを設定します。
基本テンプレートの作成方法を理解しておきます。
構成の作成方法を理解しておきます。
JSON スキーマについて理解しておきます。

サンプルスキーマ

これは、次の名前を持つシンプルなスキーマファイルです: 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

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

情報

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 スキーマのドキュメントを参照してください。