Créer une configuration de base

Cette page explique comment concevoir une configuration pouvant être utilisée pour créer un déploiement. Pour en savoir plus sur les déploiements, consultez la rubrique Créer un déploiement.

Ce fichier définit toutes les ressources Google Cloud qui composent un déploiement. Vous devez disposer d'un fichier de configuration pour créer un déploiement. Un fichier de configuration doit être écrit en syntaxe YAML.

Avant de commencer

Structure d'un fichier de configuration

Un fichier de configuration est écrit au format YAML. Sa structure est la suivante :

#  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

Chacune des sections définit une partie différente du déploiement :

  • Les sections imports correspondent à une liste de fichiers de modèle qui seront utilisés par la configuration. Deployment Manager développe tous les modèles importés de manière récursive pour former la configuration finale.

  • La section resources contient la liste des ressources qui composent le déploiement. Une ressource peut être :

    • Un type de base géré par Google, par exemple une instance de machine virtuelle Compute Engine ;
    • Un modèle importé ;
    • Un type composite ;
    • Un fournisseur de type.

Vous pouvez également inclure certaines sections facultatives, telles que les sections outputs et metadata. La section outputs permet d'exposer les données de vos modèles et configurations en tant que sorties. Les autres modèles du même déploiement pourront ainsi les "consommer", tout comme les utilisateurs finaux. La section metadata permet quant à elle d'utiliser des fonctionnalités supplémentaires. Par exemple, vous pouvez configurer des dépendances explicites entre les ressources.

Au minimum, une configuration doit toujours déclarer la section resources, laquelle doit être suivie d'une liste de ressources. Les autres sections sont facultatives.

Déclarer un type de ressource

Chaque ressource intégrée à une configuration doit être spécifiée en tant que type. Les types disponibles sont les suivants : type de base géré par Google, type composite, fournisseur de type et modèle importé.

Les types de base gérés par Google sont des types liés à des ressources Google Cloud. Les instances Cloud SQL et les buckets Cloud Storage en sont deux exemples. Vous pouvez déclarer ces types en utilisant la syntaxe suivante :

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

Pour une instance Compute Engine, vous pourriez utiliser le type suivant :

type: compute.v1.instance

Le type spécifié pour une base de données BigQuery pourrait être :

type: bigquery.v2.dataset

Pour obtenir la liste de tous les types acceptés, exécutez la commande suivante :

gcloud deployment-manager types list

Pour obtenir la liste complète des types de base gérés par Google, consultez la page Types de ressources acceptés.

Si vous utilisez un type composite ou un fournisseur de types, déclarez le type comme suit :

# Composite type

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

Pour un fournisseur de types :

# Base type

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

Vous pouvez également créer des ressources à l'aide des fournisseurs de types gérés par Google (en version bêta). Pour obtenir la liste des fournisseurs de types Google Cloud, consultez Fournisseurs de types pris en charge.

Si vous souhaitez utiliser des modèles, déclarez-les en tant que types. Définissez le nom du modèle ou son chemin comme valeur de type. Par exemple, la configuration suivante importe un modèle appelé my-template.jinja (chemin : my_vm_template.jinja) et le fournit en tant que type :

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

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

Pour plus d'informations sur les modèles, consultez la section Créer un modèle de base.

Déclarer les propriétés d'une ressource

Après avoir déclaré le type d'une ressource, vous devez également attribuer un nom (name) à la ressource et définir les propriétés que vous souhaitez pour elle. Par exemple, le fichier de configuration suivant définit une instance de machine virtuelle appelée vm-created-by-deployment-manager, ainsi que les propriétés choisies pour cette instance. Deployment Manager utilise ces informations pour créer une instance de VM qui comporte ces propriétés.

# 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

Pour définir les propriétés (properties) d'une ressource, reportez-vous à la documentation de l'API correspondant à cette ressource :

  • Examinez le format de la requête dans la méthode insert ou create.
  • Si l'URI de la requête contient la zone, ajoutez cette dernière aux propriétés.
  • Utilisez la syntaxe de liste YAML pour répertorier les éléments du tableau. Par exemple, si vous créez une instance Compute Engine à l'aide de l'API, vous devez fournir un tableau de disques à associer à l'instance, au format suivant :

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

    Dans votre configuration Deployment Manager, vous ajoutez ces disques à l'aide de la syntaxe suivante :

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

Vous pouvez également fournir n'importe quelle propriété accessible en écriture pour cette ressource. Pour déterminer si une propriété est accessible en écriture, reportez-vous à la documentation de référence de l'API correspondant au type de la ressource. Par exemple, la documentation de référence Compute Engine indique que certaines propriétés sont uniquement disponibles en sortie (lecture seule). Vous ne pouvez pas définir ces propriétés dans votre configuration, car elles sont immuables.

Certaines API nécessitent un ensemble de propriétés minimal pour créer une ressource. Par exemple, pour créer un disque persistant Compute Engine, vous devez préciser le nom du disque, la source de l'image système, la taille du disque, etc. Pour en savoir plus sur une ressource spécifique, consultez la documentation de référence de l'API correspondant à cette ressource.

Définir les propriétés d'un modèle

Pour importer un modèle que vous souhaitez utiliser dans votre configuration, vous devez définir les valeurs des propriétés du modèle (au lieu des propriétés de la ressource) dans la section properties. Si vous utilisez un modèle sans propriétés, sachez que vous n'avez pas besoin de vous préoccuper de la section properties.

Créer des ressources à partir de différents services Google Cloud

Enfin, un fichier de configuration peut créer des ressources à partir de différents services Google Cloud. Par exemple, le fichier de configuration suivant crée des ressources à partir de Compute Engine et de 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

Types de ressources et propriétés pris en charge

La liste complète des ressources gérées par Google prises en charge est disponible dans la documentation Types de ressources pris en charge.

Étapes suivantes