Installer des extensions de VM en créant des règles d'extension

Ce document explique comment créer des règles d'extension de VM, qui vous permettent d'installer et de gérer automatiquement des extensions sur un parc de machines virtuelles (VM) Compute Engine. En définissant une règle, vous pouvez vous assurer que des extensions spécifiques sont installées et gérées sur toutes les VM qui répondent aux critères que vous spécifiez, tels que les libellés de VM. Vous pouvez créer des règles d'extension de VM zonales ou globales au niveau du projet, ou au niveau de l'organisation et du dossier (disponible en preview).

Avant de commencer

Limites de la création de règles

Vous ne pouvez créer des règles d'extension de VM au niveau du dossier et de l'organisation qu'à l'aide de la Google Cloud CLI ou de l'API REST Compute Engine.

Priorité des règles et résolution des conflits

Lorsque plusieurs règles de différents niveaux hiérarchiques (organisation, dossier ou projet) s'appliquent à la même VM, le niveau hiérarchique ne détermine pas la priorité. À la place, VM Extension Manager utilise la priorité des règles et les codes temporels de mise à jour pour résoudre les conflits.

Lorsque deux règles sont en conflit pour la même extension, la règle dont la priorité est la plus élevée prévaut. Les valeurs de priorité sont comprises entre 0 et 65535. Plus le nombre est petit, plus la priorité est élevée. La priorité par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment. La suppression d'une règle ne supprime pas l'extension si une règle de priorité inférieure s'applique toujours à la VM.

Installer des extensions de VM en créant une règle d'extension de VM globale

Vous pouvez créer une règle d'extension de VM globale pour installer des extensions sur des VM dans plusieurs zones selon un plan de déploiement. Vous pouvez définir une stratégie globale au niveau du projet, ou au niveau du dossier ou de l'organisation (disponible en preview).

VM Extension Manager n'applique pas directement une règle d'extension de VM globale aux VM. Au lieu de cela, à mesure que la règle est déployée, VM Extension Manager réplique automatiquement la définition globale dans les règles zonales correspondantes de chaque zone, en fonction du plan de déploiement. Une fois qu'une règle répliquée est disponible dans une zone, VM Extension Manager évalue les VM de cette zone par rapport aux étiquettes d'inclusion de la règle, puis installe ou met à jour les extensions désignées. Lorsque vous créez des VM, VM Extension Manager les évalue et les configure automatiquement.

Plans de déploiement des règles globales

Les règles d'extension de VM globales utilisent des plans de déploiement pour gérer le déploiement des extensions dans différents emplacements. Vous pouvez utiliser l'un des plans de déploiement prédéfinis ou créer un plan de déploiement personnalisé.

Plans de déploiement prédéfinis

Vous pouvez sélectionner l'un des plans de déploiement prédéfinis suivants :

  • slow_rollout : déploie la règle sur cinq jours. Le déploiement lent est le plan de déploiement par défaut.
  • fast_rollout : déploie immédiatement la stratégie dans toutes les zones.

Plans de déploiement personnalisés

Vous pouvez créer des plans de déploiement personnalisés à l'aide de la méthode rolloutPlans.insert. Par exemple, le code JSON suivant définit un plan de déploiement nommé test-rollout-plan qui cible deux zones :

{
  "name": "test-rollout-plan",
  "waves": [
    {
      "selectors": [
        {
          "locationSelector": {
            "includedLocations": [
              "us-central1-a",
              "us-west1-a"
            ]
          }
        }
      ],
      "validation": {
        "type": "time",
        "timeBasedValidationMetadata": {
          "waitDuration": "0s"
        }
      },
      "orchestrationOptions": {
        "maxConcurrentResourcesPerLocation": "10",
        "maxConcurrentLocations": "10"
      }
    }
  ]
}

Vous pouvez ensuite utiliser ce plan de déploiement personnalisé lorsque vous créez une règle globale.

Installer des extensions de VM dans toutes les zones d'une organisation

Créez une règle d'extension globale au niveau de l'organisation pour installer et gérer les extensions de VM dans toutes les zones de tous les projets descendants de votre organisation.

Autorisations IAM requises

Pour obtenir l'autorisation nécessaire pour créer une règle d'extension au niveau de l'organisation, demandez à votre administrateur de vous accorder le rôle IAM Administrateur des règles d'extension des VM Compute au niveau de l'organisation (roles/compute.orgVmExtensionPolicyAdmin) sur votre organisation. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation compute.orgVmExtensionPolicies.create, qui est nécessaire pour créer une règle d'extension au niveau de l'organisation.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour créer une règle d'extension globale au niveau de l'organisation, sélectionnez l'une des options suivantes :

gcloud

Pour créer une règle d'extension de VM globale au niveau de l'organisation, utilisez la commande gcloud preview compute global-vm-extension-policies create avec l'option --organization :

gcloud preview compute global-vm-extension-policies create POLICY_NAME \
  --organization=organizations/ORGANIZATION_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR

