Como criar um modelo básico

Para as cargas de trabalho simples, um arquivo de configuração básico muitas vezes é o suficiente. No entanto, para as arquiteturas mais complexas ou as configurações que serão reutilizadas, é possível dividir a configuração em modelos.

Um modelo é um arquivo separado que é importado e usado como um tipo em uma configuração. É possível usar quantos modelos quiser em uma configuração.

Com os modelos, é possível dividir a configuração em partes diferentes usáveis e reutilizáveis em implantações diferentes. Os modelos podem ter o grau de generalização ou especificidade que você precisar. Com eles, você também pode aproveitar alguns outros recursos, como propriedades de modelo, variáveis de ambiente, módulos e outras funcionalidades de modelo, para criar arquivos dinâmicos de configuração e modelo.

Para exemplos de modelos que você pode usar em suas próprias implantações, consulte o repositório do GitHub do Deployment Manager.

Antes de começar

Sintaxe do modelo

É possível gravar modelos em Jinja 2.10.x ou Python 3.x (links em inglês). O mapeamento do Jinja é mais próximo à sintaxe do YAML, o que poderá facilitar a escrita de modelos em Jinja se você estiver mais familiarizado com o YAML.

Você também pode escrever arquivos de modelo em Python e aproveitar essa linguagem para gerar de modo programático partes de modelos. Por exemplo, você pode usar as bibliotecas do Python para formatar definições de modelos. Se você estiver familiarizado com o Python, esse pode ser o melhor formato para seu caso.

O Deployment Manager aceita os modelos Jinja e Python. É possível importar modelos nos dois idiomas na mesma configuração.

Como criar um modelo básico

Modelo é um arquivo local criado por você, escrito em linguagem Jinja ou Python. Por exemplo, pense no arquivo de configuração a seguir:

# Copyright 2016 Google Inc. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

resources:
- name: vm-created-by-deployment-manager
  type: compute.v1.instance
  properties:
    zone: us-central1-a
    machineType: zones/us-central1-a/machineTypes/n1-standard-1
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        sourceImage: projects/debian-cloud/global/images/family/debian-11
    networkInterfaces:
    - network: global/networks/default

Essa é uma configuração válida. No entanto, você pode simplificá-la ainda mais ao dividi-la em diferentes partes, no formato de arquivos de modelo individuais reutilizáveis. Para criar um modelo com base na configuração acima, extraia a seção do recurso em questão e crie um novo arquivo em Jinja ou Python.

Os seguintes trechos mostram as seções de modelos que podem simplificar sua implantação. Para os modelos completos, clique em Exibir no GitHub.

- name: vm-template
  type: compute.v1.instance
  properties:
    zone: us-central1-a
    machineType: zones/us-central1-a/machineTypes/n1-standard-1
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        sourceImage: projects/debian-cloud/global/images/family/debian-11
    networkInterfaces:
    - network: global/networks/default

Seus modelos Python devem atender a estes requisitos:

  • É preciso que seja definido pelo modelo um método chamado GenerateConfig(context) ou generate_config(context). Se você usar os dois nomes de métodos no mesmo modelo, o método generate_config() terá precedência.

    O objeto context contém metadados sobre a implantação e seu ambiente, como o nome da implantação, o projeto atual e assim por diante. Saiba mais sobre o uso de variáveis de ambiente específicas da implantação.

  • O método precisa retornar um dicionário Python.

Em qualquer outra ocasião, você decide se vai gerar o conteúdo do modelo.

Exemplo

resources.append({
    'name': 'vm-template',
    'type': 'compute.v1.instance',
    'properties': {
        'zone': 'us-central1-a',
        'machineType': 'zones/us-central1-a/machineTypes/n1-standard-1',
        'disks': [{
            'deviceName': 'boot',
            'type': 'PERSISTENT',
            'boot': True,
            'autoDelete': True,
            'initializeParams': {
                'sourceImage':
                    'projects/debian-cloud/global/images/family/debian-11'
            }
        }],
        'networkInterfaces': [{
            'network': 'global/networks/default'
        }]
    }
})

Para ver o exemplo completo em Python, consulte o repositório do GitHub no Deployment Manager.

Como importar o modelo

