Installare le estensioni VM creando policy di estensione

Questo documento descrive come creare policy delle estensioni VM, che consentono di installare e gestire automaticamente le estensioni su un parco risorse di macchine virtuali (VM) Compute Engine. Definendo una policy, puoi assicurarti che estensioni specifiche vengano installate e gestite su tutte le VM che corrispondono ai criteri che specifichi, ad esempio le etichette delle VM. Puoi creare policy delle estensioni VM di zona o globali a livello di progetto o a livello di organizzazione e cartella (disponibili in anteprima).

Prima di iniziare

Limitazioni alla creazione di policy

Puoi creare policy delle estensioni VM con ambito cartella e organizzazione solo utilizzando Google Cloud CLI o l'API REST di Compute Engine.

Priorità delle policy e risoluzione dei conflitti

Quando più policy di diversi livelli della gerarchia (organizzazione, cartella o progetto) si applicano alla stessa VM, il livello della gerarchia non determina la precedenza. Invece, il gestore di estensioni VM utilizza la priorità delle policy e i timestamp di aggiornamento per risolvere i conflitti.

Quando due policy sono in conflitto per la stessa estensione, la policy con la priorità più alta ha la precedenza. I valori di priorità vanno da 0 a 65535, dove un numero inferiore indica una priorità più elevata. La priorità predefinita è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente. L'eliminazione di una policy non rimuove l'estensione se alla VM si applica ancora una policy con priorità inferiore.

Installa le estensioni VM creando una policy di estensione VM globale

Puoi creare una policy di estensione VM globale per installare estensioni sulle VM in più zone in base a un piano di rilascio. Puoi definire una policy globale a livello di progetto o a livello di cartella o organizzazione (disponibile in Anteprima).

Il gestore di estensioni VM non applica una policy di estensione VM globale direttamente alle VM. Al contrario, man mano che la policy viene implementata, il gestore di estensioni VM replica automaticamente la definizione globale nelle policy di zona corrispondenti in ogni zona in base al piano di rilascio. Dopo che una policy replicata diventa disponibile in una zona, gestore di estensioni VM valuta le VM in quella zona in base alle etichette di inclusione della policy e installa o aggiorna le estensioni designate. Quando crei nuove VM, gestore di estensioni VM le valuta e le configura automaticamente.

Piani di rilascio per le policy globali

Le policy di estensione delle VM globali utilizzano i piani di rilascio per gestire il deployment delle estensioni in diverse località. Puoi utilizzare uno dei piani di rilascio predefiniti o crearne uno personalizzato.

Piani di rilascio predefiniti

Puoi selezionare uno dei seguenti piani di rilascio predefiniti:

  • slow_rollout: implementa la policy nell'arco di cinque giorni. Il piano di rilascio predefinito è il rilascio lento.
  • fast_rollout: implementa immediatamente la policy in tutte le zone.

Piani di rilascio personalizzati

Puoi creare piani di rilascio personalizzati utilizzando il metodo rolloutPlans.insert. Ad esempio, il seguente JSON definisce un piano di rilascio denominato test-rollout-plan che ha come target due zone:

{
  "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"
      }
    }
  ]
}

Puoi quindi utilizzare questo piano di rilascio personalizzato quando crei una policy globale.

Installa le estensioni VM in tutte le zone di un'organizzazione

Crea una policy di estensione globale con ambito a livello di organizzazione per installare e gestire le estensioni VM in tutte le zone di tutti i progetti discendenti della tua organizzazione.

Autorizzazioni IAM obbligatorie

Per ottenere l'autorizzazione necessaria per creare una policy di estensione con ambito a livello di organizzazione, chiedi all'amministratore di concederti il ruolo IAM Amministratore delle policy di estensione delle VM di Compute a livello di organizzazione (roles/compute.orgVmExtensionPolicyAdmin) sulla tua organizzazione. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione compute.orgVmExtensionPolicies.create necessaria per creare una policy di estensione con ambito a livello di organizzazione.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per creare una policy di estensione globale con ambito a livello di organizzazione, seleziona una delle seguenti opzioni:

gcloud

Per creare una policy di estensione delle VM globale con ambito a livello di organizzazione, utilizza il comando gcloud preview compute global-vm-extension-policies create con il flag --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