Remplacez les éléments suivants :

  • POLICY_NAME : nom de la règle d'extension de VM.
  • ORGANIZATION_ID : ID d'organisation pour la stratégie limitée à l'organisation. Le format de la ressource est organizations/{organization}/global/vmExtensionPolicies/{name}.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1,EXTENSION_NAME_2 : liste d'extensions à ajouter à la règle, séparées par une virgule. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est la version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est le chemin d'accès au fichier de configuration de cette extension. Ce fichier se trouve sur la VM sur laquelle vous exécutez la commande gcloud, et non sur la VM sur laquelle vous installez l'extension.

    Vous pouvez également fournir la configuration sous forme de chaîne intégrée en utilisant l'option --config au lieu de --config-from-file (par exemple, EXTENSION_NAME_1="CONFIG_1"). Vous pouvez utiliser --config-from-file ou --config, mais pas les deux dans la même commande.

  • KEY_1=VALUE_1 : liste de paires clé/valeur séparées par une virgule qui définissent les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez --inclusion-labels plusieurs fois, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (OU logique). Si vous omettez cette option, la règle cible toutes les VM de tous les projets et zones descendants de l'organisation.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.
  • ROLLOUT_PLAN : spécifiez slow_rollout ou fast_rollout. Si vous devez utiliser un plan de déploiement personnalisé, spécifiez l'option --rollout-custom-plan au lieu de --rollout-predefined-plan au format suivant : 
    --rollout-custom-plan=organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Remplacez les éléments suivants :

    • ORGANIZATION_ID : organisation dans laquelle le plan de déploiement est défini.
    • ROLLOUT_PLAN_NAME : nom du plan de déploiement personnalisé que vous avez défini.

    Si vous ne spécifiez pas d'option de plan de déploiement, VM Extension Manager utilise slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR : spécifie le comportement lorsque VM Extension Manager détecte un conflit entre une règle zonale et une règle globale. Vous pouvez spécifier l'un des comportements de conflit suivants :
    • "" (chaîne vide) : la règle globale n'écrase pas les règles zonales en conflit portant le même nom. Il s'agit du comportement par défaut en cas de conflit.
    • overwrite : la stratégie globale écrase toute stratégie zonale portant le même nom, puis gère les déploiements de stratégies dans la zone.

    Pour en savoir plus, consultez la section concernant l'option --rollout-conflict-behavior.

Exemple : Créer une stratégie globale au niveau de l'organisation

La commande suivante crée une règle globale de priorité élevée nommée prod-frontend-policy au niveau de l'organisation (organizations/123456789) pour les charges de travail d'interface de production (env=prod,workload=frontend), en épinglant une version spécifique pour l'extension ops-agent avec un plan de déploiement lent :

gcloud preview compute global-vm-extension-policies create prod-frontend-policy \
  --organization=organizations/123456789 \
  --description="Standard monitoring policy for production frontend VMs" \
  --extensions=ops-agent \
  --version=ops-agent=2.58.0 \
  --config=ops-agent="some-monitoring-config" \
  --inclusion-labels="env=prod,workload=frontend" \
  --priority=100 \
  --rollout-predefined-plan=slow_rollout

REST

Pour créer une règle d'extension de VM globale au niveau de l'organisation, envoyez une requête POST à la méthode organizationGlobalVmExtensionPolicies.insert :

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/ORGANIZATION_ID/global/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Remplacez les éléments suivants :

  • ORGANIZATION_ID : votre ID d'organisation.
  • POLICY_NAME : nom de la règle d'extension de VM.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1, EXTENSION_NAME_2 : nom de l'extension à ajouter à la règle. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG : configuration de l'extension, fournie sous forme de chaîne intégrée.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION : version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • KEY_1: VALUE_1 : paire clé-valeur qui définit les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez plusieurs instanceSelectors, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (opérateur logique OU). Si vous omettez instanceSelectors, la règle cible toutes les VM de l'ensemble des projets et zones descendants de l'organisation.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.
  • ROLLOUT_CONFLICT_BEHAVIOR : spécifie le comportement lorsque VM Extension Manager détecte un conflit entre une règle zonale et une règle globale. Vous pouvez spécifier l'un des comportements de conflit suivants :
    • "" (chaîne vide) : la règle globale n'écrase pas les règles zonales en conflit portant le même nom. Il s'agit du comportement par défaut en cas de conflit.
    • overwrite : la stratégie globale écrase toute stratégie zonale portant le même nom, puis gère les déploiements de stratégies dans la zone.

    Pour en savoir plus, consultez la section concernant l'option --rollout-conflict-behavior.

  • ROLLOUT_PLAN_NAME : nom du plan de déploiement personnalisé que vous avez défini. Pour utiliser un plan de déploiement prédéfini, remplacez le champ name par predefinedRolloutPlan et spécifiez l'une des valeurs suivantes :
    • SLOW_ROLLOUT : déploie la règle sur cinq jours. Ce plan prédéfini est le plan de déploiement par défaut si vous n'en spécifiez pas.
    • FAST_ROLLOUT : déploie immédiatement la stratégie dans toutes les zones.

Exemple : Créer une stratégie globale au niveau de l'organisation

L'exemple suivant crée une règle globale nommée org-global-extension-policy qui installe l'extension ops-agent pour l'organisation 123456789 sur les VM portant l'étiquette env=prod, avec la priorité 100 et un plan de déploiement prédéfini SLOW_ROLLOUT :

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/123456789/global/vmExtensionPolicies

