スキーマは、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'] }}
このテンプレートを設定ファイルで使用しようとするユーザーは、スキーマを検討することで、定義が必要な必須プロパティが 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 を通じてデプロイを作成する手順に従って、テンプレートと同様に、リクエスト本文の一部としてスキーマ ファイルを含めます。
次のステップ
- テンプレートについて学習する。
- テンプレート プロパティを使用してさらにコンテンツを抽象化する。
- 環境変数を使用してプロジェクトとデプロイの情報を設定する。
- プロジェクトに、テンプレートを複合タイプとして永続的に追加する。