Como criar uma configuração básica

Nesta página, descrevemos como fazer uma configuração que possa ser usada para criar uma implantação. Para saber mais sobre implantações, leia Como criar uma implantação.

Um arquivo de configuração define todos os recursos do Google Cloud que compõem uma implantação. É necessário ter um arquivo de configuração para criar uma implantação. O arquivo de configuração precisa ser escrito em sintaxe YAML.

Antes de começar

Estrutura do arquivo de configuração

O arquivo de configuração deve ser escrito em formato YAML e ter a seguinte estrutura:

#  imported templates, if applicable
imports:
  #  path relative to the configuration file
- path: path/to/template.jinja
  name: my-template
- path: path/to/another/template.py
  name: another-template

resources:
  - name: NAME_OF_RESOURCE
    type: TYPE_OF_RESOURCE
    properties:
      property-a: value
      property-b: value
      ...
      property-z: value
  - name: NAME_OF_RESOURCE
    type: TYPE_OF_RESOURCE
    properties:
      property-a: value
      property-b: value
      ...
      property-z: value

Cada uma das seções define uma parte diferente da implantação:

  • As seções imports são uma lista de arquivos de modelo que serão usados pela configuração. O Deployment Manager expande todos os modelos importados recursivamente para formar a configuração final.

  • A seção resources é uma lista de recursos que compõem esta implantação. Um recurso pode ser:

Outras seções opcionais, como outputs e metadata, também podem ser incluídas. A seção outputs permite que exponha dados de modelos e configurações como saídas para consumo de outros modelos na mesma implantação ou para saídas dos seus usuários finais. A seção metadata permite que você use outros recursos, como a definição de dependências explícitas entre recursos.

É preciso que no mínimo uma configuração sempre declare a seção resources, seguida por uma lista de recursos. As outras seções são opcionais.

Como declarar um tipo de recurso

É necessário que cada recurso na configuração seja especificado como um tipo. Os tipos podem ser um tipo base gerenciado pelo Google, um tipo composto, um provedor de tipos ou um modelo importado.

Os tipos de base que o Google gerencia são resolvidos pelos recursos do Google Cloud. Por exemplo, uma instância do Cloud SQL ou um bucket do Cloud Storage são tipos base gerenciados pelo Google. Você pode declarar esses tipos usando a sintaxe a seguir:

type: <api>.<api-version>.<resource-type>

Por exemplo, uma instância do Compute Engine teria o seguinte tipo:

type: compute.v1.instance

Para um banco de dados do BigQuery, o tipo pode ser:

type: bigquery.v2.dataset

Para ver uma lista de todos os tipos compatíveis, use o seguinte comando:

gcloud deployment-manager types list

Para ver uma lista completa dos tipos base aceitos pelo Google, consulte Tipos de recursos compatíveis.

Se você estiver usando um tipo composto ou um provedor de tipos, declare o tipo da seguinte maneira:

# Composite type

resources:
- name: my-composite-type
  type: [PROJECT]/composite:[TYPE_NAME]

Para um provedor de tipos:

# Base type

resources:
- name: my-base-type
  type: [PROJECT_ID]/[TYPE_PROVIDER_NAME]:[TYPE_NAME]

Você também pode criar recursos com provedores de tipo gerenciados pelo Google (Beta). Para ver uma lista dos provedores de tipos do Google Cloud, acesse Provedores de tipos suportados.

Se você quiser usar modelos, declare o modelo como um tipo, com o nome do modelo ou caminho como o valor de type. Por exemplo, a configuração a seguir importa um modelo chamado my_vm_template.jinja e o fornece como um tipo:

imports:
- path: path/to/template/my_vm_template.jinja
  name: my-template.jinja

resources:
- name: my-first-virtual-machine
  type: my-template.jinja

Para mais informações sobre modelos, leia Criação de um modelo básico.

Como declarar propriedades do recurso

Depois de declarar o tipo de recurso, você precisa fornecer o recurso a name e especificar as propriedades pretendidas para o recurso. Por exemplo, o arquivo de configuração a seguir define uma instância de máquina virtual chamada vm-created-by-deployment-manager e as propriedades dela que você quer. O Deployment Manager usa essas informações para criar uma instância de VM que tenha essas propriedades.

# 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

Para determinar a properties de um recurso, use a documentação da API para ele:

  • Veja o formato da solicitação no método insert ou create do recurso.
  • Se o URI de solicitação contiver a zona, adicione a zona às propriedades.

  • Para matrizes, use a sintaxe da lista YAML para listar os elementos da matriz. Por exemplo, ao criar uma instância do Compute Engine com a API, é preciso fornecer uma matriz de discos para anexar à instância, no seguinte formato:

    "disks": [
  {
    "type": "PERSISTENT",
    "deviceName": "disk1",
    ...
  },
  {
    "type": "PERSISTENT",
    "deviceName": "disk2",
    ...
  }
]

    Na configuração do Deployment Manager, você adiciona esses discos com a seguinte sintaxe:

    disks:
- deviceName: disk1
  type: PERSISTENT
  ...
- deviceName: disk2
  type: PERSISTENT

Também é possível fornecer qualquer propriedade gravável desse recurso. Para determinar se uma propriedade é gravável, use a documentação de referência da API referente ao tipo do recurso. Por exemplo, a referência do Compute Engine marca determinadas propriedades como somente saída. Portanto, não é possível defini-las na configuração, porque são imutáveis.

Algumas APIs exigem um grupo mínimo de propriedades para criar um recurso. Por exemplo, para criar um disco persistente do Compute Engine, é necessário definir o nome do disco, a fonte da imagem, o tamanho do disco e assim por diante. Para ver mais informações sobre um recurso específico, consulte a referência da API desse recurso.

Como definir as propriedades do modelo

Se você importar um modelo para usar na configuração, use a seção properties para definir valores para as propriedades do modelo e não para as propriedades do recurso. Como alternativa, se o modelo não tiver propriedades de modelo, omita completamente a seção properties.

Como criar recursos de diferentes serviços do Google Cloud

Por fim, um arquivo de configuração pode criar recursos de diferentes serviços do Google Cloud. Por exemplo, o seguinte arquivo de configuração cria recursos a partir do Compute Engine e do BigQuery:

# 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

- name: big-query-dataset
  type: bigquery.v2.dataset
  properties:
    datasetReference:
      datasetId: example_id

Tipos e propriedades de recurso compatíveis

Consulte a lista completa de recursos compatíveis gerenciados pelo Google na documentação Tipos de recurso compatíveis.

A seguir