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.

Hinweis

Beispielschema

Das Beispielschema ist für die Jinja-Template-Engine geschrieben. Wenn Sie Vorlagen-Engines verwenden, unterscheiden sich Ihre Dateiendungen und kann die Vorlagensyntax unterschiedlich sein.

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 gilt für die Vorlage 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'] }}

Wenn ein Nutzer diese Vorlage in seiner Konfiguration verwenden will, kann er das Schema prü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 Schema-Datei ist eine JSON-Schema-Datei. durch Hinzufügen der beiden Felder der obersten Ebene, info und imports. Im Folgenden werden die einzelnen Felder und gültigen Inhalte der Felder kurz beschrieben.

info

Das Attribut info enthält Metainformationen über das Schema. Dazu gehören Informationen wie der 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 der entsprechenden Dateien, die für Vorlagen erforderlich sind, die dieses Schema verwenden. Wenn Sie eine Vorlage mit einem Schema hochladen, das eine Liste von Importen enthält, prüft Deployment Manager, ob alle Dateien im Attribut imports zusammen mit der Vorlage hochgeladen wurden.

Wenn Sie in diesem Importfeld eine Datei angeben, können Sie sie in der Konfiguration aus dem Feld imports weglassen. Im obigen Beispiel importiert das Feld imports einen Dateinamen 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 und sicherstellen, dass die Dateien gültige Importe haben, falls das Verzeichnis freigegeben oder verschoben wird.

erforderlich

Das Feld required enthält eine Liste der Elemente aus dem Attributfeld, die für Vorlagen erforderlich sind, die dieses Schema verwenden. 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, Boolean, 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 Feldes anzugeben, damit Nutzer wissen, welche Werte für dieses Attribut akzeptiert werden. Für optionale Attribute empfiehlt es sich auch, eine default-Variable anzugeben.

Eine Liste der Validierungs-Keywords finden Sie in der Dokumentation zur 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. Schemas müssen mit demselben Namen wie die entsprechende Vorlage benannt werden, wobei .schema an das Ende angehängt wird:

TEMPLATE_NAME.EXTENSION.schema

Beispiel: Für eine Vorlage mit dem Namen vm-instance.py muss die entsprechende Schemadatei 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 Schemas auch in JSON schreiben. Beispiele für JSON-Schemas finden Sie in der Dokumentation JSON-Schema.

Schema verwenden

gcloud


Wenn Sie eine Bereitstellung mit der Google Cloud CLI erstellen, wird Deployment Manager automatisch lädt alle relevanten Vorlagen für die Konfiguration für Sie hoch. Sind Schema-Dateien vorhanden, werden diese durch die angehängten .schema verwenden, lädt Deployment Manager das Schema hoch und validiert die Bereitstellung für das Schema, bevor es versucht, 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. Die gcloud CLI erkennt die Schemadatei und übergibt sie an Deployment Manager.

API


Gehen Sie gemäß den Anweisungen vor, um in der API eine Bereitstellung zu erstellen und die Schemadatei genau wie eine Vorlage direkt in Ihren Anfragetext einzuschließen.

Nächste Schritte