Usar esquemas

Un esquema describe las especificaciones de una plantilla de Deployment Manager. Si hay un esquema para una plantilla, Deployment Manager usa este esquema a fin de aplicar la manera en la que los usuarios pueden interactuar con la plantilla correspondiente. Los esquemas definen un conjunto de reglas que un archivo de configuración debe cumplir si quieres que usen una plantilla en particular.

Además de definir las reglas de una plantilla, los esquemas también permiten a los usuarios interactuar con las plantillas que escribes, sin necesidad de controlar y conocer cada capa de plantillas. Los usuarios pueden simplemente revisar los requisitos que se definen en tu esquema en vez de aprender qué propiedades se pueden determinar o cuáles se necesitan para la plantilla correspondiente.

Por ejemplo, podrías crear un esquema en el que la plantilla correspondiente defina siempre un conjunto de propiedades específicas y que cada una de ellas tenga sus propias particularidades. Una propiedad debe ser una string, la otra debe ser un número entero menor que 100 y así sucesivamente. Si un usuario quiere utilizar tu plantilla en su configuración, deberá controlar el esquema y aplicar las propiedades correctas para la configuración.

Antes de comenzar

Esquema de ejemplo

El esquema de ejemplo está escrito para el motor de plantillas Jinja. Si estás con un motor de plantillas diferente, las extensiones de sus archivos son distintas la sintaxis de la plantilla puede ser diferente.

Este es un archivo de esquema simple 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 quisiera usar esta plantilla en su configuración, puede revisar el esquema para determinar si debe definir una propiedad requerida (IPv4Range) y si hay una propiedad opcional (description) que puede omitir o incluir. Un usuario puede, entonces, crear un archivo de configuración de esa manera, asegurándose 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 presenta un documento del esquema a modo de ejemplo. Deployment Manager recomienda escribir los esquemas en formato YAML, pero también los puedes escribir en JSON y Deployment Manager los aceptará.

Deployment Manager acepta esquemas escritos según el borrador 4 de las especificaciones del esquema en 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 la adición de dos campos de nivel superior, info y imports. A continuación, se presenta una breve descripción de cada campo y sus contenidos válidos.

info

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

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

imports

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

Cuando especificas un archivo en este campo de importación, puedes omitirlo del campo imports en 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, porque se importará automáticamente cuando Deployment Manager busque la plantilla en el esquema.

Las rutas de los imports deben ser relativas a la ubicación del archivo del esquema. Esto te permite almacenar plantillas, esquemas y configuraciones en el mismo directorio y asegurarte de que los archivos tengan imports válidos si mueves o compartes el directorio.

obligatorio

El campo required contiene una lista de elementos del campo de propiedades que se requieren en la plantilla que usa el esquema. Cualquier elemento no especificado en este campo required se considera opcional.

properties

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

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

Como mínimo, se recomienda incluir un type y una description del campo a fin de que los usuarios sepan cuál es un valor aceptable para la propiedad. Para propiedades opcionales, también se recomienda incluir un valor default.

Lee la documentación sobre la validación del esquema en JSON. para obtener una lista de palabras clave de validación.

Establece metadatos arbitrarios

De manera predeterminada, Deployment Manager ignora cualquier campo que no sea del esquema en JSON válido. Si necesitas extender tus esquemas para tener propiedades o campos especializados, puedes crear de forma arbitraria cualquier propiedad que desees y agregarla a tu esquema, siempre que el campo o la propiedad no coincida con las palabras clave de validación del esquema en JSON.

Por ejemplo, puedes agregar un campo de metadatos que anote una de tus propiedades:

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

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

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

Crea un esquema

Un esquema es un documento separado con el mismo nombre de la plantilla que describe. Los esquemas deben tener el mismo nombre que la plantilla correspondiente, con la terminación .schema:

TEMPLATE_NAME.EXTENSION.schema

Por ejemplo, para una plantilla llamada vm-instance.py, el archivo de esquema correspondiente debe llamarse vm-instance.py.schema. Solo puede existir un esquema para cada plantilla.

Los esquemas pueden contener un campo o más de los que se describen en la sección de la Estructura de un esquema. De manera alternativa, también puedes escribir esquemas en JSON. Para ver ejemplos de esquemas JSON, consulta la Esquema de JSON en la documentación de Google Cloud.

Usar un esquema

gcloud


Cuando creas una implementación con Google Cloud CLI, Deployment Manager sube automáticamente todas las plantillas relevantes para la configuración. De forma similar, si hay archivos de esquemas, identificados por el formato agregado .schema, Deployment Manager subirá el esquema y validará la implementación según el esquema, antes de que intente crear recursos.

Para usar un esquema, inclúyelo en el mismo directorio local de tus plantillas y configuración y crea la implementación como lo harías normalmente. Gcloud CLI detecta el archivo de esquema y lo pasa a Deployment Manager

API


Sigue las instrucciones para crear una implementación en la API y, luego, incluir el archivo del esquema intercalado en el cuerpo de la solicitud como si incluyeras una plantilla.

¿Qué sigue?