Schemas verwenden

In einem Schema werden die Spezifikationen einer Deployment Manager-Vorlage beschrieben. Wenn ein Schema für eine Vorlage vorhanden ist, nutzt Deployment Manager dieses Schema, um durchzusetzen, wie Nutzer mit der entsprechenden Vorlage interagieren können. Schemas definieren eine Reihe von Regeln, denen eine Konfigurationsdatei entsprechen muss, um eine bestimmte Vorlage verwenden zu können.

Neben der Definition der Regeln einer Vorlage ermöglichen Schemas Ihren Nutzern die Verbindung mit den Vorlagen, die Sie schreiben, ohne jede Ebene der Vorlagen überprüfen und erlernen zu müssen. Nutzer können einfach die Voraussetzungen, die in Ihrem Schema definiert sind, überprüfen, anstatt lernen zu müssen, welche Eigenschaften setzbar sind oder für die jeweilige Vorlage benötigt werden.

Beispielsweise können Sie ein Schema erstellen, das die erforderlichen Eigenschaften für jede verbundene Vorlage festlegt. Jede dieser Eigenschaften kann eigene Spezifikationen haben. Zum Beispiel: Eine der Eigenschaften muss ein String sein, eine weitere muss eine Ganzzahl unter 100 sein und so weiter. Wenn ein Nutzer Ihr Schema in seiner Konfiguration anwenden will, überprüft der Nutzer das Schema und gibt die passenden Eigenschaften in seiner Konfiguration an.

Vorbereitung

Beispielschema

Dies ist eine einfache Schemadatei mit dem Namen 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

Das Schema wird auf die Vorlage vm-instance-with-network.jinja angewendet:

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

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

Wenn ein Nutzer diese Vorlage in seiner Konfiguration verwenden will, kann er das Schema überprüfen und wird feststellen, dass es eine notwendige Eigenschaft gibt, die er definieren muss (IPv4Range), und eine optionale Eigenschaft (description), die er entweder weglassen oder einschließen kann. Ein Nutzer könnte dann eine Konfigurationsdatei erstellen, die wie unten gezeigt aussieht und bei der er darauf achtet, eine Eigenschaft mit dem Namen IPv4Range anzugeben:

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

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

Aufbau eines Schemas

Unten finden Sie ein Dokument mit einem Beispielschema. Für Deployment Manager empfiehlt es sich, Schemas im YAML-Format zu schreiben, Deployment Manager akzeptiert jedoch auch Schemas, die in JSON geschrieben wurden.

Deployment Manager akzeptiert Schemas, die dem Entwurf 4 der Spezifikationen für Schemas in JSON entsprechen.

<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

Eine gültige Schemadatei ist eine JSON-Schemadatei mit den beiden übergeordneten Feldern info und imports. Im Folgenden werden die einzelnen Felder und gültigen Inhalte der Felder kurz beschrieben.

Info

Die Eigenschaft info enthält Metainformationen über das Schema. Dies umfasst Informationen wie den Titel, eine Versionsnummer, eine Beschreibung und so weiter.

Geben Sie in dieser Eigenschaft zumindest Titel und Beschreibung an.

imports

Das Feld imports enthält eine Liste von verknüpften Dateien, die für die Vorlagen, die dieses Schema verwenden, benötigt werden. Wenn Sie eine Vorlage mit einem Schema hochladen, das eine Liste von Importen beinhaltet, überprüft Deployment Manager, ob alle Dateien in der Eigenschaft imports zusammen mit der Vorlage hochgeladen wurden.

Wenn Sie eine Datei in diesem imports-Feld angeben, können Sie sie bei Ihrem imports-Feld in der Konfiguration weglassen. Im Beispiel oben importiert das Feld imports eine Datei mit dem Namen vm-instance.jinja:

imports:
- path: vm-instance.jinja

In der verknüpften Konfigurationsdatei kann ein Nutzer den Import der Datei vm-instance.jinja weglassen, da diese automatisch importiert wird, wenn der Deployment Manager das Schema für die Vorlage untersucht.