Sostituisci quanto segue:

  • POLICY_NAME: un nome per la policy di estensione della VM.
  • ORGANIZATION_ID: l'ID organizzazione della policy con ambito a livello di organizzazione. Il formato della risorsa è organizations/{organization}/global/vmExtensionPolicies/{name}.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: un elenco separato da virgole di estensioni da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è il percorso del file di configurazione per quell'estensione. Questo file si trova sulla VM in cui esegui il comando gcloud, non sulla VM in cui installi l'estensione.

    In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag --config anziché --config-from-file, ad esempio EXTENSION_NAME_1="CONFIG_1". Puoi utilizzare --config-from-file o --config, ma non entrambi nello stesso comando.

  • KEY_1=VALUE_1: un elenco separato da virgole di coppie chiave-valore che definiscono le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi --inclusion-labels più volte, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti questo flag, la policy ha come target tutte le VM in tutti i progetti e le zone discendenti dell'organizzazione.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.
  • ROLLOUT_PLAN: specifica slow_rollout o fast_rollout. Se devi utilizzare un piano di rilascio personalizzato, specifica il flag --rollout-custom-plan anziché --rollout-predefined-plan utilizzando il seguente formato:
    --rollout-custom-plan=organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Sostituisci quanto segue:

    • ORGANIZATION_ID: l'organizzazione in cui è definito il piano di rilascio.
    • ROLLOUT_PLAN_NAME: il nome del piano di rilascio personalizzato che hai definito.

    Se non specifichi un flag del piano di rilascio, il gestore di estensioni VM utilizza slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: specifica il comportamento quando il gestore di estensioni VM rileva un conflitto tra una policy di zona e una policy globale. Puoi specificare uno dei seguenti comportamenti in caso di conflitto:
    • "" (stringa vuota): la policy globale non sovrascrive le policy di zona in conflitto con lo stesso nome. Questo comportamento in caso di conflitto è quello predefinito.
    • overwrite: la policy globale sovrascrive qualsiasi policy di zona con lo stesso nome, quindi gestisce i rollout delle policy nella zona.

    Per saperne di più, consulta il flag --rollout-conflict-behavior.

Esempio: crea una policy globale con ambito a livello di organizzazione

Il seguente comando crea una policy globale ad alta priorità denominata prod-frontend-policy a livello di organizzazione (organizations/123456789) per i workload di frontend di produzione (env=prod,workload=frontend), bloccando una versione specifica per l'estensione ops-agent con un piano di rilascio lento:

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

Per creare una policy di estensione VM globale con ambito a livello di organizzazione, invia una richiesta POST al metodo 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"
  }
}
}

Sostituisci quanto segue:

  • ORGANIZATION_ID: ID organizzazione.
  • POLICY_NAME: un nome per la policy di estensione della VM.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: il nome dell'estensione da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: la configurazione dell'estensione, fornita come stringa incorporata.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • KEY_1: VALUE_1: una coppia chiave-valore che definisce le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi più instanceSelectors, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti instanceSelectors, la policy ha come target tutte le VM in tutti i progetti e le zone discendenti dell'organizzazione.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.
  • ROLLOUT_CONFLICT_BEHAVIOR: specifica il comportamento quando il gestore di estensioni VM rileva un conflitto tra una policy di zona e una policy globale. Puoi specificare uno dei seguenti comportamenti in caso di conflitto:
    • "" (stringa vuota): la policy globale non sovrascrive le policy di zona in conflitto con lo stesso nome. Questo comportamento in caso di conflitto è quello predefinito.
    • overwrite: la policy globale sovrascrive qualsiasi policy di zona con lo stesso nome, quindi gestisce i rollout delle policy nella zona.

    Per saperne di più, consulta il flag --rollout-conflict-behavior.

  • ROLLOUT_PLAN_NAME: il nome del piano di rilascio personalizzato che hai definito. Per utilizzare un piano di rilascio predefinito, sostituisci il campo name con predefinedRolloutPlan e specifica uno dei seguenti valori:
    • SLOW_ROLLOUT: implementa la policy nell'arco di cinque giorni. Questo piano predefinito è il piano di rilascio predefinito se non ne specifichi uno.
    • FAST_ROLLOUT: implementa immediatamente la policy in tutte le zone.

Esempio: crea una policy globale con ambito a livello di organizzazione

L'esempio seguente crea una policy globale denominata org-global-extension-policy che installa l'estensione ops-agent per l'organizzazione 123456789 sulle VM con etichetta env=prod, con priorità 100 e un piano di rilascio predefinito 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"
  }
}
}

