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 para 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 utilice 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

Este es un archivo del 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 la siguiente 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 que se hayan escrito 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 del esquema válido es un archivo del esquema en JSON, con el agregado de los dos campos de nivel superior, info e imports. A continuación, se presenta una breve descripción de cada campo y de sus contenidos válidos.

info

La propiedad info contiene información meta 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 necesitan para las plantillas que utilizan este esquema. Cuando subes una plantilla con un esquema que tiene una lista de imports, Deployment Manager controla que todos los archivos en la propiedad imports se hayan subido con la plantilla.

Cuando especifiques un archivo en el campo imports, 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.

required

El campo required contiene una lista de los elementos del campo de propiedades que se necesitan en la plantilla que usa el esquema. Cualquier elemento que no se especifique en el campo required es 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, etc.)
  • default
  • minimum / exclusiveMinimum / maximum / exclusiveMaximum
  • minLength / maxLength
  • pattern
  • not X / allOf X, Y / anyOf X, Y / oneOf X, Y

Como mínimo, es una buena práctica incluir un type y una description del campo para que los usuarios sepan cuál es un valor aceptable para la propiedad. Para propiedades opcionales, resulta útil incluir un valor default.

Lee la documentación sobre la Validación del Esquema en JSON para ver la lista de palabras clave para la 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 que corresponda, más la terminación .schema:

TEMPLATE_NAME.EXTENSION.schema

Por ejemplo, para una plantilla con el nombre vm-instance.py, el esquema correspondiente se debe llamar 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, lee la documentación de los esquemas en JSON.

Usa un esquema

gcloud


Cuando creas una implementación con la herramienta de línea de comandos de gcloud, 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. La herramienta de gcloud detecta el archivo del esquema para Deployment Manager se lo transfiere.

API


Sigue las instrucciones para crear una implementación en la API e incluir el archivo del esquema intercalado en el cuerpo de tu solicitud como si estuvieras incluyendo una plantilla.

Pasos siguientes

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Cloud Deployment Manager Documentation