Usar esquemas

Um esquema descreve as especificações de um modelo do Deployment Manager. Se existir um esquema para um modelo, o Deployment Manager usa o esquema para aplicar a forma como os utilizadores podem interagir com o modelo correspondente. Os esquemas definem um conjunto de regras que um ficheiro de configuração tem de cumprir se quiser usar um modelo específico.

Além de definir as regras de um modelo, os esquemas também permitem que os seus utilizadores interajam com os modelos que escreve, sem terem de rever e saber mais sobre cada camada de modelos. Em alternativa, os utilizadores podem simplesmente rever os requisitos definidos no seu esquema para saber que propriedades são configuráveis ou necessárias para o modelo respetivo.

Por exemplo, pode criar um esquema em que o modelo correspondente tem sempre de definir um conjunto específico de propriedades obrigatórias, e cada uma destas propriedades tem as suas próprias especificações. Uma propriedade tem de ser uma string, outra tem de ser um número inteiro inferior a 100 e assim sucessivamente. Se um utilizador quiser aplicar o seu modelo na respetiva configuração, revê o esquema e define as propriedades corretas na respetiva configuração.

Antes de começar

Esquema de exemplo

O esquema de exemplo é escrito para o motor de modelos Jinja. Se estiver a usar um motor de modelos diferente, as extensões de ficheiros são diferentes e a sintaxe do modelo pode ser diferente.

Este é um ficheiro de esquema simples denominado 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

O esquema aplica-se a este modelo, 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 um utilizador quiser usar este modelo na respetiva configuração, pode rever o esquema para saber que existe uma propriedade obrigatória que tem de definir (IPv4Range) e uma propriedade opcional (description) que pode omitir ou incluir. Em seguida, um utilizador pode criar um ficheiro de configuração da seguinte forma, certificando-se de que faculta uma propriedade denominada 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

Estrutura de um esquema

Segue-se um exemplo de um documento de esquema. O Deployment Manager recomenda que os esquemas sejam escritos no formato YAML, mas também pode escrever esquemas em JSON, e estes são aceites pelo Deployment Manager.

O Deployment Manager aceita esquemas escritos de acordo com o rascunho 4 das especificações do 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

Um ficheiro de esquema válido é um ficheiro de esquema JSON com a adição de dois campos de nível superior, info e imports. Segue-se uma breve descrição de cada campo e do respetivo conteúdo válido.

informação

A propriedade info contém metainformações sobre o esquema. Isto inclui informações como um título, um número de versão, uma descrição, etc.

No mínimo, indique um título e uma descrição nesta propriedade.

importações

O campo imports contém uma lista de ficheiros correspondentes que são necessários para modelos que usam este esquema. Quando carrega um modelo com um esquema que tem uma lista de importações, o Deployment Manager verifica se todos os ficheiros na propriedade imports foram carregados juntamente com o modelo.

Quando especifica um ficheiro neste campo de importações, pode omiti-lo do campo imports na configuração. No exemplo acima, o campo imports importa um nome de ficheiro vm-instance.jinja:

imports:
- path: vm-instance.jinja

No ficheiro de configuração correspondente, um utilizador pode omitir a importação do ficheiro vm-instance.jinja, porque é importado automaticamente quando o Deployment Manager inspeciona o esquema do modelo.

Os caminhos de importação têm de ser relativos à localização do ficheiro de esquema. Isto permite-lhe armazenar modelos, esquemas e configurações no mesmo diretório, e garantir que os ficheiros têm importações válidas se o diretório for partilhado ou movido.

obrigatório

O campo required contém uma lista de elementos do campo de propriedades que são obrigatórios no modelo que usa o esquema. Todos os elementos não especificados neste campo required são considerados opcionais.

propriedades

O campo properties contém as regras do esquema JSON para este documento. Os elementos descritos no campo properties podem ser definidos pelos utilizadores do modelo. Pode usar todas as validações de esquema JSON suportadas para estas propriedades, como:

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

No mínimo, é uma boa prática incluir um type e um description do campo para que os utilizadores saibam qual é um valor aceitável para a propriedade. Para propriedades opcionais, também é recomendável incluir um valor default.

Leia a documentação de validação do esquema JSON para ver uma lista de palavras-chave de validação.

Defina metadados arbitrários

Por predefinição, o Deployment Manager ignora todos os campos que não sejam um esquema JSON válido. Se precisar de expandir os seus esquemas para ter campos ou propriedades especializados, pode criar arbitrariamente qualquer propriedade que pretender e adicioná-la ao seu esquema, desde que o campo ou a propriedade não se sobreponham a nenhuma palavra-chave de validação do esquema JSON.

Por exemplo, pode adicionar um campo de metadados que anota uma das suas propriedades:

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

Em alternativa, pode criar uma variável especial que pode usar noutras aplicações fora do Deployment Manager:

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

Crie um esquema

Um esquema é um documento separado com o nome do modelo que descreve. Os esquemas têm de ter o mesmo nome que o modelo correspondente, com .schema anexado ao final:

TEMPLATE_NAME.EXTENSION.schema

Por exemplo, para um modelo com o nome vm-instance.py, o ficheiro de esquema correspondente tem de ter o nome vm-instance.py.schema. Só pode existir um esquema para cada modelo.

Os esquemas podem conter um ou mais dos campos descritos na secção Estrutura de um esquema. Em alternativa, também pode escrever esquemas em JSON. Para ver exemplos de esquemas JSON, consulte a documentação do esquema JSON.

Use um esquema

gcloud


Quando cria uma implementação através da CLI do Google Cloud, o Deployment Manager carrega automaticamente todos os modelos relevantes para a configuração. Da mesma forma, se existirem ficheiros de esquema, identificados pelo formato .schema anexado, o Deployment Manager carrega o esquema e valida a implementação em função do esquema antes de tentar criar recursos.

Para usar um esquema, basta incluí-lo no mesmo diretório local que os seus modelos e configuração, e criar a implementação como faria normalmente. A CLI gcloud deteta e transmite o ficheiro de esquema ao Deployment Manager.

API


Siga as instruções para criar uma implementação na API e inclua o ficheiro de esquema incorporado no corpo do pedido como se estivesse a incluir um modelo.

O que se segue?