{
"name": "org-global-extension-policy",
"description": "Standard monitoring policy for organization VMs",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "100",
"rolloutOperation": {
  "rolloutInput": {
    "predefinedRolloutPlan": "SLOW_ROLLOUT"
  }
}
}

Installer des extensions de VM dans toutes les zones d'un dossier

Créez une règle d'extension globale limitée à un dossier pour installer et gérer des extensions de VM dans toutes les zones de tous les projets descendants de votre dossier.

Autorisations IAM requises

Pour obtenir l'autorisation nécessaire pour créer une règle d'extension au niveau du dossier, demandez à votre administrateur de vous accorder le rôle IAM Administrateur des règles d'extension de VM Compute au niveau du dossier (roles/compute.folderVmExtensionPolicyAdmin) sur votre dossier. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation compute.folderVmExtensionPolicies.create, qui est nécessaire pour créer une règle d'extension limitée à un dossier.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour créer une stratégie d'extension globale limitée à un dossier, sélectionnez l'une des options suivantes :

gcloud

Pour créer une règle d'extension de VM globale limitée à un dossier, utilisez la commande gcloud preview compute global-vm-extension-policies create avec l'option --folder :

gcloud preview compute global-vm-extension-policies create POLICY_NAME \
  --folder=folders/FOLDER_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR

Remplacez les éléments suivants :

  • POLICY_NAME : nom de la règle d'extension de VM.
  • FOLDER_ID : ID du dossier pour la stratégie limitée au dossier. Le format de la ressource est folders/{folder}/global/vmExtensionPolicies/{name}.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1,EXTENSION_NAME_2 : liste d'extensions à ajouter à la règle, séparées par une virgule. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est la version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est le chemin d'accès au fichier de configuration de cette extension. Ce fichier se trouve sur la VM sur laquelle vous exécutez la commande gcloud, et non sur la VM sur laquelle vous installez l'extension.

    Vous pouvez également fournir la configuration sous forme de chaîne intégrée en utilisant l'option --config au lieu de --config-from-file (par exemple, EXTENSION_NAME_1="CONFIG_1"). Vous pouvez utiliser --config-from-file ou --config, mais pas les deux dans la même commande.

  • KEY_1=VALUE_1 : liste de paires clé/valeur séparées par une virgule qui définissent les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez --inclusion-labels plusieurs fois, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (OU logique). Si vous omettez cette option, la règle cible toutes les VM de tous les projets et zones descendants du dossier.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.
  • ROLLOUT_PLAN : spécifiez slow_rollout ou fast_rollout. Si vous devez utiliser un plan de déploiement personnalisé, spécifiez l'option --rollout-custom-plan au lieu de --rollout-predefined-plan au format suivant : 
    --rollout-custom-plan=folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Remplacez les éléments suivants :

    • FOLDER_ID : dossier dans lequel le plan de déploiement est défini.
    • ROLLOUT_PLAN_NAME : nom du plan de déploiement personnalisé que vous avez défini.

    Si vous ne spécifiez pas d'option de plan de déploiement, VM Extension Manager utilise slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR : spécifie le comportement lorsque VM Extension Manager détecte un conflit entre une règle zonale et une règle globale. Vous pouvez spécifier l'un des comportements de conflit suivants :
    • "" (chaîne vide) : la règle globale n'écrase pas les règles zonales en conflit portant le même nom. Il s'agit du comportement par défaut en cas de conflit.
    • overwrite : la stratégie globale écrase toute stratégie zonale portant le même nom, puis gère les déploiements de stratégies dans la zone.

    Pour en savoir plus, consultez la section concernant l'option --rollout-conflict-behavior.

Exemple : Créer une stratégie globale limitée à un dossier

La commande suivante crée une règle globale nommée folder-global-extension-policy au niveau du dossier (folders/123456) qui installe l'extension ops-agent sur les VM portant l'étiquette env=prod à l'aide d'un plan de déploiement lent :

gcloud preview compute global-vm-extension-policies create folder-global-extension-policy \
  --folder=folders/123456 \
  --description="Standard monitoring policy for folder VMs" \
  --extensions=ops-agent \
  --version=ops-agent=2.58.0 \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --inclusion-labels="env=prod" \
  --priority=100 \
  --rollout-predefined-plan=slow_rollout

REST

Pour créer une règle d'extension de VM globale limitée à un dossier, envoyez une requête POST à la méthode folderGlobalVmExtensionPolicies.insert :

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/FOLDER_ID/global/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Remplacez les éléments suivants :

  • FOLDER_ID : l'ID de votre dossier.
  • POLICY_NAME : nom de la règle d'extension de VM.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1, EXTENSION_NAME_2 : nom de l'extension à ajouter à la règle. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG : configuration de l'extension, fournie sous forme de chaîne intégrée.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION : version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • KEY_1: VALUE_1 : paire clé-valeur qui définit les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez plusieurs instanceSelectors, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (opérateur logique OU). Si vous omettez instanceSelectors, la règle cible toutes les VM de l'ensemble des projets et zones descendants du dossier.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.
  • ROLLOUT_CONFLICT_BEHAVIOR : spécifie le comportement lorsque VM Extension Manager détecte un conflit entre une règle zonale et une règle globale. Vous pouvez spécifier l'un des comportements de conflit suivants :
    • "" (chaîne vide) : la règle globale n'écrase pas les règles zonales en conflit portant le même nom. Il s'agit du comportement par défaut en cas de conflit.
    • overwrite : la stratégie globale écrase toute stratégie zonale portant le même nom, puis gère les déploiements de stratégies dans la zone.

    Pour en savoir plus, consultez la section concernant l'option --rollout-conflict-behavior.

  • ROLLOUT_PLAN_NAME : nom du plan de déploiement personnalisé que vous avez défini. Pour utiliser un plan de déploiement prédéfini, remplacez le champ name par predefinedRolloutPlan et spécifiez l'une des valeurs suivantes :
    • SLOW_ROLLOUT : déploie la règle sur cinq jours. Ce plan prédéfini est le plan de déploiement par défaut si vous n'en spécifiez pas.
    • FAST_ROLLOUT : déploie immédiatement la stratégie dans toutes les zones.