Depois de criar o modelo, para usá-lo basta importá-lo no arquivo de configuração. Para importar um modelo, adicione uma seção imports à sua configuração, seguida pelo caminho relativo ou absoluto do diretório atual. Por exemplo, é possível importar o modelo de máquina virtual da etapa anterior, basta adicionar a seguinte linha ao início da configuração:

imports:
  - path: path/to/my_vm_template.jinja

Se você tiver um caminho de arquivo longo, poderá fornecer uma propriedade name opcional como um alias para o arquivo. Futuramente, use esse nome para fazer referência ao modelo. Se você não fornecer o nome, será possível fazer referência ao modelo usando path.

imports:
  - path: path/to/my_vm_template.jinja
    name: my_renamed_template.jinja

É possível misturar e combinar importações de vários modelos, sejam eles Jinja ou Python:

imports:
  - path: path/to/my_vm_template.jinja
    name: my_renamed_template.jinja
  - path: special_vm.py

Se o modelo usar outros modelos como dependências, importe também os modelos dependentes para a configuração:

imports:
  - path: path/to/my_vm_template.jinja
  - path: special_vm.py
  - path: base_vm.jinja

Você também pode importar arquivos de texto para deixar o conteúdo in-line. Por exemplo, caso você crie um arquivo chamado resource_type.txt com a seguinte string:

compute.v1.instance

Importe-o para a configuração e forneça o conteúdo in-line da seguinte maneira:

imports:
- path: resource_type.txt

resources:
- name: my-vm
  type: {{ imports["resource_type.txt"] }} # Resolves to "compute.v1.instance"
  properties:
    zone: us-central1-a
    machineType: zones/us-central1-a/machineTypes/f1-micro
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        sourceImage: projects/debian-cloud/global/images/family/debian-9
    networkInterfaces:
    - network: global/networks/default
      accessConfigs:
      - name: External NAT
        type: ONE_TO_ONE_NAT

Como implantar modelos

Após importar o modelo, use-o como um tipo na configuração:

imports:
- path: vm-template.jinja

resources:
- name: my-vm
  type: vm-template.jinja
imports:
- path: vm-template.py

resources:
- name: my-vm
  type: vm-template.py

Se o nome do modelo não foi fornecido, chame-o usando o caminho:

imports:
- path: path/to/my_vm_template.jinja

resources:
- name: my-first-virtual-machine
  type: path/to/my_vm_template.jinja

Como implantar modelos diretamente com a ferramenta de linha de comando

Em vez de criar um arquivo de configuração de nível superior, o Deployment Manager oferece a capacidade de implantar um modelo diretamente na CLI do Google Cloud.

Por exemplo, a solicitação a seguir implanta um modelo chamado vm-template.jinja:

gcloud deployment-manager deployments create a-single-vm --template vm-template.jinja

Se seu modelo tiver propriedades de modelo , será possível definir essas propriedades na linha de comando usando a sinalização --properties:

gcloud deployment-manager deployments create my-igm \
    --template vm-template.jinja \
    --properties zone:us-central1-a

Lembre-se:

  • Todos os valores são analisados como valores de YAML. Por exemplo, version: 3 é transmitido como um número inteiro. Se você quiser especificá-lo como uma string, coloque aspas simples com escape em volta do valor, version: \'3\'.

  • Os valores booleanos não diferenciam maiúsculas de minúsculas, por isso, TRUE, true e True são tratados da mesma maneira.

  • É preciso que todas as propriedades obrigatórias sejam definidas pelo modelo. Não é possível fornecer apenas um subconjunto de propriedades. Se algumas propriedades tiverem valores padrão, será possível omiti-las da linha de comando.

Para especificar várias propriedades, forneça pares de chave-valor separados por vírgulas. A ordem na qual os pares são especificados não é importante. Por exemplo:

gcloud deployment-manager deployments create my-igm 
--template vm-template.jinja
--properties zone:us-central1-a,machineType:n1-standard-1,image:debian-9

Após executar esse comando, o Deployment Manager cria uma implantação usando o modelo que você forneceu. Você pode confirmar que a implantação foi criada usando o console do Google Cloud ou a gcloud CLI. Para mais informações sobre como visualizar a implantação, leia Como ver um manifesto.

A seguir