Criar uma configuração básica

Esta página descreve como criar uma configuração que pode ser usada para criar uma implementação. Para saber mais sobre implementações, leia o artigo Criar uma implementação.

Um ficheiro de configuração define todos os Google Cloud recursos que compõem uma implementação. Tem de ter um ficheiro de configuração para criar uma implementação. Um ficheiro de configuração tem de ser escrito na sintaxe YAML.

Antes de começar

• Se quiser usar os exemplos de linhas de comando neste guia, instale a ferramenta de linhas de comando`gcloud`.
• Se quiser usar os exemplos de API neste guia, configure o acesso à API.
• Compreenda as noções básicas sobre os ficheiros de configuração.

Estrutura do ficheiro de configuração

Um ficheiro de configuração é escrito no formato YAML e tem 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 secções define uma parte diferente da implementação:

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

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

  • Um tipo base gerido pela Google, como uma instância de VM do Compute Engine.
  • Um modelo importado
  • Um tipo composto.
  • Um fornecedor de tipos.

Também pode incluir outras secções opcionais, como as secções outputs e metadata. A secção outputs permite-lhe expor dados dos seus modelos e configurações como resultados para outros modelos na mesma implementação a consumir ou como resultados para os seus utilizadores finais, enquanto a secção metadata lhe permite usar outras funcionalidades, como definir dependências explícitas entre recursos.

No mínimo, uma configuração tem de declarar sempre a secção resources, seguida de uma lista de recursos. As outras secções são opcionais.

Declarar um tipo de recurso

Cada recurso na sua configuração tem de ser especificado como um tipo. Os tipos podem ser um tipo base gerido pela Google, um tipo composto, um fornecedor de tipos ou um modelo importado.

Os tipos base geridos pela Google são tipos que são resolvidos em Google Cloud recursos. Por exemplo, uma instância do Cloud SQL ou um contentor do Cloud Storage é um tipo base gerido pela Google. Pode declarar estes tipos através da seguinte sintaxe:

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

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

type: compute.v1.instance

Para uma base de dados do BigQuery, o tipo pode ser:

type: bigquery.v2.dataset

Para ver uma lista de todos os tipos suportados, use o seguinte comando:

gcloud deployment-manager types list

Para ver uma lista completa dos tipos base geridos pela Google suportados, consulte o artigo Tipos de recursos suportados.

Se estiver a usar um composto ou um fornecedor de tipos, declare o tipo da seguinte forma:

# Composite type

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

Para um fornecedor de tipos:

# Base type

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

Também pode criar recursos através de fornecedores de tipos geridos pela Google (beta). Para ver uma lista de fornecedores de tipos, consulte o artigo Fornecedores de tipos suportados. Google Cloud

Se quiser usar modelos, declare o modelo como um tipo, com o nome ou o caminho do modelo como o valor de type. Por exemplo, a seguinte configuração importa um modelo denominado my_vm_template.jinja e disponibiliza-o 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 o artigo Criar um modelo básico.

Declarar propriedades de recursos

Depois de declarar o tipo de recurso, também tem de atribuir um name ao recurso e especificar as propriedades pretendidas para o recurso. Por exemplo, o seguinte ficheiro de configuração define uma instância de máquina virtual denominada vm-created-by-deployment-manager e as respetivas propriedades pretendidas. O Deployment Manager usa estas informações para criar uma instância de VM com estas 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 o properties de um recurso, use a documentação da API para o recurso:

• Consulte o formato do pedido no método insert ou create para o recurso.
• Se o URI do pedido contiver a zona, adicione a zona às propriedades.

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

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

  Na configuração do Deployment Manager, adicione estes discos através da seguinte sintaxe:

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

Também pode fornecer qualquer propriedade gravável desse recurso. Para determinar se uma propriedade é gravável, use a documentação de referência da API para o tipo de recurso. Por exemplo, a referência do Compute Engine marca determinadas propriedades que são apenas de saída, pelo que não pode definir estas propriedades na sua configuração, uma vez que são imutáveis.

Algumas APIs requerem um conjunto mínimo de propriedades para criar um recurso. Um disco persistente do Compute Engine, por exemplo, requer o nome do disco, a origem da imagem, o tamanho do disco, etc., quando cria um novo disco. Para ver informações sobre um recurso específico, reveja a referência da API desse recurso.

Definir propriedades do modelo

Se importar um modelo para usar na sua configuração, usaria a secção properties para definir valores para propriedades do modelo em vez de propriedades de recursos. Em alternativa, se o modelo não tiver propriedades de modelo, pode omitir completamente a secção properties.

Criar recursos a partir de diferentes Google Cloud serviços

Por último, um ficheiro de configuração pode criar recursos a partir de diferentes Google Cloud serviços. Por exemplo, o seguinte ficheiro de configuração cria recursos 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 de recursos e propriedades suportados

Consulte a lista completa de recursos geridos pela Google suportados na documentação de Tipos de recursos suportados.

O que se segue?

• Pré-visualize a sua configuração antes de se comprometer a implementá-la.
• Quando estiver satisfeito com a configuração, use-a para criar uma implementação.
• Eventualmente, deve considerar reformular os seus ficheiros de configuração para usar modelos.