Utilizzo degli schemi

Uno schema descrive le specifiche di un modello Deployment Manager. Se per un modello esiste uno schema, Deployment Manager lo utilizza per applicare le modalità di interazione degli utenti con il modello corrispondente. Gli schemi definiscono un insieme regole che un file di configurazione deve soddisfare per utilizzare un determinato modello.

Oltre a definire le regole di un modello, gli schemi consentono anche agli utenti a interagire con i modelli che scrivi, senza dover rivedere e apprendere su ogni livello di modelli. Gli utenti possono semplicemente rivedere i requisiti definiti nel tuo schema per sapere quali proprietà sono impostabili o richieste modello corrispondente.

Ad esempio, potresti creare uno schema in cui il modello corrispondente deve sempre definiscono un insieme specifico di proprietà obbligatorie, ciascuna delle quali avrà le proprie specifiche. Una proprietà deve essere una stringa, un'altra deve essere un numero intero minore di 100 e così via. Se un utente vuole applicare il tuo modello alla propria configurazione, esamina lo schema e imposta le proprietà corrette nella configurazione.

Prima di iniziare

Schema di esempio

Lo schema di esempio è scritto per il motore di creazione di modelli Jinja. Se utilizzando un motore per la creazione di modelli diverso, le estensioni dei file sono diverse e la sintassi del modello può essere diversa.

Questo è un semplice file schema denominato 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

Lo schema si applica a questo modello, 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'] }}

Se un utente vuole utilizzare questo modello nella propria configurazione, può consultare lo schema per capire che c'è una proprietà obbligatoria che devono definire (IPv4Range) e una proprietà facoltativa (description) che possono omettere o includere. Un utente potrebbe quindi creare un file di configurazione come questo, assicurandosi di fornire una proprietà denominata 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

Struttura di uno schema

Di seguito è riportato un esempio di documento dello schema. Deployment Manager consiglia agli schemi in formato YAML, ma puoi anche scrivere schemi in JSON per essere accettati da Deployment Manager.

Deployment Manager accetta gli schemi scritti in base alla bozza 4 delle specifiche dello schema JSON.

<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

Un file di schema valido è un file di schema JSON con l'aggiunta di due campi di primo livello, info e imports. Le seguenti è una breve descrizione di ogni campo e dei relativi contenuti validi.

info

La proprietà info contiene meta informazioni sullo schema. Sono inclusi informazioni come titolo, numero di versione, descrizione e così via.

Fornisci almeno un titolo e una descrizione in questa proprietà.

importazioni

Il campo imports contiene un elenco di file corrispondenti necessari per i modelli che utilizzano questo schema. Quando carichi un modello con uno schema che un elenco di importazioni, Deployment Manager controlla che tutti i file imports proprietà è stata caricata insieme al modello.

Quando specifichi un file in questo campo delle importazioni, puoi ometterlo dal imports campo nella configurazione. Nell'esempio precedente, il campo imports importa un nome file vm-instance.jinja:

imports:
- path: vm-instance.jinja

Nel file di configurazione corrispondente, un utente può omettere l'importazione del file vm-instance.jinja, perché verrà importato automaticamente quando Deployment Manager ispeziona lo schema del modello.

I percorsi di importazione devono essere relativi alla posizione del file dello schema. In questo modo, puoi memorizzare modelli, schemi e configurazioni nella stessa directory e assicurarti che le importazioni dei file siano valide se la directory viene condivisa o spostata.

di provisioning.

Il campo required contiene un elenco di elementi del campo delle proprietà obbligatori nel modello che utilizza lo schema. Qualsiasi elemento non specificato in questo campo required è considerato facoltativo.

proprietà

Il campo properties contiene le regole dello schema JSON per questo documento. Elementi descritto nel campo properties può essere impostato dagli utenti del modello. Puoi utilizzare tutte le convalide degli schemi JSON supportate per queste proprietà, ad esempio:

  • type (stringa, booleano, numero intero, numero, ...)
  • default
  • minimum / exclusiveMinimum / maximum / exclusiveMaximum
  • minLength / maxLength
  • pattern
  • not X / allOf X, Y / anyOf X, Y / oneOf X, Y

Come minimo, è buona norma includere un type e un description del campo in modo che gli utenti sappiano qual è un valore accettabile per la proprietà. Per le proprietà facoltative, è buona prassi includere anche un valore default.

Leggi la documentazione di convalida dello schema JSON per un elenco di parole chiave di convalida.

Imposta metadati arbitrari

Per impostazione predefinita, Deployment Manager ignora i campi non validi in formato JSON . Se devi estendere gli schemi per avere campi o proprietà specializzati, puoi creare arbitrariamente qualsiasi proprietà e aggiungerla allo schema, a condizione che il campo o la proprietà non si sovrapponga a nessuna delle parole chiave di convalida dello schema JSON.

Ad esempio, puoi aggiungere un campo di metadati che annoti una delle tue proprietà:

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

Oppure crei una variabile speciale che potresti usare in altre applicazioni all'esterno di Deployment Manager:

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

Crea uno schema

Uno schema è un documento separato che prende il nome dal modello che descrive. Gli schemi devono avere lo stesso nome del modello corrispondente, con .schema aggiunto alla fine:

TEMPLATE_NAME.EXTENSION.schema

Ad esempio, per un modello denominato vm-instance.py, lo schema corrispondente il file deve essere denominato vm-instance.py.schema. Può esistere un solo schema per ogni modello.

Gli schemi possono contenere uno o più dei campi descritti nella sezione Struttura di uno schema. In alternativa, puoi scrivere schemi in JSON. Per esempi di schemi JSON, consulta la documentazione relativa allo schema JSON.

Utilizza uno schema

gcloud


Quando crei un deployment utilizzando Google Cloud CLI, Deployment Manager carica automaticamente tutti i modelli pertinenti per la configurazione. Analogamente, se sono presenti file di schema, identificati dalla funzione formato .schema, Deployment Manager caricherà lo schema e convaliderà il deployment in base allo schema, prima di tentare di creare risorse.

Per utilizzare uno schema, includilo nella stessa directory locale dei modelli e della configurazione e crea il deployment come faresti normalmente. L'interfaccia a riga di comando gcloud rileva e passa il file dello schema a Deployment Manager.

API


Segui le istruzioni per creare un deployment nell'API e includi il file di schema in linea con il corpo della richiesta se stessi includendo un modello.

Passaggi successivi