Installare le estensioni VM creando policy di estensione

Questo documento descrive come creare policy di estensione 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 specificati, ad esempio le etichette VM.

Prima di iniziare

Ruoli IAM richiesti

Per ottenere l'autorizzazione necessaria per creare una policy di estensione, chiedi all'amministratore di concederti il ruolo IAM VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin). 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.

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

Per ulteriori informazioni sui ruoli e le autorizzazioni IAM in Compute Engine, consulta Ruoli e autorizzazioni di Compute Engine.

Priorità dei criteri e risoluzione dei conflitti

Quando più policy si applicano alla stessa VM, il gestore di estensioni VM utilizza la priorità delle policy per risolvere i conflitti.

Quando due criteri sono in conflitto per la stessa estensione, ha la precedenza il criterio con priorità più alta. I valori di priorità vanno da 0 a 65535, dove un numero più basso indica una priorità più alta. 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 viene ancora applicata una policy con priorità inferiore.

Crea una policy di estensione VM globale

Puoi creare una policy di estensione VM globale per installare le estensioni sulle VM in più zone all'interno del progetto in base a un piano di implementazione. Una policy di estensione VM globale non viene applicata direttamente alle VM. Man mano che la policy viene implementata, il gestore di estensioni VM crea policy in ogni zona in base al piano di implementazione. Questi criteri gestiscono quindi l'installazione delle estensioni sulle VM all'interno delle rispettive zone.

Puoi utilizzare gcloud o il metodo globalVmExtensionPolicies.insert per creare policy di estensione globali.

Limitazioni

Non puoi creare policy di estensione VM globali utilizzando la console Google Cloud .

Informazioni sui piani di implementazione

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

Piani di implementazione predefiniti

  • slow_rollout: Implementa la policy in cinque giorni. L'implementazione lenta è il piano di implementazione predefinito.
  • fast_rollout: implementa immediatamente la policy in tutte le zone.

Piani di implementazione personalizzati

Puoi creare piani di implementazione personalizzati utilizzando il metodo rolloutPlans.insert. Ad esempio, il seguente JSON definisce un piano di rollout 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 implementazione personalizzato quando crei una policy globale, come mostrato nell'esempio 2.

Crea una policy globale

Per creare una policy di estensione VM globale, utilizza uno dei seguenti metodi.

gcloud

Utilizza il comando gcloud beta compute global-vm-extension-policies create per creare una policy di estensione VM globale:

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --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 VM.
  • DESCRIPTION: una descrizione facoltativa della policy.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: un elenco separato da virgole di estensioni da aggiungere al criterio. Devi specificare almeno un'estensione. I valori validi per le estensioni sono:
    • 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 e la aggiorna automaticamente 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 prese di mira. Se specifichi --inclusion-labels più volte, la policy ha come target le VM che corrispondono a uno qualsiasi dei selettori forniti (operatore logico OR). Se ometti questo flag, la policy ha come target tutte le VM del progetto in tutte le zone.

  • PRIORITY: un numero intero che definisce la priorità del criterio. I numeri più grandi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, viene applicata alle VM la policy aggiornata più di recente.

  • ROLLOUT_PLAN: specifica slow_rollout o fast_rollout. Se devi utilizzare un piano di implementazione personalizzato, utilizza il flag --rollout-custom-plan anziché --rollout-predefined-plan e specifica il nome del piano, ad esempio:

    --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 implementazione.
    • ROLLOUT_PLAN_NAME: il nome del piano di implementazione personalizzato che hai definito. Se non viene specificato alcun flag del piano di implementazione, viene utilizzato slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: specifica il comportamento quando viene rilevato un conflitto tra una policy zonale e una globale. I valori possibili sono:

    • "" (stringa vuota): la policy globale non sovrascrive le policy di zona in conflitto con lo stesso nome. Questo è il comportamento standard.
    • overwrite: la policy globale sovrascrive qualsiasi policy di zona con lo stesso nome, quindi gestisce i rollout delle policy nella zona.

    Per maggiori dettagli, vedi il flag --rollout-conflict-behavior.

Esempio 1

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 l'Ops Agent e --rollout-predefined-plan specifica il piano slow_rollout.

gcloud beta 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 2

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 l'Ops Agent. Il flag --rollout-custom-plan specifica un piano di rollout personalizzato.

 gcloud beta 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, invia una richiesta POST al metodo globalVmExtensionPolicies.insert.

