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
- Si deseas usar los ejemplos de línea de comandos de esta guía, instala la herramienta de línea de comandos de gcloud.
- Si deseas usar los ejemplos de la API en esta guía, configura el acceso a la API.
- Aprende a crear una plantilla básica.
- Aprende a crear una configuración
- Aprende el esquema en JSON.
Esquema de ejemplo
El esquema de ejemplo está escrito para el motor de plantillas Jinja. Si usas un motor de plantillas diferente, las extensiones de archivo son diferentes y 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 en 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, …)defaultminimum / exclusiveMinimum / maximum / exclusiveMaximumminLength / maxLengthpatternnot 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 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 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 en JSON, consulta la documentación del esquema en JSON.
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. La gcloud CLI detecta el archivo del esquema para Deployment Manager se lo transfiere.
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?
- Aprende sobre las plantillas.
- Usa las propiedades de las plantillas para comprimir todavía más tu contenido.
- Propaga la información sobre los proyectos y las implementaciones con las variables de entorno.
- Agrega una plantilla de forma permanente a tu proyecto como un tipo compuesto.