Uno schema descrive le specifiche di un modello Deployment Manager. Se esiste uno schema per un modello, Deployment Manager lo utilizza per applicare in che modo gli utenti possono interagire con il modello corrispondente. Gli schemi definiscono un insieme di 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 di interfacciarsi con i modelli che scrivi, senza dover esaminare e acquisire informazioni su ogni livello dei modelli. Gli utenti possono semplicemente esaminare i requisiti definiti nello schema per scoprire quali proprietà possono essere impostate o richieste per il rispettivo modello.
Ad esempio, puoi creare uno schema in cui il modello corrispondente deve sempre definire un insieme specifico di proprietà obbligatorie e ciascuna di queste deve avere specifiche proprie. 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 nella sua configurazione, esamina lo schema e imposta le proprietà corrette nella configurazione.
Prima di iniziare
- Se vuoi utilizzare gli esempi a riga di comando di questa guida, installa lo strumento a riga di comando "gcloud".
- Se vuoi utilizzare gli esempi di API descritti in questa guida, configura l'accesso alle API.
- Scopri come creare un modello di base.
- Scopri come creare una configurazione
- Scopri di più sullo schema JSON.
Schema di esempio
Lo schema di esempio è stato scritto per il motore dei modelli Jinja. Se utilizzi un motore per i modelli diverso, le estensioni dei file sono diverse, così come la sintassi del modello.
Questo è un semplice file di 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 al seguente 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ò esaminare lo schema per sapere che esiste una proprietà obbligatoria da definire (IPv4Range
) e una proprietà facoltativa (description
) che può 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 schema. Deployment Manager consiglia di scrivere gli schemi in formato YAML, ma puoi anche scrivere schemi in formato JSON, che verrà accettato da Deployment Manager.
Deployment Manager accetta 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
. Di seguito è riportata una breve descrizione di ogni campo e dei relativi contenuti validi.
info
La proprietà info
contiene meta informazioni sullo schema. Sono incluse informazioni come un titolo, un numero di versione, una descrizione e così via.
Fornisci almeno un titolo e una descrizione in questa proprietà.
importazioni
Il campo imports
contiene un elenco dei file corrispondenti necessari per i modelli che utilizzano questo schema. Quando carichi un modello con uno schema che include un elenco di importazioni, Deployment Manager controlla che tutti i file nella proprietà imports
siano stati caricati insieme al modello.
Se specifichi un file in questo campo delle importazioni, puoi ometterlo dal campo imports
della 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
, poiché verrà importato automaticamente quando Deployment Manager esamina lo schema per il modello.
I percorsi di importazione devono essere relativi alla posizione del file di schema. In questo modo puoi archiviare modelli, schemi e configurazioni nella stessa directory e assicurarti che le importazioni dei file siano valide se la directory viene condivisa o spostata.
obbligatorio
Il campo required
contiene un elenco di elementi del campo delle proprietà che sono obbligatori nel modello che utilizza lo schema. Tutti gli elementi non specificati in questo campo required
sono considerati facoltativi.
proprietà
Il campo properties
contiene le regole dello schema JSON per questo documento. Gli elementi descritti nel campo properties
possono essere impostati dagli utenti del modello. Puoi utilizzare tutte le convalide dello schema JSON supportate per queste proprietà, ad esempio:
type
(string, boolean, integer, number, ...)default
minimum / exclusiveMinimum / maximum / exclusiveMaximum
minLength / maxLength
pattern
not X / allOf X, Y / anyOf X, Y / oneOf X, Y
È buona norma includere almeno type
e description
nel campo, in modo che gli utenti sappiano qual è un valore accettabile per la proprietà. Per le proprietà facoltative, è inoltre buona norma includere 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 tutti i campi che non sono uno schema JSON valido. Se devi estendere gli schemi in modo da avere campi o proprietà specializzati, puoi creare arbitrariamente qualsiasi proprietà desiderata e aggiungerla allo schema, purché il campo o la proprietà non si sovrapponga ad alcuna parola chiave di convalida dello schema JSON.
Ad esempio, puoi aggiungere un campo di metadati che annota una delle tue proprietà:
properties:
zone:
type: string
default: us-central1-a
description: Zone to run
metadata: a-special-property
In alternativa, puoi creare una variabile speciale che potresti utilizzare in altre applicazioni al di fuori 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 descritto. Gli schemi devono avere lo stesso nome del modello corrispondente, con l'aggiunta di .schema
alla fine:
TEMPLATE_NAME.EXTENSION.schema
Ad esempio, per un modello denominato vm-instance.py
, il file dello schema corrispondente
deve essere denominato vm-instance.py.schema
. Può esistere un solo schema per ciascun modello.
Gli schemi possono contenere uno o più campi descritti nella sezione Struttura di uno schema. In alternativa, puoi anche 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.
Allo stesso modo, se sono presenti file di schema identificati dal formato .schema
aggiunto, Deployment Manager caricherà lo schema e convaliderà il deployment in base allo schema prima di tentare di creare risorse.
Per utilizzare uno schema, è sufficiente includerlo nella stessa directory locale dei modelli e della configurazione e creare il deployment come faresti normalmente. gcloud CLI rileva e passa il file di 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 come se stessi includendo un modello.
Passaggi successivi
- Scopri di più sui modelli.
- Utilizza le proprietà del modello per astrarre ulteriormente i tuoi contenuti.
- Compila le informazioni sui progetti e sui deployment utilizzando le variabili di ambiente.
- Aggiungi definitivamente un modello al tuo progetto come tipo composito.