スキーマを使用する

スキーマは、Deployment Manager テンプレートの仕様を記述します。テンプレートに対してスキーマが存在する場合、Deployment Manager はスキーマを使用して、ユーザーがテンプレートを利用する方法を規定します。スキーマは、設定ファイルが対象テンプレートを使用する際に満たすべきルールのセットを定義します。

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

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

始める前に

サンプル スキーマ

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'] }}

このテンプレートを設定ファイルで使用しようとするユーザーは、スキーマを検討することで、定義が必要な必須プロパティが 1 つあり（IPv4Range）、必須ではない省略可能なプロパティが 1 つある（description）ということがわかります。これに基づいて設定ファイルを作成することで、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

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 フィールドは、スキーマを使用するテンプレートで必要とされるプロパティ フィールドの要素のリストを格納します。この 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 スキーマのドキュメントをご覧ください。

スキーマを使用する

gcloud


gcloud コマンドライン ツールを使用してデプロイを作成する場合、Deployment Manager はデベロッパーの設定に関連したすべてのテンプレートを自動的にアップロードします。同様に、ファイル名の末尾に .schema が付加されているファイル形式で識別されるスキーマ ファイルが存在する場合、Deployment Manager は、スキーマをアップロードし、リソースを作成する前に、スキーマを基にデプロイを検証します。

テンプレートや設定ファイルと同じローカル ディレクトリにスキーマを配置し、通常どおりにデプロイを作成するだけで、スキーマを使用できます。gcloud ツールがスキーマ ファイルを検出し、Deployment Manager に渡します。

API


API を通じてデプロイを作成する手順に従って、テンプレートと同様に、リクエスト本文の一部としてスキーマ ファイルを含めます。

次のステップ

このページは役立ちましたか？評価をお願いいたします。

フィードバックを送信...

このページ
ドキュメントのフィードバック
Cloud Deployment Manager のドキュメント
サービスのフィードバック