Installa le estensioni VM in tutte le zone di una cartella

Crea una policy di estensione globale con ambito cartella per installare e gestire le estensioni VM in tutte le zone di tutti i progetti discendenti della cartella.

Autorizzazioni IAM obbligatorie

Per ottenere l'autorizzazione necessaria per creare una policy di estensione con ambito cartella, chiedi all'amministratore di concederti il ruolo IAM Amministratore delle policy di estensione delle VM di Compute a livello di cartella (roles/compute.folderVmExtensionPolicyAdmin) nella cartella. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione compute.folderVmExtensionPolicies.create, necessaria per creare una policy delle estensioni con ambito cartella.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per creare una policy di estensione globale con ambito a livello di cartella, seleziona una delle seguenti opzioni:

gcloud

Per creare una policy di estensione VM globale con ambito cartella, utilizza il comando gcloud preview compute global-vm-extension-policies create con il flag --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

Sostituisci quanto segue:

  • POLICY_NAME: un nome per la policy di estensione della VM.
  • FOLDER_ID: l'ID della cartella per la policy con ambito a livello di cartella. Il formato della risorsa è folders/{folder}/global/vmExtensionPolicies/{name}.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: un elenco separato da virgole di estensioni da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è il percorso del file di configurazione per quell'estensione. Questo file si trova sulla VM in cui esegui il comando gcloud, non sulla VM in cui installi l'estensione.

    In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag --config anziché --config-from-file, ad esempio EXTENSION_NAME_1="CONFIG_1". Puoi utilizzare --config-from-file o --config, ma non entrambi nello stesso comando.

  • KEY_1=VALUE_1: un elenco separato da virgole di coppie chiave-valore che definiscono le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi --inclusion-labels più volte, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti questo flag, la policy ha come target tutte le VM in tutti i progetti e le zone discendenti all'interno della cartella.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.
  • ROLLOUT_PLAN: specifica slow_rollout o fast_rollout. Se devi utilizzare un piano di rilascio personalizzato, specifica il flag --rollout-custom-plan anziché --rollout-predefined-plan utilizzando il seguente formato:
    --rollout-custom-plan=folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Sostituisci quanto segue:

    • FOLDER_ID: la cartella in cui è definito il piano di rilascio.
    • ROLLOUT_PLAN_NAME: il nome del piano di rilascio personalizzato che hai definito.

    Se non specifichi un flag del piano di rilascio, il gestore di estensioni VM utilizza slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: specifica il comportamento quando il gestore di estensioni VM rileva un conflitto tra una policy di zona e una policy globale. Puoi specificare uno dei seguenti comportamenti in caso di conflitto:
    • "" (stringa vuota): la policy globale non sovrascrive le policy di zona in conflitto con lo stesso nome. Questo comportamento in caso di conflitto è quello predefinito.
    • overwrite: la policy globale sovrascrive qualsiasi policy di zona con lo stesso nome, quindi gestisce i rollout delle policy nella zona.

    Per saperne di più, consulta il flag --rollout-conflict-behavior.

Esempio: crea una policy globale con ambito cartella

Il seguente comando crea una policy globale denominata folder-global-extension-policy a livello di cartella (folders/123456) che installa l'estensione ops-agent sulle VM con l'etichetta env=prod utilizzando un piano di rilascio lento:

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

Per creare una policy di estensione VM globale con ambito cartella, invia una richiesta POST al metodo 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"
  }
}
}

Sostituisci quanto segue:

  • FOLDER_ID: il tuo ID cartella.
  • POLICY_NAME: un nome per la policy di estensione della VM.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: il nome dell'estensione da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: la configurazione dell'estensione, fornita come stringa incorporata.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • KEY_1: VALUE_1: una coppia chiave-valore che definisce le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi più instanceSelectors, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti instanceSelectors, la policy ha come target tutte le VM in tutti i progetti e le zone discendenti all'interno della cartella.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.
  • ROLLOUT_CONFLICT_BEHAVIOR: specifica il comportamento quando il gestore di estensioni VM rileva un conflitto tra una policy di zona e una policy globale. Puoi specificare uno dei seguenti comportamenti in caso di conflitto:
    • "" (stringa vuota): la policy globale non sovrascrive le policy di zona in conflitto con lo stesso nome. Questo comportamento in caso di conflitto è quello predefinito.
    • overwrite: la policy globale sovrascrive qualsiasi policy di zona con lo stesso nome, quindi gestisce i rollout delle policy nella zona.

    Per saperne di più, consulta il flag --rollout-conflict-behavior.

  • ROLLOUT_PLAN_NAME: il nome del piano di rilascio personalizzato che hai definito. Per utilizzare un piano di rilascio predefinito, sostituisci il campo name con predefinedRolloutPlan e specifica uno dei seguenti valori:
    • SLOW_ROLLOUT: implementa la policy nell'arco di cinque giorni. Questo piano predefinito è il piano di rilascio predefinito se non ne specifichi uno.
    • FAST_ROLLOUT: implementa immediatamente la policy in tutte le zone.

