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
- Rivedi le nozioni di base su gestore di estensioni VM.
- Esamina le quote del gestore di estensioni VM.
- Esamina i prezzi del gestore di estensioni VM. Il gestore di estensioni VM è disponibile senza costi aggiuntivi, ma l'utilizzo delle estensioni installate dalle policy potrebbe comportare addebiti.
- Abilita l'API Compute Engine nel tuo progetto Google Cloud , se non è già abilitata.
- Assicurati che sulla VM sia in esecuzione la versione dell'agente guest
20241209.01o successiva. - Per visualizzare i log di debug per gli eventi del gestore di estensioni VM, configura le impostazioni dei log per l'agente guest.
-
Se non l'hai ancora fatto, configura l'autenticazione.
L'autenticazione verifica la tua identità per l'accesso ad API e servizi Google Cloud . Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:
Seleziona la scheda relativa al modo in cui prevedi di utilizzare gli esempi in questa pagina:
Console
Quando utilizzi la console Google Cloud per accedere ai servizi e alle API Google Cloud , non devi configurare l'autenticazione.
gcloud
-
Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il comando seguente:
gcloud init
-
- Imposta una regione e una zona predefinite.
REST
Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.
Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata.
Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .
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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, non sulla VM in cui installi l'estensione.In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag
--configanziché--config-from-file, ad esempioEXTENSION_NAME_1="CONFIG_1". Puoi utilizzare--config-from-fileo--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-labelspiù 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 tra0e65535che 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: specificaslow_rolloutofast_rollout. Se devi utilizzare un piano di rilascio personalizzato, specifica il flag--rollout-custom-plananziché--rollout-predefined-planutilizzando 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-agentgoogle-cloud-sap-extensiongoogle-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 omettiinstanceSelectors, la policy ha come target tutte le VM in tutti i progetti e le zone discendenti dell'organizzazione.PRIORITY: un numero intero compreso tra0e65535che 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 camponameconpredefinedRolloutPlane 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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, non sulla VM in cui installi l'estensione.In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag
--configanziché--config-from-file, ad esempioEXTENSION_NAME_1="CONFIG_1". Puoi utilizzare--config-from-fileo--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-labelspiù 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 tra0e65535che 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: specificaslow_rolloutofast_rollout. Se devi utilizzare un piano di rilascio personalizzato, specifica il flag--rollout-custom-plananziché--rollout-predefined-planutilizzando 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-agentgoogle-cloud-sap-extensiongoogle-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 omettiinstanceSelectors, 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 tra0e65535che 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 camponameconpredefinedRolloutPlane 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:
- Nella console Google Cloud , vai alla pagina Policy delle estensioni VM.
- Fai clic su Crea policy di estensione.
- Nel campo Nome, inserisci un nome per la policy.
- (Facoltativo) Nel campo Descrizione, inserisci una descrizione della policy.
- 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. - Nella sezione Ambito, seleziona Implementazione globale.
- Nella sezione Gestisci estensioni, fai clic su Aggiungi estensione e segui questi passaggi per ogni estensione che vuoi installare sulle VM di destinazione:
- Seleziona un'estensione dall'elenco Estensione. Per saperne di più, consulta Estensioni supportate.
- 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.0o 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.
- Per Ops Agent, puoi specificare la versione
- (Facoltativo) Nel campo Contenuto del file di configurazione, inserisci i parametri di configurazione per l'estensione.
- 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.
- 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.
- 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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, non sulla VM in cui installi l'estensione.In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag
--configanziché--config-from-file, ad esempioEXTENSION_NAME_1="CONFIG_1". Puoi utilizzare--config-from-fileo--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-labelspiù 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 tra0e65535che 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: specificaslow_rolloutofast_rollout. Se devi utilizzare un piano di rilascio personalizzato, specifica il flag--rollout-custom-plananziché--rollout-predefined-planutilizzando 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-agentgoogle-cloud-sap-extensiongoogle-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 omettiinstanceSelectors, la policy ha come target tutte le VM del progetto in tutte le zone.PRIORITY: un numero intero compreso tra0e65535che 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 camponameconpredefinedRolloutPlane 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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, non sulla VM in cui installi l'estensione.In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag
--configanziché--config-from-file, ad esempioEXTENSION_NAME_1="CONFIG_1". Puoi utilizzare--config-from-fileo--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-labelspiù 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 tra0e65535che 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-agentgoogle-cloud-sap-extensiongoogle-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 omettiinstanceSelectors, la policy ha come target tutte le VM nella zona specificata in tutti i progetti discendenti dell'organizzazione.PRIORITY: un numero intero compreso tra0e65535che 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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, non sulla VM in cui installi l'estensione.In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag
--configanziché--config-from-file, ad esempioEXTENSION_NAME_1="CONFIG_1". Puoi utilizzare--config-from-fileo--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-labelspiù 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 tra0e65535che 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-agentgoogle-cloud-sap-extensiongoogle-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 omettiinstanceSelectors, 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 tra0e65535che 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:
- Nella console Google Cloud , vai alla pagina Policy delle estensioni VM.
- Fai clic su Crea policy di estensione.
- Nel campo Nome, inserisci un nome per la policy.
- (Facoltativo) Nel campo Descrizione, inserisci una descrizione della policy.
- 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. - Nella sezione Ambito, seleziona Implementazione a livello di zona.
- 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.
- Nella sezione Gestisci estensioni, fai clic su Aggiungi estensione e segui questi passaggi per ogni estensione che vuoi installare sulle VM di destinazione:
- Seleziona un'estensione dall'elenco Estensione. Per saperne di più, consulta Estensioni supportate.
- 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.0o 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.
- Per Ops Agent, puoi specificare la versione
- (Facoltativo) Nel campo Contenuto del file di configurazione, inserisci i parametri di configurazione per l'estensione.
- 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.
- 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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, non sulla VM in cui installi l'estensione.In alternativa, per fornire la configurazione come stringa incorporata, utilizza il flag
--configanziché--config-from-file, ad esempioEXTENSION_NAME_1="CONFIG_1". Puoi utilizzare--config-from-fileo--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-labelspiù 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 tra0e65535che 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-agentgoogle-cloud-sap-extensiongoogle-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 omettiinstanceSelectors, la policy ha come target tutte le VM nella zona specificata all'interno del progetto.PRIORITY: un numero intero compreso tra0e65535che 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
- Per esaminare l'avanzamento dell'implementazione e lo stato di integrità delle estensioni, consulta Visualizza i dettagli e lo stato delle estensioni VM.
- Per modificare le impostazioni di configurazione, cambiare le versioni bloccate o rimuovere gli agenti di cui è stato eseguito il deployment, consulta Gestisci le estensioni VM utilizzando le policy delle estensioni.
- Per creare dashboard di Cloud Monitoring e configurare avvisi per l'integrità dell'agente, l'utilizzo della CPU e della memoria utilizzata, consulta Monitora le estensioni VM.
- Per diagnosticare i rollout non riusciti, controllare i processi guest in esecuzione o ispezionare i log di debug dell'agente guest, consulta Risolvi i problemi relativi alle estensioni VM.