POST https://compute.googleapis.com/compute/beta/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 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. I valori validi per le estensioni sono:
    • 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 e la aggiorna automaticamente 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 prese di mira. Se specifichi più instanceSelectors, la policy ha come target le VM che corrispondono a uno qualsiasi dei selettori forniti (operatore logico OR). Se ometti instanceSelectors, la policy ha come target tutte le VM del progetto in tutte le zone.

  • PRIORITY: un numero intero che definisce la priorità del criterio. I numeri più grandi indicano una priorità più alta. Il valore predefinito è 1000. Se più policy hanno la stessa priorità, viene applicata alle VM la policy aggiornata più di recente.

  • ROLLOUT_CONFLICT_BEHAVIOR: specifica il comportamento quando viene rilevato un conflitto tra una policy zonale e una globale. I valori possibili sono:

    • "" (stringa vuota): la policy globale non sovrascrive le policy di zona in conflitto con lo stesso nome. Questo è il comportamento standard.

    • overwrite: la policy globale sovrascrive qualsiasi policy di zona con lo stesso nome, quindi gestisce i rollout delle policy nella zona.

      Per maggiori dettagli, vedi il flag --rollout-conflict-behavior.

  • PROJECT_NUMBER: il progetto in cui è definito il piano di implementazione personalizzato.

  • ROLLOUT_PLAN_NAME: il nome del piano di implementazione personalizzato che hai definito. Per utilizzare un piano di implementazione predefinito, sostituisci il campo name con predefinedRolloutPlan e specifica uno dei seguenti valori:

    • SLOW_ROLLOUT: implementa la policy in cinque giorni. Questo è il piano di implementazione predefinito se non ne viene specificato nessuno.
    • FAST_ROLLOUT: implementa immediatamente la policy in tutte le zone.

Esempio

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à del criterio è impostata su 500 e utilizza il piano di implementazione test-rollout-plan.

POST https://compute.googleapis.com/compute/beta/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"
    }
  }
}

Crea una policy di estensione VM zonale

Per creare una policy di estensione VM a livello di zona, utilizza uno dei seguenti metodi. Questa policy di zona definisce quali estensioni installare e su quali VM in una zona specifica.

Console

  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. Nell'elenco Zona, seleziona la zona in cui vuoi applicare questa policy.
  7. Nella sezione Estensioni, fai clic su Aggiungi estensione e procedi nel seguente modo per ogni estensione che vuoi installare sulle VM di destinazione:
    1. Seleziona un'estensione dall'elenco Estensione. Consulta Estensioni supportate.
    2. Nell'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 successive.
      • Per l'estensione per SAP e l'estensione per i carichi di lavoro di Compute, lascia vuoto il campo per selezionare l'ultima versione.
    3. (Facoltativo) Nel campo Contenuto del file di configurazione, inserisci i parametri di configurazione per l'estensione.
  8. 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.
  9. Fai clic su Crea.

gcloud

Per creare una policy di estensione VM zonale e implementarla nelle VM in una zona specifica, utilizza il comando gcloud compute zone-vm-extension-policies create:

gcloud compute zone-vm-extension-policies create POLICY_NAME \
    --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 VM.
  • 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 al criterio. Devi specificare almeno un'estensione. I valori validi per le estensioni sono:
    • 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 e la aggiorna automaticamente 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 percorso 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 prese di mira. Se specifichi --inclusion-labels più volte, la policy ha come target le VM che corrispondono a uno qualsiasi dei selettori forniti (operatore logico OR). Se ometti questo flag, la policy ha come target tutte le VM nella zona specificata.

  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità del criterio. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000.

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

Esempio 1

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 l'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 2

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 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 l'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 VM a livello di zona, 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 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. I valori validi per le estensioni sono:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension

  • 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 e la aggiorna automaticamente quando diventano disponibili nuove versioni.

  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: la configurazione dell'estensione, fornita come stringa incorporata.

  • 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 prese di mira. Se specifichi più instanceSelectors, la policy ha come target le VM che corrispondono a uno qualsiasi dei selettori forniti (operatore logico OR). Se ometti instanceSelectors, la policy ha come target tutte le VM nella zona specificata.

  • PRIORITY: un numero intero compreso tra 0 e 65535 che definisce la priorità del criterio. I numeri più bassi indicano una priorità più alta. Il valore predefinito è 1000.

Esempio

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