Esempio: crea una policy globale con ambito cartella

L'esempio seguente crea una policy globale denominata folder-global-extension-policy che installa l'estensione ops-agent per la cartella 123456 sulle VM con etichetta env=prod, con priorità 500 e un piano di rilascio predefinito 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"
  }
}
}

Installa le estensioni VM in tutte le zone di un progetto

Crea una policy di estensione globale con ambito a livello di progetto per installare e gestire le estensioni VM in tutte le zone del progetto.

Autorizzazioni IAM obbligatorie

Per ottenere l'autorizzazione necessaria per creare una policy di estensione con ambito a livello di progetto, chiedi all'amministratore di concederti il ruolo IAM Compute VM extension policies admin (roles/compute.vmExtensionPolicyAdmin) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione compute.vmExtensionPolicies.create, necessaria per creare una policy di estensione con ambito a livello di progetto.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per creare una policy di estensione globale con ambito a livello di progetto, seleziona una delle seguenti opzioni:

Console

Per creare una policy di estensione delle VM globale con ambito di progetto nella console Google Cloud , completa i seguenti passaggi:

  1. Nella console Google Cloud , vai alla pagina Policy delle estensioni VM.

    Vai a Policy di estensione VM

  2. Fai clic su Crea policy di estensione.
  3. Nel campo Nome, inserisci un nome per la policy.
  4. (Facoltativo) Nel campo Descrizione, inserisci una descrizione della policy.
  5. Nel campo Priority (Priorità), specifica un numero di priorità per risolvere i conflitti tra le policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000.
  6. Nella sezione Ambito, seleziona Implementazione globale.
  7. Nella sezione Gestisci estensioni, fai clic su Aggiungi estensione e segui questi passaggi per ogni estensione che vuoi installare sulle VM di destinazione:
    1. Seleziona un'estensione dall'elenco Estensione. Per saperne di più, consulta Estensioni supportate.
    2. Dall'elenco Versione, specifica il numero di versione dell'estensione. Lascia vuoto per selezionare l'ultima versione.
      • Per Ops Agent, puoi specificare la versione 2.58.0 o una versione successiva.
      • Per l'estensione per SAP e l'estensione per i workload di computing, lascia il campo vuoto per selezionare l'ultima versione.
    3. (Facoltativo) Nel campo Contenuto del file di configurazione, inserisci i parametri di configurazione per l'estensione.
  8. Nel campo Piano di rilascio, seleziona un piano di rilascio tra le seguenti opzioni:
    • Implementazione lenta: installa le estensioni gradualmente nel parco risorse di VM in un periodo di tempo. Questo piano di rilascio è l'opzione predefinita.
    • Implementazione rapida: installa immediatamente le estensioni su tutte le VM target in tutte le zone e regioni.

    Per saperne di più sui piani di rilascio, consulta Piani di rilascio.

  9. Nella sezione Istanze VM di destinazione, seleziona le VM per la policy. Per selezionare le VM con etichette specifiche, fai clic su Aggiungi etichette e aggiungi la coppia chiave-valore.
  10. Fai clic su Crea.

gcloud

Per creare una policy di estensione VM globale con ambito a livello di progetto, utilizza il comando 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