Exemple : Créer une stratégie globale limitée à un dossier

L'exemple suivant crée une règle globale nommée folder-global-extension-policy qui installe l'extension ops-agent pour le dossier 123456 sur les VM portant l'étiquette env=prod, avec la priorité 500 et un plan de déploiement prédéfini SLOW_ROLLOUT :

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/123456/global/vmExtensionPolicies

{
"name": "folder-global-extension-policy",
"description": "Test extension policy for Ops Agent at folder level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "500",
"rolloutOperation": {
  "rolloutInput": {
    "predefinedRolloutPlan": "SLOW_ROLLOUT"
  }
}
}

Installer des extensions de VM dans toutes les zones d'un projet

Créez une règle d'extension globale à l'échelle du projet pour installer et gérer des extensions de VM dans toutes les zones de votre projet.

Autorisations IAM requises

Pour obtenir l'autorisation nécessaire pour créer une règle d'extension au niveau du projet, demandez à votre administrateur de vous accorder le rôle IAM Administrateur des règles d'extension de VM Compute (roles/compute.vmExtensionPolicyAdmin) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation compute.vmExtensionPolicies.create, qui est nécessaire pour créer une stratégie d'extension limitée au projet.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour créer une règle d'extension globale limitée au projet, sélectionnez l'une des options suivantes :

Console

Pour créer une règle d'extension de VM globale au niveau du projet dans la console Google Cloud , procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Règles d'extension de VM.

    Accéder aux règles d'extension de VM

  2. Cliquez sur Créer une règle d'extension.
  3. Dans le champ Nom, saisissez un nom pour la stratégie.
  4. (Facultatif) Dans le champ Description, saisissez une description de la stratégie.
  5. Dans le champ Priorité, spécifiez un numéro de priorité pour résoudre les conflits entre les règles. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000.
  6. Dans la section Champ d'application, sélectionnez Déploiement mondial.
  7. Dans la section Gérer les extensions, cliquez sur Ajouter une extension et procédez comme suit pour chaque extension que vous souhaitez installer sur les VM cibles :
    1. Dans la liste Extension, sélectionnez une extension. Pour en savoir plus, consultez Extensions compatibles.
    2. Dans la liste Version, spécifiez le numéro de version de l'extension. Laissez ce champ vide pour sélectionner la dernière version.
      • Pour l'agent Ops, vous pouvez spécifier la version 2.58.0 ou une version ultérieure.
      • Pour Extension for SAP et Extension for Compute Workloads, laissez le champ vide pour sélectionner la dernière version.
    3. (Facultatif) Dans le champ Contenu du fichier de configuration, saisissez les paramètres de configuration de l'extension.
  8. Dans le champ Plan de déploiement, sélectionnez un plan de déploiement parmi les options suivantes :
    • Déploiement lent : installe les extensions progressivement sur votre parc de VM sur une période donnée. Ce plan de déploiement est l'option par défaut.
    • Déploiement rapide : installe immédiatement les extensions sur toutes les VM ciblées dans l'ensemble des zones et régions.

    Pour en savoir plus sur les plans de déploiement, consultez Plans de déploiement.

  9. Dans la section Instances de VM cibles, sélectionnez les VM pour la règle. Pour sélectionner des VM avec des étiquettes spécifiques, cliquez sur Ajouter des étiquettes et ajoutez la paire clé-valeur.
  10. Cliquez sur Créer.

gcloud

Pour créer une règle d'extension de VM globale limitée au projet, utilisez la commande gcloud compute global-vm-extension-policies create :

gcloud compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR

