Utilizzo degli schemi

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

Oltre a definire le regole di un modello, gli schemi consentono agli utenti di interfacciarsi con i modelli che scrivi, senza dover esaminare e conoscere ogni livello di modelli. Gli utenti possono semplicemente esaminare i requisiti definiti nello schema per sapere quali proprietà possono essere impostate o richieste per il modello corrispondente.

Ad esempio, puoi creare uno schema in cui il modello corrispondente deve sempre definire un insieme specifico di proprietà obbligatorie e ognuna di queste ha 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 modello nella configurazione, esamina lo schema e imposta le proprietà corrette nella configurazione.

Prima di iniziare

• Se vuoi usare gli esempi della riga di comando in questa guida, installa lo strumento a riga di comando gcloud.
• Se vuoi utilizzare gli esempi di API in questa guida, imposta l'accesso 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 è scritto per il motore di creazione di modelli Jinja. Se utilizzi un motore di creazione dei modelli diverso, le estensioni dei file sono diverse e la sintassi del modello può essere diversa.

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 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ò esaminare lo schema per scoprire che esiste una proprietà obbligatoria che deve definire (IPv4Range) e una proprietà facoltativa (description) che può omettere o includere. Un utente potrebbe quindi creare un file di configurazione come questo, assicurandoti 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 documento di schema di esempio. Deployment Manager consiglia di scrivere gli schemi in formato YAML, ma puoi anche scrivere schemi in JSON e saranno accettati da Deployment Manager.

Deployment Manager accetta gli schemi scritti secondo la bozza 4 delle specifiche di 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 quali titolo, numero di versione, descrizione e così via.

Come minimo, fornisci 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 include un elenco di importazioni, Deployment Manager controlla che tutti i file nella proprietà imports siano stati caricati insieme al modello.

Quando specifichi un file in questo campo di importazione, puoi ometterlo dal campo imports 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 per il modello.

I percorsi di importazione devono essere relativi alla posizione del file dello schema. Questo consente di archiviare modelli, schemi e configurazioni nella stessa directory e di garantire che i file abbiano importazioni valide se la directory viene condivisa o spostata.

obbligatorio

Il campo required contiene un elenco di elementi del campo delle proprietà 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 (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 best practice, includi almeno type e description del campo in modo che gli utenti sappiano quale sia un valore accettabile per la proprietà. Per le proprietà facoltative, è buona norma includere anche un valore default.

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

Nota: tecnicamente, non è necessario descrivere ogni proprietà che può essere impostata per i modelli nello schema. Per i tuoi motivi, puoi descrivere alcune proprietà e non altre. Spetta a te decidere quante informazioni includere. Ad esempio, un possibile caso d'uso potrebbe essere l'inclusione di una proprietà nel campo required che non è descritta nella sezione properties, il che significa che la proprietà deve essere impostata, ma che hai deciso di non descrivere la proprietà nello schema.

Imposta metadati arbitrari

Per impostazione predefinita, Deployment Manager ignora tutti i campi che non sono schemi JSON validi. Se devi estendere gli schemi per avere campi o proprietà specializzati, puoi creare arbitrariamente qualsiasi proprietà tu voglia e aggiungerla allo schema purché il campo o la proprietà non si sovrappongano a parole 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, crei 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 per cui viene descritto. 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, il file di schema corrispondente deve avere il nome vm-instance.py.schema. Per ogni modello può esistere un solo schema.

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 dello 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 dal formato .schema aggiunto, Deployment Manager caricherà lo schema e convaliderà il deployment rispetto allo schema, prima di tentare di creare qualsiasi risorsa.

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 di schema a Deployment Manager.

API

Segui le istruzioni per creare un deployment nell'API e includi il file di schema incorporato nel 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.
• Completa le informazioni sui progetti e sui deployment utilizzando le variabili di ambiente.
• Aggiungi un modello in modo permanente al tuo progetto come tipo composito.