Sostituisci quanto segue:

  • POLICY_NAME: un nome per la policy di estensione della VM.
  • PROJECT_ID: l'ID progetto per la policy con ambito a livello di progetto.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: un elenco separato da virgole di estensioni da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è il percorso del file di configurazione per quell'estensione. Questo file si trova sulla VM in cui esegui il comando gcloud, non sulla VM in cui installi l'estensione.

    In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag --config anziché --config-from-file, ad esempio EXTENSION_NAME_1="CONFIG_1". Puoi utilizzare --config-from-file o --config, ma non entrambi nello stesso comando.

  • KEY_1=VALUE_1: un elenco separato da virgole di coppie chiave-valore che definiscono le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi --inclusion-labels più volte, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti questo flag, la policy ha come target tutte le VM del progetto in tutte le zone.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.
  • ROLLOUT_PLAN: specifica slow_rollout o fast_rollout. Se devi utilizzare un piano di rilascio personalizzato, specifica il flag --rollout-custom-plan anziché --rollout-predefined-plan utilizzando il seguente formato:
    --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il progetto in cui è definito il piano di rilascio.
    • ROLLOUT_PLAN_NAME: il nome del piano di rilascio personalizzato che hai definito.

    Se non specifichi un flag del piano di rilascio, il gestore di estensioni VM utilizza slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: specifica il comportamento quando il gestore di estensioni VM rileva un conflitto tra una policy di zona e una policy globale. Puoi specificare uno dei seguenti comportamenti in caso di conflitto:
    • "" (stringa vuota): la policy globale non sovrascrive le policy di zona in conflitto con lo stesso nome. Questo comportamento in caso di conflitto è quello predefinito.
    • overwrite: la policy globale sovrascrive qualsiasi policy di zona con lo stesso nome, quindi gestisce i rollout delle policy nella zona.

    Per saperne di più, consulta il flag --rollout-conflict-behavior.

Esempio: Creare una policy globale a livello di progetto

Il seguente comando crea una policy denominata global-test-extension-policy che installa l'estensione ops-agent per il progetto test-project. Il flag --config-from-file specifica il percorso di un file locale contenente una configurazione YAML per Ops Agent, mentre --rollout-predefined-plan specifica il piano 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

Esempio: crea una policy globale con ambito a livello di progetto con un piano di rilascio personalizzato

Il seguente comando crea una policy denominata global-test-extension-policy-2 che installa l'estensione ops-agent per il progetto test-project sulle VM con l'etichetta env=prod. La priorità della policy è impostata su 500 e il flag --config-from-file specifica il percorso di un file locale contenente una configurazione YAML per Ops Agent. Il flag --rollout-custom-plan specifica un piano di rilascio personalizzato.

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

Per creare una policy di estensione VM globale con ambito a livello di progetto, invia una richiesta POST al metodo 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"
  }
}
}

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • POLICY_NAME: un nome per la policy di estensione della VM.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: il nome dell'estensione da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: la configurazione dell'estensione, fornita come stringa incorporata.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • KEY_1: VALUE_1: una coppia chiave-valore che definisce le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi più instanceSelectors, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti instanceSelectors, la policy ha come target tutte le VM del progetto in tutte le zone.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.
  • ROLLOUT_CONFLICT_BEHAVIOR: specifica il comportamento quando il gestore di estensioni VM rileva un conflitto tra una policy di zona e una policy globale. Puoi specificare uno dei seguenti comportamenti in caso di conflitto:
    • "" (stringa vuota): la policy globale non sovrascrive le policy di zona in conflitto con lo stesso nome. Questo comportamento in caso di conflitto è quello predefinito.
    • overwrite: la policy globale sovrascrive qualsiasi policy di zona con lo stesso nome, quindi gestisce i rollout delle policy nella zona.

    Per saperne di più, consulta il flag --rollout-conflict-behavior.

  • PROJECT_NUMBER: il progetto in cui è definito il piano di rilascio personalizzato.
  • ROLLOUT_PLAN_NAME: il nome del piano di rilascio personalizzato che hai definito. Per utilizzare un piano di rilascio predefinito, sostituisci il campo name con predefinedRolloutPlan e specifica uno dei seguenti valori:
    • SLOW_ROLLOUT: implementa la policy nell'arco di cinque giorni. Questo piano predefinito è il piano di rilascio predefinito se non ne specifichi uno.
    • FAST_ROLLOUT: implementa immediatamente la policy in tutte le zone.

Esempio: Creare una policy globale a livello di progetto

L'esempio seguente crea una policy denominata global-test-extension-policy che installa l'estensione ops-agent per il progetto 12345678 sulle VM con l'etichetta env=prod. La priorità della policy è impostata su 500 e utilizza il piano di rilascio 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"
  }
}
}

Installa le estensioni VM creando una policy di estensione VM a livello di zona

