Usar esquemas

Un esquema describe las especificaciones de una plantilla de Deployment Manager. Si existe un esquema para una plantilla, Deployment Manager lo usa para definir cómo pueden interactuar los usuarios con la plantilla correspondiente. Los esquemas definen un conjunto de reglas que debe cumplir un archivo de configuración si quiere usar una plantilla concreta.

Además de definir las reglas de una plantilla, los esquemas también permiten que los usuarios interactúen con las plantillas que escribas sin tener que revisar ni aprender sobre cada capa de las plantillas. Los usuarios pueden consultar los requisitos definidos en tu esquema para saber qué propiedades se pueden definir o son obligatorias para la plantilla correspondiente.

Por ejemplo, puede crear un esquema en el que la plantilla correspondiente siempre deba definir un conjunto específico de propiedades obligatorias, y cada una de estas propiedades tenga sus propias especificaciones. Una propiedad debe ser una cadena, otra debe ser un número entero inferior a 100, etc. Si un usuario quiere aplicar tu plantilla en su configuración, revisa el esquema y define las propiedades correctas en su configuración.

Antes de empezar

Ejemplo de esquema

El esquema de ejemplo se ha escrito para el motor de plantillas Jinja. Si usas otro motor de plantillas, las extensiones de los archivos y la sintaxis de las plantillas pueden ser diferentes.

Este es un archivo de esquema sencillo llamado 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

El esquema se aplica a esta plantilla: 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'] }}

Si un usuario quiere usar esta plantilla en su configuración, puede consultar el esquema para saber que hay una propiedad obligatoria que debe definir (IPv4Range) y una propiedad opcional (description) que puede omitir o incluir. Un usuario puede crear un archivo de configuración como este y asegurarse de proporcionar una propiedad llamada 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

Estructura de un esquema

A continuación, se muestra un ejemplo de documento de esquema. Deployment Manager recomienda que los esquemas se escriban en formato YAML, pero también puedes escribirlos en JSON y Deployment Manager los aceptará.

Deployment Manager acepta esquemas escritos de acuerdo con el borrador 4 de las especificaciones del esquema 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 archivo de esquema válido es un archivo de esquema JSON con dos campos de nivel superior adicionales: info y imports. A continuación, se incluye una breve descripción de cada campo y su contenido válido.

información

La propiedad info contiene metainformación sobre el esquema. Esto incluye información como el título, el número de versión, la descripción, etc.

Como mínimo, proporciona un título y una descripción en esta propiedad.

importaciones

El campo imports contiene una lista de los archivos correspondientes que se necesitan para las plantillas que usan este esquema. Cuando subes una plantilla con un esquema que tiene una lista de importaciones, Deployment Manager comprueba que todos los archivos de la propiedad imports se hayan subido junto con la plantilla.

Si especifica un archivo en este campo de importaciones, puede omitirlo del campo imports de la configuración. En el ejemplo anterior, el campo imports importa un nombre de archivo vm-instance.jinja:

imports:
- path: vm-instance.jinja

En el archivo de configuración correspondiente, un usuario puede omitir la importación del archivo vm-instance.jinja, ya que se importará automáticamente cuando Deployment Manager inspeccione el esquema de la plantilla.

Las rutas de importación deben ser relativas a la ubicación del archivo de esquema. De esta forma, puedes almacenar plantillas, esquemas y configuraciones en el mismo directorio, y asegurarte de que los archivos tengan importaciones válidas si el directorio se comparte o se mueve.

obligatorio

El campo required contiene una lista de elementos del campo de propiedades que son obligatorios en la plantilla que usa el esquema. Los elementos que no se especifiquen en este campo required se considerarán opcionales.

properties

El campo properties contiene las reglas del esquema JSON de este documento. Los usuarios de la plantilla pueden definir los elementos descritos en el campo properties. Puedes usar todas las validaciones de esquemas JSON admitidas para estas propiedades, como las siguientes:

  • type (cadena, booleano, entero, número, etc.)
  • default
  • minimum / exclusiveMinimum / maximum / exclusiveMaximum
  • minLength / maxLength
  • pattern
  • not X / allOf X, Y / anyOf X, Y / oneOf X, Y

Como mínimo, es recomendable incluir un type y un description del campo para que los usuarios sepan qué valor es aceptable para la propiedad. En el caso de las propiedades opcionales, también es recomendable incluir un valor default.

Consulta la documentación de validación de esquemas JSON para ver una lista de palabras clave de validación.

Definir metadatos arbitrarios

De forma predeterminada, Deployment Manager ignora los campos que no sean un esquema JSON válido. Si necesitas ampliar tus esquemas para que tengan campos o propiedades especializados, puedes crear arbitrariamente cualquier propiedad que quieras y añadirla a tu esquema, siempre que el campo o la propiedad no se solapen con ninguna palabra clave de validación de esquemas JSON.

Por ejemplo, puede añadir un campo de metadatos que anote una de sus propiedades:

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

También puede crear una variable especial que puede usar en otras aplicaciones fuera de Deployment Manager:

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

Crear un esquema

Un esquema es un documento independiente que recibe el nombre de la plantilla que describe. Los esquemas deben tener el mismo nombre que la plantilla correspondiente, con .schema añadido al final:

TEMPLATE_NAME.EXTENSION.schema

Por ejemplo, si una plantilla se llama vm-instance.py, el archivo de esquema correspondiente debe llamarse vm-instance.py.schema. Solo puede haber un esquema por plantilla.

Los esquemas pueden contener uno o varios de los campos descritos en la sección Estructura de un esquema. También puedes escribir esquemas en JSON. Para ver ejemplos de esquemas JSON, consulta la documentación sobre esquemas JSON.

Usar un esquema

gcloud


Cuando creas una implementación con la CLI de Google Cloud, Deployment Manager sube automáticamente todas las plantillas relevantes para la configuración. Del mismo modo, si hay archivos de esquema, identificados por el formato .schema, Deployment Manager subirá el esquema y validará la implementación con respecto al esquema antes de intentar crear recursos.

Para usar un esquema, inclúyelo en el mismo directorio local que tus plantillas y configuración, y crea tu implementación como lo harías normalmente. La interfaz de línea de comandos de gcloud detecta el archivo de esquema y lo transfiere a Deployment Manager.

API


Sigue las instrucciones para crear una implementación en la API e incluye el archivo de esquema en el cuerpo de la solicitud como si incluyeras una plantilla.

Siguientes pasos