Uso de esquemas

Um esquema descreve as especificações de um modelo do Deployment Manager. Se houver um esquema para um modelo, o Deployment Manager o usará para impor o modo de interação dos usuários com o modelo correspondente. Os esquemas definem um grupo de regras que um arquivo de configuração precisa respeitar caso queira usar um modelo específico.

Além de definir as regras de um modelo, o esquema também permite a interface dos usuários com os modelos escritos, sem a necessidade de avaliar e saber mais sobre cada camada de modelos. Os usuários podem simplesmente avaliar os requisitos definidos no esquema, em vez de procurar saber quais propriedades são definíveis ou obrigatórias para o respectivo modelo.

Por exemplo, você pode criar um esquema em que o modelo correspondente precise sempre definir um grupo específico de propriedades obrigatórias, e cada uma delas tenha especificações próprias. Uma das propriedades precisa ser uma string, a outra tem que ser um número inteiro menor que 100 e assim por diante. Caso queira aplicar o modelo na configuração, o usuário analisa o esquema e define as propriedades corretas na configuração.

Antes de começar

Esquema de exemplo

O esquema de exemplo é escrito para o mecanismo de modelos Jinja. Se você estiver usando um mecanismo de modelagem diferente, as extensões de arquivo serão diferentes e a sintaxe do modelo poderá ser diferente.

Este é um arquivo de esquema simples chamado 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 se aplica 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 usuário quiser usar esse modelo em sua configuração, é possível analisar o esquema para descobrir que há uma propriedade obrigatória a ser definida (IPv4Range) e uma propriedade opcional (description) que pode ser omitida ou incluída. É possível criar um arquivo de configuração dessa forma, fornecendo uma propriedade chamada 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

Abaixo está um documento de esquema de exemplo. O Deployment Manager recomenda que os esquemas sejam escritos em formato YAML, mas você também pode escrever esquemas em JSON, pois eles serão aceitos 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 arquivo de esquema JSON é um arquivo de esquema válido. com a adição de dois campos de nível superior, info e imports. Esta é uma descrição resumida de cada campo e respectivos conteúdos válidos.

info

A propriedade info contém meta informações sobre o esquema. Isso inclui informações como título, número da versão, descrição etc.

Forneça, pelo menos, um título e uma descrição nessa propriedade.

imports

O campo imports contém uma lista de arquivos correspondentes, obrigatórios para modelos que usam este esquema. Quando você faz upload de um modelo com um esquema que possui uma lista de importações, o Deployment Manager verifica se todos os arquivos na propriedade imports foram carregados junto com o modelo.

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

imports:
- path: vm-instance.jinja

No arquivo de configuração correspondente, um usuário pode omitir a importação do arquivo vm-instance.jinja porque ele será importado automaticamente quando o Deployment Manager inspecionar o esquema para o modelo.

Os caminhos de importação devem ser relativos ao local do arquivo de esquema. Isso permite armazenar modelos, esquemas e configurações no mesmo diretório, além de garantir que os arquivos teriam importações válidas se o diretório for compartilhado ou movido.

obrigatório

O campo required contém uma lista de elementos do campo de propriedades que são necessários no modelo que usa o esquema. Qualquer elemento não especificado no campo required é considerado opcional.

properties

O campo properties contém as regras de esquema JSON deste documento. Os elementos descritos no campo properties podem ser definidos pelos usuários do modelo. Você pode usar todas as validações de esquema JSON compatíveis com essas propriedades, como:

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

É prática recomendada incluir pelo menos um type e description do campo para que os usuários saibam o que é um valor aceitável para a propriedade. Para propriedades opcionais, também é prática recomendada incluir um valor default.

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

Definir metadados arbitrários

Por padrão, o Deployment Manager ignora todos os campos que não tenham um esquema JSON válido. Caso precise estender os esquemas para ter campos ou propriedades especializados, você pode criar arbitrariamente qualquer propriedade desejada e adicioná-la ao esquema, contanto que o campo ou a propriedade não se sobreponha a nenhuma palavra-chave de validação do esquema JSON.

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

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

Ou você cria uma variável especial que pode usar em outros aplicativos fora do Deployment Manager:

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

Criar um esquema

Um esquema é um documento separado nomeado após o modelo que descreve. Os esquemas precisam ser nomeados com o mesmo nome que o modelo correspondente, com .schema anexado ao final:

TEMPLATE_NAME.EXTENSION.schema

Por exemplo, para um modelo chamado vm-instance.py, o arquivo de esquema correspondente precisa nomear vm-instance.py.schema. Só pode haver um esquema para cada modelo.

Os esquemas podem conter um ou mais campos descritos na seção Estrutura de um esquema. Como alternativa, também é possível escrever esquemas em JSON. Para exemplos de esquemas JSON, consulte a Esquema JSON na documentação do Google Cloud.

Usar um esquema

gcloud


Quando você cria uma implantação usando a Google Cloud CLI, o Deployment Manager faz automaticamente o upload de todos os modelos relevantes para a configuração. Da mesma forma, se houver arquivos de esquema, identificados pelo formato anexado .schema, o Deployment Manager fará o upload do esquema e validará a implantação em relação ao esquema antes de tentar criar qualquer recurso.

Para usar um esquema, basta incluí-lo no mesmo diretório local dos modelos e da configuração e criar a implantação como você faria normalmente. A CLI gcloud detecta e transmite o arquivo de esquema para o Deployment Manager.

API


Siga as instruções para criar uma implantação na API e inclua o arquivo de esquema in-line com o corpo da solicitação do mesmo modo como você faria para incluir um modelo.

A seguir