Puoi creare una policy di estensione delle VM a livello di zona per definire quali estensioni installare e su quali VM in una zona specifica. Puoi definire una policy a livello di zona a livello di progetto o a livello di cartella o organizzazione (disponibile in Anteprima).

Installa le estensioni VM in una zona di un'organizzazione

Crea una policy di estensione a livello di zona con ambito a livello di organizzazione per installare e gestire le estensioni delle VM in una zona specifica in tutti i progetti discendenti della tua organizzazione.

Autorizzazioni IAM obbligatorie

Per ottenere l'autorizzazione necessaria per creare una policy di estensione con ambito a livello di organizzazione, chiedi all'amministratore di concederti il ruolo IAM Amministratore delle policy di estensione delle VM di Compute a livello di organizzazione (roles/compute.orgVmExtensionPolicyAdmin) sulla tua organizzazione. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione compute.orgVmExtensionPolicies.create necessaria per creare una policy di estensione con ambito a livello di organizzazione.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per creare una policy di estensione a livello di zona con ambito a livello di organizzazione, seleziona una delle seguenti opzioni:

gcloud

Per creare una policy di estensione delle VM di zona con ambito a livello di organizzazione e implementarla nelle VM di una zona specifica, utilizza il comando gcloud preview compute zone-vm-extension-policies create con il flag --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

Sostituisci quanto segue:

  • POLICY_NAME: un nome per la policy di estensione della VM.
  • ORGANIZATION_ID: l'ID organizzazione della policy con ambito a livello di organizzazione. Il formato della risorsa è organizations/{organization}/zones/{zone}/vmExtensionPolicies/{name}.
  • ZONE: la zona in cui si applica questa policy.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: un elenco separato da virgole di estensioni da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è il percorso del file di configurazione per quell'estensione. Questo file si trova sulla VM in cui esegui il comando gcloud, non sulla VM in cui installi l'estensione.

    In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag --config anziché --config-from-file, ad esempio EXTENSION_NAME_1="CONFIG_1". Puoi utilizzare --config-from-file o --config, ma non entrambi nello stesso comando.

  • KEY_1=VALUE_1: un elenco separato da virgole di coppie chiave-valore che definiscono le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi --inclusion-labels più volte, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti questo flag, la policy ha come target tutte le VM nella zona specificata in tutti i progetti discendenti dell'organizzazione.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.

Il comando non va a buon fine se nella zona esiste già una policy con il nome specificato.

Esempio: crea una policy di zona con ambito a livello di organizzazione

Il seguente comando crea una policy di zona denominata org-test-extension-policy che installa l'estensione ops-agent nella zona us-central1-f per l'organizzazione organizations/123456789 sulle VM con etichetta 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

Per creare una policy di estensione delle VM di zona con ambito a livello di organizzazione, invia una richiesta POST al metodo organizationZoneVmExtensionPolicies.insert. Questo metodo definisce quali estensioni installare e su quali VM in una zona specifica dell'organizzazione.

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"
}

Sostituisci quanto segue:

  • ORGANIZATION_ID: ID organizzazione.
  • ZONE: la zona in cui si applica questa policy.
  • POLICY_NAME: un nome per la policy di estensione della VM.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: il nome dell'estensione da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: la configurazione dell'estensione, fornita come stringa incorporata.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • KEY_1: VALUE_1: una coppia chiave-valore che definisce le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi più instanceSelectors, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti instanceSelectors, la policy ha come target tutte le VM nella zona specificata in tutti i progetti discendenti dell'organizzazione.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.

Esempio: crea una policy di zona con ambito a livello di organizzazione

L'esempio seguente crea una policy denominata org-test-extension-policy che installa l'estensione ops-agent nella zona us-central1-f per l'organizzazione 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"
}

Installa le estensioni VM in una zona in una cartella

Crea una policy di estensione a livello di zona con ambito cartella per installare e gestire le estensioni delle VM in una zona specifica in tutti i progetti discendenti della cartella.

Autorizzazioni IAM obbligatorie

Per ottenere l'autorizzazione necessaria per creare una policy di estensione con ambito cartella, chiedi all'amministratore di concederti il ruolo IAM Amministratore delle policy di estensione delle VM di Compute a livello di cartella (roles/compute.folderVmExtensionPolicyAdmin) nella cartella. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione compute.folderVmExtensionPolicies.create, necessaria per creare una policy delle estensioni con ambito cartella.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per creare una policy di estensione a livello di zona con ambito cartella, seleziona una delle seguenti opzioni:

