Crear una configuración básica

En esta página se describe cómo crear una configuración que puede utilizarse para crear una implementación. A fin de obtener más información sobre las implementaciones, lee Crear una implementación.

Un archivo de configuración define todos los recursos de Google Cloud que conforman una implementación. Debes tener un archivo de configuración para crear una implementación. Un archivo de configuración debe escribirse en sintaxis YAML.

Antes de comenzar

• Si deseas usar los ejemplos de línea de comandos de esta guía, instala la herramienta de línea de comandos de gcloud.
• Si deseas usar los ejemplos de la API en esta guía, configura el acceso a la API.
• Comprende los conceptos básicos sobre los archivos de configuración.

Estructura del archivo de configuración

Un archivo de configuración se escribe en formato YAML y tiene la siguiente estructura:

#  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

En cada una de las secciones se define una parte diferente de la implementación:

• Las secciones imports son una lista de archivos de plantillas que usará la configuración. De manera recurrente, Deployment Manager expande las plantillas importadas para formar la configuración final.

• La sección resources es una lista de recursos que conforman esta implementación. Un recurso puede ser:

  • Un tipo de base administrado por Google como, por ejemplo, una instancia de VM de Compute Engine.
  • Una plantilla importada
  • Un tipo compuesto.
  • Un proveedor de tipos.

También puedes incluir otras columnas opcionales, como las secciones outputs y metadata. La sección outputs te permite exponer datos de tus plantillas y configuraciones como resultados a fin de que otras plantillas en la misma implementación las consuman o como resultados para tus usuarios finales, mientras que la sección metadata te permite usar otras funciones, como configurar dependencias explícitas entre recursos.

Como mínimo, una configuración siempre debe declarar la sección resources seguida de una lista de recursos. Otras secciones son opcionales.

Declarar un tipo de recurso

Cada recurso en la configuración debe especificarse como un tipo. Los tipos pueden ser un tipo de base administrado por Google, un tipo compuesto, un proveedor de tipos o una plantilla importada.

Los tipos de base administrados por Google son tipos que se resuelven en recursos de Google Cloud. Por ejemplo, una instancia de Cloud SQL o un bucket de Cloud Storage son un tipo de base administrado por Google. Puedes anunciar estos tipos con el uso de la siguiente sintaxis:

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

Por ejemplo, una instancia de Compute Engine tendría el siguiente tipo:

type: compute.v1.instance

Para una base de datos de BigQuery, el tipo podría ser:

type: bigquery.v2.dataset

Para obtener una lista de todos los tipos admitidos, utiliza el siguiente comando:

gcloud deployment-manager types list

Para obtener una lista completa de los tipos de base administrados por Google, consulta Tipos de recursos admitidos.

Si usas un tipo compuesto o un proveedor de tipos, declara el tipo de la siguiente manera:

# Composite type

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

Para un proveedor de tipos:

# Base type

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

También puedes crear recursos con el uso de proveedores de tipos administrados por Google (Beta). Si quieres ver la lista de proveedores de tipos de Google Cloud, consulta Proveedores de tipos compatibles.

Si deseas usar plantillas, declara la plantilla como un tipo, con el nombre de la plantilla o su ruta como el valor de type. Por ejemplo, la siguiente configuración importa un plantilla denominada my_vm_template.jinja y la proporciona como un 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 obtener más información sobre las plantillas, lee Crear una plantilla básica.

Declarar las propiedades del recurso

Después de anunciar el tipo de recurso, también debes asignar un name al recurso y especificar las propiedades que deseas para tal recurso. Por ejemplo, en el siguiente archivo de configuración, se define una instancia de máquina virtual llamada vm-created-by-deployment-manager y sus propiedades deseadas. Deployment Manager usa esta información para crear una instancia de VM que tiene estas propiedades.

# 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 el properties de un recurso, debes usar la documentación de la API del recurso:

• Consulta el formato de solicitud en el método insert o create para el recurso.
• Si el URI de solicitud contiene la zona, agrégala a las propiedades.

• Para los arreglos, utiliza la sintaxis de la lista de YAML a fin de enumerar los elementos del arreglo. Por ejemplo, si estás creando una instancia de Compute Engine mediante la API, debes proporcionar un conjunto de discos para adjuntar a la instancia, en el siguiente formato:

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

  En la configuración de Deployment Manager, agrega estos discos con el uso de la siguiente sintaxis:

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

También puedes proporcionar cualquier propiedad que admita escritura de ese recurso. Para determinar si una propiedad admite escritura, utiliza la documentación de referencia de la API para el tipo de recurso. Por ejemplo, la referencia de Compute Engine marca ciertas propiedades que solo son de salida, por lo que no puedes definir estas propiedades en la configuración, dado que son inmutables.

Algunas API requieren un conjunto mínimo de propiedades para crear un recurso. Un disco persistente de Compute Engine, por ejemplo, requiere el nombre de disco, la fuente de imagen, el tamaño del disco, etc., cuando se crea un disco nuevo. Para obtener información sobre un recurso específico, revisa la referencia de API para ese recurso.

Define propiedades de la plantilla

Si importas una plantilla con el fin de usarla en tu configuración, debes usar la sección properties a fin de definir valores para las propiedades de plantilla en lugar de propiedades de recursos. De manera alternativa, si la plantilla no tiene propiedades de la plantilla, puedes omitir la sección propertiespor completo.

Cómo crear recursos a partir de diferentes servicios de Google Cloud

Por último, con un archivo de configuración, se pueden crear recursos a partir de servicios diferentes de Google Cloud. Por ejemplo, en el siguiente archivo de configuración, se crean recursos a partir de Compute Engine y 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

Propiedades y tipos de recursos admitidos

Consulta la lista completa de recursos administrados por Google en la documentación Tipos de recursos admitidos.

Pasos siguientes

• Obtén vista previa de la configuración antes de que confirmes su implementación.
• Una vez que estés satisfecho con la configuración, utilízala para crear una implementación.
• Por último, debes considerar la reelaboración de los archivos de configuración para usar las plantillas.