Remplacez les éléments suivants :

  • POLICY_NAME : nom de la règle d'extension de VM.
  • PROJECT_ID : ID du projet pour la règle limitée au projet.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1,EXTENSION_NAME_2 : liste d'extensions à ajouter à la règle, séparées par une virgule. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est la version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est le chemin d'accès au fichier de configuration de cette extension. Ce fichier se trouve sur la VM sur laquelle vous exécutez la commande gcloud, et non sur la VM sur laquelle vous installez l'extension.

    Vous pouvez également fournir la configuration sous forme de chaîne intégrée en utilisant l'option --config au lieu de --config-from-file (par exemple, EXTENSION_NAME_1="CONFIG_1"). Vous pouvez utiliser --config-from-file ou --config, mais pas les deux dans la même commande.

  • KEY_1=VALUE_1 : liste de paires clé/valeur séparées par une virgule qui définissent les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez --inclusion-labels plusieurs fois, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (OU logique). Si vous omettez cette option, la règle cible toutes les VM de votre projet dans toutes les zones.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.
  • ROLLOUT_PLAN : spécifiez slow_rollout ou fast_rollout. Si vous devez utiliser un plan de déploiement personnalisé, spécifiez l'option --rollout-custom-plan au lieu de --rollout-predefined-plan au format suivant : 
    --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Remplacez les éléments suivants :

    • PROJECT_NUMBER : projet dans lequel le plan de déploiement est défini.
    • ROLLOUT_PLAN_NAME : nom du plan de déploiement personnalisé que vous avez défini.

    Si vous ne spécifiez pas d'option de plan de déploiement, VM Extension Manager utilise slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR : spécifie le comportement lorsque VM Extension Manager détecte un conflit entre une règle zonale et une règle globale. Vous pouvez spécifier l'un des comportements de conflit suivants :
    • "" (chaîne vide) : la règle globale n'écrase pas les règles zonales en conflit portant le même nom. Il s'agit du comportement par défaut en cas de conflit.
    • overwrite : la stratégie globale écrase toute stratégie zonale portant le même nom, puis gère les déploiements de stratégies dans la zone.

    Pour en savoir plus, consultez la section concernant l'option --rollout-conflict-behavior.

Exemple : Créer une règle globale limitée au projet

La commande suivante crée une règle nommée global-test-extension-policy qui installe l'extension ops-agent pour le projet test-project. L'option --config-from-file spécifie le chemin d'accès à un fichier local contenant une configuration YAML pour l'agent Ops, et --rollout-predefined-plan spécifie le plan slow_rollout.

gcloud compute global-vm-extension-policies create global-test-extension-policy \
  --project=test-project \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --rollout-predefined-plan=slow_rollout

Exemple : Créer une règle globale limitée au projet avec un plan de déploiement personnalisé

La commande suivante crée une règle nommée global-test-extension-policy-2 qui installe l'extension ops-agent pour le projet test-project sur les VM portant l'étiquette env=prod. La priorité de la règle est définie sur 500, et l'option --config-from-file spécifie le chemin d'accès à un fichier local contenant une configuration YAML pour l'agent Ops. L'option --rollout-custom-plan spécifie un plan de déploiement personnalisé.

gcloud compute global-vm-extension-policies create global-test-extension-policy-2 \
  --project=test-project \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod \
  --rollout-custom-plan=projects/12345678/locations/global/rolloutPlans/test-rollout-plan

REST

Pour créer une règle d'extension de VM globale limitée au projet, envoyez une requête POST à la méthode globalVmExtensionPolicies.insert.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet.
  • POLICY_NAME : nom de la règle d'extension de VM.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1, EXTENSION_NAME_2 : nom de l'extension à ajouter à la règle. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG : configuration de l'extension, fournie sous forme de chaîne intégrée.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION : version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • KEY_1: VALUE_1 : paire clé-valeur qui définit les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez plusieurs instanceSelectors, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (opérateur logique OU). Si vous omettez instanceSelectors, la règle cible toutes les VM de votre projet dans toutes les zones.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.
  • ROLLOUT_CONFLICT_BEHAVIOR : spécifie le comportement lorsque VM Extension Manager détecte un conflit entre une règle zonale et une règle globale. Vous pouvez spécifier l'un des comportements de conflit suivants :
    • "" (chaîne vide) : la règle globale n'écrase pas les règles zonales en conflit portant le même nom. Il s'agit du comportement par défaut en cas de conflit.
    • overwrite : la stratégie globale écrase toute stratégie zonale portant le même nom, puis gère les déploiements de stratégies dans la zone.

    Pour en savoir plus, consultez la section concernant l'option --rollout-conflict-behavior.

  • PROJECT_NUMBER : projet dans lequel le plan de déploiement personnalisé est défini.
  • ROLLOUT_PLAN_NAME : nom du plan de déploiement personnalisé que vous avez défini. Pour utiliser un plan de déploiement prédéfini, remplacez le champ name par predefinedRolloutPlan et spécifiez l'une des valeurs suivantes :
    • SLOW_ROLLOUT : déploie la règle sur cinq jours. Ce plan prédéfini est le plan de déploiement par défaut si vous n'en spécifiez pas.
    • FAST_ROLLOUT : déploie immédiatement la stratégie dans toutes les zones.

Exemple : Créer une règle globale limitée au projet

L'exemple suivant crée une règle nommée global-test-extension-policy qui installe l'extension ops-agent pour le projet 12345678 sur les VM portant l'étiquette env=prod. La priorité de la règle est définie sur 500 et utilise le plan de déploiement test-rollout-plan.

POST https://compute.googleapis.com/compute/v1/projects/12345678/global/vmExtensionPolicies

{
"name": "global-test-extension-policy",
"description": "Test extension policy for Ops Agent",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "500",
"rolloutOperation": {
  "rolloutInput": {
    "name": "projects/12345678/locations/global/rolloutPlans/test-rollout-plan"
  }
}
}

Installer des extensions de VM en créant une règle d'extension de VM zonale