gcloud

Per creare una policy di estensione delle VM di zona con ambito cartella e implementarla nelle VM di una zona specifica, utilizza il comando gcloud preview compute zone-vm-extension-policies create con il flag --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

Sostituisci quanto segue:

  • POLICY_NAME: un nome per la policy di estensione della VM.
  • FOLDER_ID: l'ID della cartella per la policy con ambito a livello di cartella. Il formato della risorsa è folders/{folder}/zones/{zone}/vmExtensionPolicies/{name}.
  • ZONE: la zona in cui si applica questa policy.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: un elenco separato da virgole di estensioni da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è il percorso del file di configurazione per quell'estensione. Questo file si trova sulla VM in cui esegui il comando gcloud, non sulla VM in cui installi l'estensione.

    In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag --config anziché --config-from-file, ad esempio EXTENSION_NAME_1="CONFIG_1". Puoi utilizzare --config-from-file o --config, ma non entrambi nello stesso comando.

  • KEY_1=VALUE_1: un elenco separato da virgole di coppie chiave-valore che definiscono le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi --inclusion-labels più volte, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti questo flag, la policy ha come target tutte le VM nella zona specificata in tutti i progetti discendenti all'interno della cartella.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.

Il comando non va a buon fine se nella zona esiste già una policy con il nome specificato.

Esempio: crea una policy a livello di zona con ambito cartella

Il seguente comando crea una policy di zona denominata folder-test-extension-policy che installa l'estensione ops-agent nella zona us-central1-f per la cartella folders/123456 sulle VM con etichetta 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

Per creare una policy di estensione delle VM di zona con ambito cartella, invia una richiesta POST al metodo folderZoneVmExtensionPolicies.insert. Questo metodo definisce quali estensioni installare e su quali VM in una zona specifica della cartella.

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"
}

Sostituisci quanto segue:

  • FOLDER_ID: il tuo ID cartella.
  • ZONE: la zona in cui si applica questa policy.
  • POLICY_NAME: un nome per la policy di estensione della VM.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: il nome dell'estensione da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: la configurazione dell'estensione, fornita come stringa incorporata.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • KEY_1: VALUE_1: una coppia chiave-valore che definisce le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi più instanceSelectors, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti instanceSelectors, la policy ha come target tutte le VM nella zona specificata in tutti i progetti discendenti all'interno della cartella.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.

Esempio: crea una policy a livello di zona con ambito cartella

L'esempio seguente crea una policy denominata folder-test-extension-policy che installa l'estensione ops-agent nella zona us-central1-f per la cartella 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"
}

Installa le estensioni VM in una zona di un progetto

Crea una policy di estensione a livello di zona con scope del progetto per installare e gestire le estensioni VM in una zona specifica del progetto.

Autorizzazioni IAM obbligatorie

Per ottenere l'autorizzazione necessaria per creare una policy di estensione con ambito a livello di progetto, chiedi all'amministratore di concederti il ruolo IAM Compute VM extension policies admin (roles/compute.vmExtensionPolicyAdmin) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione compute.vmExtensionPolicies.create, necessaria per creare una policy di estensione con ambito a livello di progetto.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per creare una policy di estensione a livello di zona con ambito a livello di progetto, seleziona una delle seguenti opzioni:

Console

Per creare una policy di estensione delle VM di zona con ambito di progetto nella console Google Cloud , completa i seguenti passaggi:

  1. Nella console Google Cloud , vai alla pagina Policy delle estensioni VM.

    Vai a Policy di estensione VM

  2. Fai clic su Crea policy di estensione.
  3. Nel campo Nome, inserisci un nome per la policy.
  4. (Facoltativo) Nel campo Descrizione, inserisci una descrizione della policy.
  5. Nel campo Priority (Priorità), specifica un numero di priorità per risolvere i conflitti tra le policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000.
  6. Nella sezione Ambito, seleziona Implementazione a livello di zona.
  7. Negli elenchi Regione e Zona, seleziona la regione e la zona in cui si trovano le VM. Il gestore di estensioni VM applica la policy alle VM nella regione e nella zona selezionate.
  8. Nella sezione Gestisci estensioni, fai clic su Aggiungi estensione e segui questi passaggi per ogni estensione che vuoi installare sulle VM di destinazione:
    1. Seleziona un'estensione dall'elenco Estensione. Per saperne di più, consulta Estensioni supportate.
    2. Dall'elenco Versione, specifica il numero di versione dell'estensione. Lascia vuoto per selezionare l'ultima versione.
      • Per Ops Agent, puoi specificare la versione 2.58.0 o una versione successiva.
      • Per l'estensione per SAP e l'estensione per i workload di computing, lascia il campo vuoto per selezionare l'ultima versione.
    3. (Facoltativo) Nel campo Contenuto del file di configurazione, inserisci i parametri di configurazione per l'estensione.
  9. Nella sezione Istanze VM di destinazione, seleziona le VM per la policy. Per selezionare le VM con etichette specifiche, fai clic su Aggiungi etichette e aggiungi la coppia chiave-valore.
  10. Fai clic su Crea.