Importpfade müssen sich auf den Speicherort der Schemadatei beziehen. So können Sie Vorlagen, Schemas und Konfigurationen im gleichen Verzeichnis speichern. Dies gewährleistet, dass für die Dateien gültige Importe vorhanden sind, wenn das Verzeichnis freigegeben oder verschoben wird.

required

Das Feld required beinhaltet eine Liste von Elementen aus dem Feld Eigenschaften, die in der Vorlage, die das Schema verwendet, benötigt werden. Alle Elemente, die nicht im Feld required angegeben sind, werden als optional angesehen.

properties

Das Feld properties enthält die JSON-Schemaregeln für dieses Dokument. Elemente, die im Feld properties beschrieben sind, können von Nutzern der Vorlage gesetzt werden. Sie können für diese Eigenschaften alle unterstützten Validierungen für JSON-Schemas verwenden. Zum Beispiel:

  • type (String, boolescher Wert, Ganzzahl, Zahl, ...)
  • default
  • minimum / exclusiveMinimum / maximum / exclusiveMaximum
  • minLength / maxLength
  • pattern
  • not X / allOf X, Y / anyOf X, Y / oneOf X, Y

Es ist ratsam, zumindest einen type und eine description des Felds anzugeben, damit Nutzer wissen, welche Werte für diese Eigenschaft akzeptiert werden. Für optionale Eigenschaften empfiehlt es sich auch, eine default-Variable anzugeben.

Eine Liste der Validierungs-Keywords finden Sie in der Dokumentation JSON-Schemavalidierung.

Beliebige Metadaten festlegen

Standardmäßig ignoriert Deployment Manager alle Felder, die kein gültiges JSON-Schema darstellen. Wenn Sie Ihre Schemas um spezialisierte Eigenschaften oder Felder erweitern, können Sie beliebig jegliche Eigenschaften erstellen und sie zu Ihrem Schema hinzufügen, solange das Feld oder die Eigenschaft sich nicht mit einem Validierungs-Keyword für JSON-Schemas überschneidet.

Beispielsweise können Sie ein Metadatenfeld hinzufügen, das eine Ihrer Eigenschaften annotiert:

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

Oder Sie erstellen eine spezielle Variable, die Sie in anderen Anwendungen außerhalb von Deployment Manager verwenden können:

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

Schema erstellen

Ein Schema ist ein separates Dokument, das nach der Vorlage, die es beschreibt, benannt ist. Ein Schema muss mit dem gleichen Namen wie die verknüpfte Vorlage bezeichnet werden, wobei .schema am Ende angehängt werden muss:

TEMPLATE_NAME.EXTENSION.schema

Für eine Vorlage mit dem Namen vm-instance.py muss die verknüpfte Schemadatei beispielsweise den Namen vm-instance.py.schema haben. Pro Vorlage kann es nur ein Schema geben.

Schemas können ein oder mehrere Felder beinhalten, die in dem Abschnitt Aufbau eines Schemas beschrieben werden. Alternativ können Sie auch Schemas in JSON schreiben. Beispiele für JSON-Schemas finden Sie in der Dokumentation JSON-Schema.

Schema verwenden

gcloud


Wenn Sie eine Bereitstellung mit dem gcloud-Befehlszeilentool erstellen, lädt Deployment Manager automatisch alle für die Konfiguration erforderlichen Vorlagen hoch. Sind Schemadateien vorhanden – erkennbar am angehängten .schema –, lädt Deployment Manger auch das Schema hoch und validiert die Bereitstellung mit dem Schema, bevor versucht wird, Ressourcen zu erstellen.

Zur Verwendung eines Schemas speichern Sie es einfach im gleichen lokalen Verzeichnis wie Ihre Vorlagen und Ihre Konfiguration und erstellen Ihre Bereitstellung wie gewohnt. Das Tool gcloud erkennt die Schemadatei und übergibt sie an Deployment Manager.

API


In der API erstellen Sie eine Bereitstellung gemäß der Anleitung und fügen die Schemadatei in Ihren Anfragetext wie eine Vorlage ein.

Weitere Informationen

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Cloud Deployment Manager-Dokumentation