Vous pouvez créer une règle d'extension de VM zonale pour définir les extensions à installer et sur quelles VM d'une zone spécifique. Vous pouvez définir une règle zonale au niveau du projet, ou au niveau du dossier ou de l'organisation (disponible en version preview).

Installer des extensions de VM dans une zone d'une organisation

Créez une règle d'extension zonale au niveau de l'organisation pour installer et gérer des extensions de VM dans une zone spécifique sur tous les projets descendants de votre organisation.

Autorisations IAM requises

Pour obtenir l'autorisation nécessaire pour créer une règle d'extension au niveau de l'organisation, demandez à votre administrateur de vous accorder le rôle IAM Administrateur des règles d'extension des VM Compute au niveau de l'organisation (roles/compute.orgVmExtensionPolicyAdmin) sur votre organisation. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation compute.orgVmExtensionPolicies.create, qui est nécessaire pour créer une règle d'extension au niveau de l'organisation.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour créer une règle d'extension zonale au niveau de l'organisation, sélectionnez l'une des options suivantes :

gcloud

Pour créer une règle d'extension de VM zonale au niveau de l'organisation et la déployer sur les VM d'une zone spécifique, utilisez la commande gcloud preview compute zone-vm-extension-policies create avec l'option --organization :

gcloud preview compute zone-vm-extension-policies create POLICY_NAME \
  --organization=organizations/ORGANIZATION_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Remplacez les éléments suivants :

  • POLICY_NAME : nom de la règle d'extension de VM.
  • ORGANIZATION_ID : ID d'organisation pour la stratégie limitée à l'organisation. Le format de la ressource est organizations/{organization}/zones/{zone}/vmExtensionPolicies/{name}.
  • ZONE : zone où cette règle s'applique.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1,EXTENSION_NAME_2 : liste d'extensions à ajouter à la règle, séparées par une virgule. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est la version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est le chemin d'accès au fichier de configuration de cette extension. Ce fichier se trouve sur la VM sur laquelle vous exécutez la commande gcloud, et non sur la VM sur laquelle vous installez l'extension.

    Vous pouvez également fournir la configuration sous forme de chaîne intégrée en utilisant l'option --config au lieu de --config-from-file (par exemple, EXTENSION_NAME_1="CONFIG_1"). Vous pouvez utiliser --config-from-file ou --config, mais pas les deux dans la même commande.

  • KEY_1=VALUE_1 : liste de paires clé/valeur séparées par une virgule qui définissent les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez --inclusion-labels plusieurs fois, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (OU logique). Si vous omettez cette option, la règle cible toutes les VM de la zone spécifiée dans tous les projets descendants de l'organisation.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.

La commande échoue si une stratégie portant le nom spécifié existe déjà dans la zone.

Exemple : Créer une règle zonale au niveau de l'organisation

La commande suivante crée une règle zonale nommée org-test-extension-policy qui installe l'extension ops-agent dans la zone us-central1-f pour l'organisation organizations/123456789 sur les VM portant l'étiquette env=prod :

gcloud preview compute zone-vm-extension-policies create org-test-extension-policy \
  --organization=organizations/123456789 \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=100 \
  --inclusion-labels=env=prod

REST

Pour créer une règle d'extension de VM zonale au niveau de l'organisation, envoyez une requête POST à la méthode organizationZoneVmExtensionPolicies.insert. Cette méthode définit les extensions à installer et sur quelles VM d'une zone spécifique de l'organisation.

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/ORGANIZATION_ID/zones/ZONE/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Remplacez les éléments suivants :

  • ORGANIZATION_ID : votre ID d'organisation.
  • ZONE : zone où cette règle s'applique.
  • POLICY_NAME : nom de la règle d'extension de VM.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1, EXTENSION_NAME_2 : nom de l'extension à ajouter à la règle. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG : configuration de l'extension, fournie sous forme de chaîne intégrée.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION : version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • KEY_1: VALUE_1 : paire clé-valeur qui définit les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez plusieurs instanceSelectors, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (opérateur logique OU). Si vous omettez instanceSelectors, la règle cible toutes les VM de la zone spécifiée dans tous les projets descendants de l'organisation.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.

Exemple : Créer une règle zonale au niveau de l'organisation

L'exemple suivant crée une règle nommée org-test-extension-policy qui installe l'extension ops-agent dans la zone us-central1-f pour l'organisation 123456789.

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/123456789/zones/us-central1-f/vmExtensionPolicies

{
"name": "org-test-extension-policy",
"description": "Test extension policy for Ops Agent at organization level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "100"
}

Installer des extensions de VM dans une zone d'un dossier

Créez une règle d'extension zonale limitée à un dossier pour installer et gérer des extensions de VM dans une zone spécifique sur tous les projets descendants de votre dossier.

Autorisations IAM requises

Pour obtenir l'autorisation nécessaire pour créer une règle d'extension au niveau du dossier, demandez à votre administrateur de vous accorder le rôle IAM Administrateur des règles d'extension de VM Compute au niveau du dossier (roles/compute.folderVmExtensionPolicyAdmin) sur votre dossier. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation compute.folderVmExtensionPolicies.create, qui est nécessaire pour créer une règle d'extension limitée à un dossier.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour créer une règle d'extension zonale limitée à un dossier, sélectionnez l'une des options suivantes :