gcloud

Per creare una policy delle estensioni delle VM a livello di zona con scope del progetto e implementarla nelle VM di una zona specifica, utilizza il comando 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

Sostituisci quanto segue:

  • POLICY_NAME: un nome per la policy di estensione della VM.
  • PROJECT_ID: l'ID progetto per la policy con ambito a livello di progetto.
  • ZONE: la zona in cui si applica questa policy.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: un elenco separato da virgole di estensioni da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: un elenco separato da virgole di coppie chiave-valore in cui la chiave è il nome dell'estensione e il valore è il percorso del file di configurazione per quell'estensione. Questo file si trova sulla VM in cui esegui il comando gcloud, non sulla VM in cui installi l'estensione.

    In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag --config anziché --config-from-file, ad esempio EXTENSION_NAME_1="CONFIG_1". Puoi utilizzare --config-from-file o --config, ma non entrambi nello stesso comando.

  • KEY_1=VALUE_1: un elenco separato da virgole di coppie chiave-valore che definiscono le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi --inclusion-labels più volte, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti questo flag, la policy ha come target tutte le VM nella zona specificata all'interno del progetto.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.

Il comando non va a buon fine se nella zona esiste già una policy con il nome specificato.

Esempio: crea una policy di zona con ambito a livello di progetto

Il seguente comando crea una policy denominata test-extension-policy che installa l'estensione ops-agent nella zona us-central1-f per il progetto test-project. Il flag --config-from-file specifica il percorso di un file locale contenente una configurazione YAML per Ops Agent.

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"

Esempio: crea una policy di zona con ambito a livello di progetto con etichette di inclusione e priorità

Il seguente comando crea una policy denominata test-extension-policy-2 che installa l'estensione ops-agent nella zona us-central1-f per il progetto test-project sulle VM con etichetta env=prod. La priorità della policy è impostata su 500 e il flag --config-from-file specifica il percorso di un file locale contenente una configurazione YAML per Ops Agent.

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

Per creare una policy di estensione delle VM di zona con ambito di progetto, invia una richiesta POST al metodo zoneVmExtensionPolicies.insert. Questo metodo definisce quali estensioni installare e su quali VM in una zona specifica.

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"
}

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • ZONE: la zona in cui si applica questa policy.
  • POLICY_NAME: un nome per la policy di estensione della VM.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: il nome dell'estensione da aggiungere alla policy. Devi specificare almeno un'estensione. Puoi specificare una delle seguenti estensioni supportate:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: la configurazione dell'estensione, fornita come stringa incorporata.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: la versione dell'estensione. Se non specifichi una versione per un'estensione, il gestore di estensioni VM utilizza l'ultima versione disponibile ed esegue l'upgrade automatico quando diventano disponibili nuove versioni.
  • KEY_1: VALUE_1: una coppia chiave-valore che definisce le etichette di inclusione per un selettore. Le VM devono avere tutte le etichette specificate in un selettore per essere scelte come target. Se specifichi più instanceSelectors, la policy ha come target le VM che corrispondono a uno dei selettori forniti (OR logico). Se ometti instanceSelectors, la policy ha come target tutte le VM nella zona specificata all'interno del progetto.
  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità della policy. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, il gestore di estensioni VM applica alle VM la policy aggiornata più di recente.

Esempio: crea una policy di zona con ambito a livello di progetto

L'esempio seguente crea una policy denominata test-extension-policy che installa l'estensione ops-agent nella zona us-central1-f per 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"
}

Passaggi successivi