gcloud

Pour créer une règle d'extension de VM zonale limitée à un dossier et la déployer sur les VM d'une zone spécifique, utilisez la commande gcloud preview compute zone-vm-extension-policies create avec l'option --folder :

gcloud preview compute zone-vm-extension-policies create POLICY_NAME \
  --folder=folders/FOLDER_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Remplacez les éléments suivants :

  • POLICY_NAME : nom de la règle d'extension de VM.
  • FOLDER_ID : ID du dossier pour la stratégie limitée au dossier. Le format de la ressource est folders/{folder}/zones/{zone}/vmExtensionPolicies/{name}.
  • ZONE : zone où cette règle s'applique.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1,EXTENSION_NAME_2 : liste d'extensions à ajouter à la règle, séparées par une virgule. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est la version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est le chemin d'accès au fichier de configuration de cette extension. Ce fichier se trouve sur la VM sur laquelle vous exécutez la commande gcloud, et non sur la VM sur laquelle vous installez l'extension.

    Vous pouvez également fournir la configuration sous forme de chaîne intégrée en utilisant l'option --config au lieu de --config-from-file (par exemple, EXTENSION_NAME_1="CONFIG_1"). Vous pouvez utiliser --config-from-file ou --config, mais pas les deux dans la même commande.

  • KEY_1=VALUE_1 : liste de paires clé/valeur séparées par une virgule qui définissent les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez --inclusion-labels plusieurs fois, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (OU logique). Si vous omettez cette option, la règle cible toutes les VM de la zone spécifiée dans tous les projets descendants du dossier.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.

La commande échoue si une stratégie portant le nom spécifié existe déjà dans la zone.

Exemple : Créer une règle zonale limitée à un dossier

La commande suivante crée une règle zonale nommée folder-test-extension-policy qui installe l'extension ops-agent dans la zone us-central1-f pour le dossier folders/123456 sur les VM portant l'étiquette env=prod :

gcloud preview compute zone-vm-extension-policies create folder-test-extension-policy \
  --folder=folders/123456 \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod

REST

Pour créer une règle d'extension de VM zonale limitée à un dossier, envoyez une requête POST à la méthode folderZoneVmExtensionPolicies.insert. Cette méthode définit les extensions à installer et sur quelles VM d'une zone spécifique du dossier.

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/FOLDER_ID/zones/ZONE/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Remplacez les éléments suivants :

  • FOLDER_ID : l'ID de votre dossier.
  • ZONE : zone où cette règle s'applique.
  • POLICY_NAME : nom de la règle d'extension de VM.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1, EXTENSION_NAME_2 : nom de l'extension à ajouter à la règle. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG : configuration de l'extension, fournie sous forme de chaîne intégrée.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION : version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • KEY_1: VALUE_1 : paire clé-valeur qui définit les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez plusieurs instanceSelectors, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (opérateur logique OU). Si vous omettez instanceSelectors, la règle cible toutes les VM de la zone spécifiée dans tous les projets descendants du dossier.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.

Exemple : Créer une règle zonale limitée à un dossier

L'exemple suivant crée une règle nommée folder-test-extension-policy qui installe l'extension ops-agent dans la zone us-central1-f pour le dossier 123456.

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/123456/zones/us-central1-f/vmExtensionPolicies

{
"name": "folder-test-extension-policy",
"description": "Test extension policy for Ops Agent at folder level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "test"
       }
    }
  }
],
"priority": "500"
}

Installer des extensions de VM dans une zone d'un projet

Créez une règle d'extension zonale limitée au projet pour installer et gérer des extensions de VM dans une zone spécifique de votre projet.

Autorisations IAM requises

Pour obtenir l'autorisation nécessaire pour créer une règle d'extension au niveau du projet, demandez à votre administrateur de vous accorder le rôle IAM Administrateur des règles d'extension de VM Compute (roles/compute.vmExtensionPolicyAdmin) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation compute.vmExtensionPolicies.create, qui est nécessaire pour créer une stratégie d'extension limitée au projet.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour créer une règle d'extension zonale limitée à un projet, sélectionnez l'une des options suivantes :

Console

Pour créer une règle d'extension de VM zonale limitée au projet dans la console Google Cloud , procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Règles d'extension de VM.

    Accéder aux règles d'extension de VM

  2. Cliquez sur Créer une règle d'extension.
  3. Dans le champ Nom, saisissez un nom pour la stratégie.
  4. (Facultatif) Dans le champ Description, saisissez une description de la stratégie.
  5. Dans le champ Priorité, spécifiez un numéro de priorité pour résoudre les conflits entre les règles. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000.
  6. Dans la section Champ d'application, sélectionnez Déploiement zonal.
  7. Dans les listes Région et Zone, sélectionnez la région et la zone où se trouvent vos VM. VM Extension Manager applique la règle aux VM de la région et de la zone sélectionnées.
  8. Dans la section Gérer les extensions, cliquez sur Ajouter une extension et procédez comme suit pour chaque extension que vous souhaitez installer sur les VM cibles :
    1. Dans la liste Extension, sélectionnez une extension. Pour en savoir plus, consultez Extensions compatibles.
    2. Dans la liste Version, spécifiez le numéro de version de l'extension. Laissez ce champ vide pour sélectionner la dernière version.
      • Pour l'agent Ops, vous pouvez spécifier la version 2.58.0 ou une version ultérieure.
      • Pour Extension for SAP et Extension for Compute Workloads, laissez le champ vide pour sélectionner la dernière version.
    3. (Facultatif) Dans le champ Contenu du fichier de configuration, saisissez les paramètres de configuration de l'extension.
  9. Dans la section Instances de VM cibles, sélectionnez les VM pour la règle. Pour sélectionner des VM avec des étiquettes spécifiques, cliquez sur Ajouter des étiquettes et ajoutez la paire clé-valeur.
  10. Cliquez sur Créer.

gcloud

Pour créer une règle d'extension de VM zonale limitée au projet et la déployer sur les VM d'une zone spécifique, utilisez la commande gcloud compute zone-vm-extension-policies create :

gcloud compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Remplacez les éléments suivants :

  • POLICY_NAME : nom de la règle d'extension de VM.
  • PROJECT_ID : ID du projet pour la règle limitée au projet.
  • ZONE : zone où cette règle s'applique.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1,EXTENSION_NAME_2 : liste d'extensions à ajouter à la règle, séparées par une virgule. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est la version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 : liste de paires clé/valeur séparées par une virgule, où la clé est le nom de l'extension et la valeur est le chemin d'accès au fichier de configuration de cette extension. Ce fichier se trouve sur la VM sur laquelle vous exécutez la commande gcloud, et non sur la VM sur laquelle vous installez l'extension.

    Vous pouvez également fournir la configuration sous forme de chaîne intégrée en utilisant l'option --config au lieu de --config-from-file (par exemple, EXTENSION_NAME_1="CONFIG_1"). Vous pouvez utiliser --config-from-file ou --config, mais pas les deux dans la même commande.

  • KEY_1=VALUE_1 : liste de paires clé/valeur séparées par une virgule qui définissent les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez --inclusion-labels plusieurs fois, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (OU logique). Si vous omettez cette option, la règle cible toutes les VM de la zone spécifiée dans votre projet.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.

La commande échoue si une stratégie portant le nom spécifié existe déjà dans la zone.

Exemple : Créer une règle zonale au niveau du projet

La commande suivante crée une règle nommée test-extension-policy qui installe l'extension ops-agent dans la zone us-central1-f pour le projet test-project. L'option --config-from-file spécifie le chemin d'accès à un fichier local contenant une configuration YAML pour l'agent Ops.

gcloud compute zone-vm-extension-policies create test-extension-policy \
  --project=test-project \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml"

Exemple : Créer une règle zonale limitée au projet avec des libellés d'inclusion et une priorité

La commande suivante crée une règle nommée test-extension-policy-2 qui installe l'extension ops-agent dans la zone us-central1-f pour le projet test-project sur les VM portant l'étiquette env=prod. La priorité de la règle est définie sur 500, et l'option --config-from-file spécifie le chemin d'accès à un fichier local contenant une configuration YAML pour l'agent Ops.

gcloud compute zone-vm-extension-policies create test-extension-policy-2 \
  --project=test-project \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod

REST

Pour créer une règle d'extension de VM zonale limitée au projet, envoyez une requête POST à la méthode zoneVmExtensionPolicies.insert. Cette méthode définit les extensions à installer et sur quelles VM d'une zone spécifique.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet.
  • ZONE : zone où cette règle s'applique.
  • POLICY_NAME : nom de la règle d'extension de VM.
  • DESCRIPTION : description facultative de la règle.
  • EXTENSION_NAME_1, EXTENSION_NAME_2 : nom de l'extension à ajouter à la règle. Vous devez spécifier au moins une extension. Vous pouvez spécifier l'une des extensions compatibles suivantes :
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG : configuration de l'extension, fournie sous forme de chaîne intégrée.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION : version de l'extension. Si vous ne spécifiez pas de version pour une extension, VM Extension Manager utilise la dernière version disponible et la met automatiquement à niveau lorsque de nouvelles versions sont disponibles.
  • KEY_1: VALUE_1 : paire clé-valeur qui définit les étiquettes d'inclusion d'un sélecteur. Les VM doivent comporter toutes les étiquettes spécifiées dans un sélecteur pour être ciblées. Si vous spécifiez plusieurs instanceSelectors, la règle cible les VM qui correspondent à l'un des sélecteurs fournis (opérateur logique OU). Si vous omettez instanceSelectors, la règle cible toutes les VM de la zone spécifiée dans votre projet.
  • PRIORITY : entier compris entre 0 et 65535 qui définit la priorité de la stratégie. Plus le nombre est faible, plus la priorité est élevée. La valeur par défaut est 1000. Si plusieurs règles ont la même priorité, VM Extension Manager applique aux VM la règle mise à jour le plus récemment.

Exemple : Créer une règle zonale au niveau du projet

L'exemple suivant crée une règle nommée test-extension-policy qui installe l'extension ops-agent dans la zone us-central1-f pour my-project.

POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/vmExtensionPolicies

{
"name": "test-extension-policy",
"description": "Test extension policy for Ops Agent",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "test"
       }
    }
  }
],
"priority": "500"
}

Étapes suivantes