Utilizzare le policy dell'agente (GA)

Crea e gestisci le policy dell'agente utilizzando il gruppo di comandi gcloud compute instances ops-agents policies in Google Cloud CLI o il modulo Terraform ops-agent-policy. Le policy dell'agente utilizzano la suite di strumenti VM Manager in Compute Engine per gestire le policy del sistema operativo, che possono automatizzare il deployment e la manutenzione delle configurazioni software come l'Ops Agent. Queste norme non possono essere applicate all'agente Monitoring legacy o all'agente Logging legacy.

Le policy dell'agente GA utilizzano le risorse di assegnazione delle policy del sistema operativo nell'API OS Config. Sebbene esista un gruppo di comandi gcloud CLI generale per la gestione delle assegnazioni delle policy del sistema operativo, gcloud compute os-config os-policy-assignments, il gruppo di comandi gcloud compute instances ops-agents policies è progettato specificamente per le policy dell'agente descritte in questo documento.

Prima di iniziare

Il modulo Terraform ops-agent-policy è basato sui comandi gcloud compute instances ops-agents policies di Google Cloud SDK. Per informazioni su come funziona Terraform, consulta Utilizzo di Terraform.

Prima di utilizzare Google Cloud CLI o il modulo Terraform per creare criteri agente, completa i seguenti passaggi:

  1. Se utilizzerai i comandi gcloud compute instances ops-agents policies e se non l'hai ancora fatto, installa Google Cloud CLI.

  2. Se utilizzerai il modulo Terraform, segui questi passaggi:

    1. Per informazioni sull'installazione di Terraform, consulta Installare e configurare Terraform. Cloud Shell ha già installato Terraform.

    2. Clona il repository terraform-google-cloud-operations, che contiene il modulo ops-agent-policy:

      git clone https://github.com/terraform-google-modules/terraform-google-cloud-operations

  3. Scarica ed esegui lo script prepare-for-ops-agents-policies.sh per abilitare le API richieste e impostare le autorizzazioni appropriate per l'utilizzo di Google Cloud CLI o Terraform.

    Per informazioni sullo script, vedi Lo script prepare-for-ops-agents-policies.sh.

Disinstalla l'agente Monitoring e l'agente Logging legacy

Se stai creando una policy per l'Ops Agent, assicurati che sulle tue VM non siano installati l'agente Logging o l'agente Monitoring legacy. L'esecuzione dell'Ops Agent e degli agenti legacy sulla stessa VM può causare l'importazione di log duplicati o un conflitto nell'importazione delle metriche. Se necessario, disinstalla l'agente Monitoring e disinstalla l'agente Logging prima di creare una norma per installare Ops Agent.

Verifica che l'agente OS Config sia installato

Potrebbe essere necessario installare e configurare manualmente l'agente OS Config sulle VM precedenti a OS Config. Per informazioni sull'installazione e la verifica manuale dell'agente OS Config, consulta l'elenco di controllo per la verifica di VM Manager.

Trovare i valori per le informazioni sul sistema operativo

Se vuoi applicare le policy dell'agente a sistemi operativi o versioni specifici, devi conoscere i valori utilizzati da OS Config per farvi riferimento.

Per trovare i valori per i campi osShortName e osVersion per una VM, utilizza i seguenti comandi:

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^ShortName: "

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^Version: "

Questi comandi richiedono l'installazione dell'agente OS Config sulla VM.

Crea una policy dell'agente per gestire Ops Agent

Riga di comando

Per creare una policy dell'agente, utilizza il comando gcloud compute instances ops-agents policies create. Questo comando ha la seguente struttura:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone ZONE \
  --file path/to/policy-description-file.yaml \
  --project PROJECT_ID

Quando utilizzi questo comando, sostituisci le variabili nel seguente modo:

  • POLICY_ID è un nome per la tua policy.
  • ZONE è una zona di Compute Engine. Le policy dell'agente vengono applicate solo alle VM nella zona specificata; per applicare una policy in più zone, devi creare più policy.
  • path/to/policy-description-file.yaml è il percorso di un file YAML che descrive la policy. Per informazioni sulla struttura di questo file, consulta Descrivere le policy degli agenti.
  • PROJECT_ID è l'ID del tuo progetto Google Cloud .

Per informazioni sugli altri comandi del gruppo di comandi e sulle opzioni disponibili, consulta la documentazione di gcloud compute instances ops-agents policies.

Descrivere le policy dell'agente

Fornisci le informazioni sui criteri a gcloud compute instances ops-agents policies create creando un file YAML che descrive i criteri e passando questo file al comando come valore dell'opzione --file.

Questa sezione descrive la struttura del file di descrizione delle norme. Per ulteriori informazioni, consulta File di descrizione delle policy di esempio.

Formato del file YAML di descrizione delle policy

Il file di descrizione di una policy dell'agente deve includere due gruppi di campi:

  • agentsRule, che indica alla policy dell'agente se installare o rimuovere Ops Agent e specifica la versione di Ops Agent su cui operare.

  • instanceFilter, che descrive le VM su cui applicare la policy.

Struttura del gruppo di campi agentsRule

Il gruppo di campi agentsRule ha la seguente struttura:

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y
  • Il campo packageState indica alla policy lo stato previsto dell'Ops Agents. I valori validi sono installed e removed.

  • Il campo version indica la versione di Ops Agent da installare o rimuovere. Puoi specificare i seguenti valori:

    • latest è la versione più recente di Ops Agent.
    • 2.*.* è la release più recente della versione principale 2 di Ops Agent.
    • 2.x.y indica una release specifica della versione principale 2.

    Per informazioni sulle versioni disponibili dell'Ops Agent, consulta il repository GitHub dell'agente.

Struttura del gruppo di campi instanceFilter

Il gruppo di campi instanceFilter indica le VM in una zona a cui si applica il filtro. Questo gruppo di campi è una rappresentazione YAML della InstanceFilter struttura utilizzata dalla risorsa OSPolicyAssignment nell'API OS Config.

Il gruppo di campi instanceFilter ha una delle seguenti strutture:

  • Per applicare la policy dell'agente a tutte le VM in una zona, utilizza il seguente comando:

    instanceFilter:
  all: True

    Se utilizzi il filtro all: True, non puoi specificare altri criteri.

  • Per applicare il criterio dell'agente a un insieme specifico di VM in una zona, descrivi le VM utilizzando una combinazione di uno qualsiasi dei seguenti elementi:

    • Etichette sulla VM, per l'inclusione o l'esclusione:
      • inclusionLabels:
      • exclusionLabels:
    • Sistema operativo: inventories:

    Ad esempio, il seguente filtro applica la policy dell'agente alle VM con i sistemi operativi specificati che hanno l'etichetta "env=prod" e non hanno l'etichetta "app=web":

    instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  exclusionLabels:
  - labels:
      app: web
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

    Per informazioni su come trovare i valori del sistema operativo, vedi Trovare informazioni sul sistema operativo.

Terraform

Per creare una policy dell'agente completamente personalizzata, utilizza il modulo ops-agent-policy nella directory modules del repository terraform-google-cloud-operations. Questo modulo richiede le stesse informazioni del comando gcloud compute instances ops-agents policies create. Per una descrizione di tutti i campi utilizzati per descrivere una policy dell'agente, seleziona la scheda Riga di comando.

La directory examples nel repository terraform-google-cloud-operations contiene file che forniscono molte delle variabili necessarie al modulo ops-agent-policy. Per saperne di più, consulta Esempi di configurazioni delle policy.

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per informazioni su come funziona Terraform, consulta Utilizzo di Terraform.

Verificare lo stato dei criteri dell'agente

Questa sezione descrive come controllare lo stato delle policy create e l'installazione dell&#39Ops Agents. Queste informazioni possono anche aiutarti a risolvere i problemi relativi alle norme per gli agenti.

Pagina Policy OS di Compute Engine

La pagina Policy del sistema operativo di Compute Engine fornisce informazioni sulle policy dell'agente che gestiscono Ops Agent e sulle VM nella scheda Istanze VM. Ad esempio:

  • La colonna Stato indica se un criterio è stato installato correttamente ("Conforme"), è in corso ("In attesa"), potrebbe non essere stato installato ("Sconosciuto") o è mancante ("Nessun criterio").
  • La colonna VM monitorata indica se Ops Agent è gestito da OS Config ("Monitorato") o meno ("Non monitorato").

    Se un criterio è "Conforme", ma la VM mostra "Non monitorata", allora potrebbe esserci un problema con l'installazione di Ops Agent. Ad esempio, potresti avere già installato un agente legacy.

Nella console Google Cloud , vai alla pagina Policy del sistema operativo:

Vai a Policy del sistema operativo

Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Compute Engine.

La scheda Istanze VM nella scheda Policy del sistema operativo di Compute Engine mostra informazioni sugli agenti gestiti da tutte le policy del sistema operativo nel tuo progettoGoogle Cloud . Questi criteri sono etichettati come goog-ops-agent-policy.

  • L'indicatore goog-ops-agent-policy include diversi tipi di norme:

    Per distinguere le policy, utilizza la scheda Assegnazioni delle policy del sistema operativo nella pagina per visualizzare gli ID policy di tutte le assegnazioni delle policy nel tuo progetto Google Cloud .

  • Questa colonna VM monitorata non riflette l'installazione di Ops Agent con altri mezzi, ad esempio l'installazione manuale o tramite norme per gli agenti beta.

Pagina Istanze VM di Cloud Monitoring

La pagina Istanze VM in Cloud Monitoring include una colonna Agente che elenca l'agente installato su ogni VM e, per Ops Agent, include un indicatore per gli agenti installati che sono precedenti all'ultima versione.

Nella console Google Cloud , vai alla pagina Dashboard istanze VM:

Vai alla dashboard Istanze VM

Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

Configurazioni dei criteri di esempio

Questa sezione descrive esempi di configurazione delle policy dell'agente quando utilizzi Google Cloud SDK o Terraform.

Riga di comando

Esempi di file di descrizione delle norme

Questa sezione fornisce alcuni esempi di file YAML di descrizione delle policy per una serie di scenari. Gli esempi presuppongono che tu inserisca il codice YAML in un file denominato agent-policy-description.yaml e che tu crei il criterio nella zona us-central1-a utilizzando un comando come il seguente:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone us-central1-a \
  --file agent-policy-description.yaml \
  --project PROJECT_ID

Installa su tutte le VM

Per installare l'ultima versione di Ops Agent su tutte le VM nella zona us-central1-a, utilizza la seguente descrizione della policy:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  all: True

Rimuovi da tutte le VM

Per rimuovere l'ultima versione di Ops Agent su tutte le VM nella zona us-central1-a, utilizza la seguente descrizione della policy:

agentsRule:
  packageState: removed
  version: latest
instanceFilter:
  all: True

Installazione su VM in base alle etichette

Per installare l'ultima versione di Ops Agent su tutte le VM nella zona us-central1-a con l'etichetta "env=prod" o "app=web", utilizza la seguente descrizione della policy:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  - labels:
      app: web

Quando specifichi più voci labels: per l'inclusione o l'esclusione, una VM corrisponde se è presente una delle etichette; ovvero, i set di etichette per l'inclusione o l'esclusione vengono abbinati come operazione logica OR, non come operazione logica AND.

Installare sulle VM in base ad altre etichette

Per installare l'ultima versione di Ops Agent su tutte le VM nella zona us-central1-a che eseguono Debian 11, ad eccezione di quelle con le etichette "env=prod" e "app=web6", utilizza la seguente descrizione della policy:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  exclusionLabels:
  - labels:
      env: prod
      app: web6
  inventories:
  - osShortName: debian
    osVersion: '11'

Quando specifichi più coppie chiave-valore in una singola voce labels: per l'inclusione o l'esclusione, una VM corrisponde se sono presenti tutte le etichette; ovvero, le etichette vengono abbinate come operazione logica AND, non come operazione logica OR.

Installazione su VM in base al sistema operativo

Per installare l'ultima versione 2 di Ops Agent su tutte le VM che eseguono Debian 11 o RHEL 7.* nella zona us-central1-a, utilizza la seguente descrizione della policy:

agentsRule:
  packageState: installed
  version: 2.*.*
instanceFilter:
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

Terraform

Questa sezione descrive gli esempi nella directory examples del repository terraform-google-cloud-operations. Questi esempi contengono file che configurano molte delle variabili richieste dal modulo ops-agent-policy. Puoi anche copiare e modificare gli esempi. Ad esempio, tutti questi esempi installano l'Ops Agent; puoi modificarli per eliminare l'agente.

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.

Esempio: ops_agent_policy_install_all

Questo esempio installa l'ultima versione di Ops Agent su tutte le VM idonee nel tuo progetto Google Cloud .

Quando esegui il comando terraform plan o terraform apply, ti vengono richiesti i seguenti valori:

  • PROJECT_ID: L'ID del tuo Google Cloud progetto

Esempio: ops_agent_policy_install_all_in_region

Questo esempio installa l'ultima versione di Ops Agent su tutte le VM idonee in una determinata regione, ad esempio us-west1. Una regione contiene più zone, in questo caso us-west-1a, us-west-1b e us-west-1c.

Quando esegui il comando terraform plan o terraform apply, ti vengono richiesti i seguenti valori:

  • PROJECT_ID: L'ID del tuo Google Cloud progetto
  • REGION: La regione in cui installare l'agente sulle VM

Esempio: ops_agent_policy_install_all_in_zone

Questo esempio installa l'ultima versione di Ops Agent su tutte le VM idonee in una determinata zona, ad esempio us-central1-a.

Quando esegui il comando terraform plan o terraform apply, ti vengono richiesti i seguenti valori:

  • PROJECT_ID: L'ID del tuo Google Cloud progetto
  • ZONE: La zona in cui installare l'agente sulle VM

Risolvere i problemi relativi ai criteri dell'agente GA

Questa sezione fornisce informazioni per aiutarti a risolvere i problemi relativi alle policy dell'agente GA per l'Ops Agent. Potrebbero esserti utili anche le informazioni descritte in Verificare lo stato delle norme per gli agenti.

I comandi ops-agents policy non vanno a buon fine

Quando un comando gcloud compute instances ops-agents policies non va a buon fine, la risposta mostra un errore di convalida. Correggi gli errori modificando gli argomenti e i flag del comando come suggerito dal messaggio di errore.

Oltre agli errori di convalida, potresti visualizzare errori che indicano le seguenti condizioni:

Le sezioni seguenti descrivono queste condizioni in modo più dettagliato.

Autorizzazione IAM insufficiente

Se un comando gcloud compute instances ops-agents policies non riesce a causa di un errore di autorizzazione, assicurati di aver eseguito lo script prepare-for-ops-agents-policies.sh come descritto in Prima di iniziare per configurare i ruoli delle policy OS Config:

Per saperne di più sullo script prepare-for-ops-agents-policies.sh, consulta Lo script prepare-for-ops-agents-policies.sh.

L'API OS Config non è abilitata

Un esempio di errore è il seguente:

API [osconfig.googleapis.com] not enabled on project PROJECT_ID.
Would you like to enable and retry (this will take a few minutes)?
(y/N)?

Puoi inserire y per abilitare l'API oppure eseguire lo script prepare-for-ops-agents-policies.sh descritto in Prima di iniziare per concedere tutte le autorizzazioni necessarie. Se inserisci y al prompt nel messaggio di errore, devi comunque eseguire lo script prepare-for-ops-agents-policies.sh per impostare le autorizzazioni necessarie.

Per verificare che l'API OS Config sia abilitata per il progetto, esegui i seguenti comandi:

gcloud services list --project PROJECT_ID | grep osconfig.googleapis.com

Di seguito è riportato l'output previsto:

osconfig.googleapis.com    Cloud OS Config API

La norma esiste già

Un esempio di errore è il seguente:

ALREADY_EXISTS: Requested entity already exists

Questo errore indica che la norma esiste già con lo stesso nome, ID progetto e regione. Puoi utilizzare il comando gcloud compute instances ops-agents policies describe per confermarlo.

Il criterio non esiste

Un esempio di errore è il seguente:

NOT_FOUND: Requested entity was not found

Questo errore potrebbe significare che il criterio non è mai stato creato, che è stato eliminato o che l'ID criterio specificato non è corretto. Assicurati che l'elemento POLICY_ID utilizzato in un comando gcloud compute instances ops-agents policies describe, update o delete corrisponda a una policy esistente. Per ottenere un elenco delle policy dell'agente, utilizza il comando gcloud compute instances ops-agents policies list.

Il criterio viene creato, ma sembra non avere effetto

Gli agenti OS Config vengono implementati in ogni istanza Compute Engine per gestire i pacchetti per gli agenti Logging e Monitoring. Il criterio potrebbe sembrare non avere effetto se l'agente OS Config sottostante non è installato.

Linux

Per verificare che l'agente OS Config sia installato, esegui questo comando:

gcloud compute ssh instance-id \
    --project project-id \
    -- sudo systemctl status google-osconfig-agent

Un output di esempio è:

    google-osconfig-agent.service - Google OSConfig Agent
    Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset:
    Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago
    Main PID: 369 (google_osconfig)
     Tasks: 8 (limit: 4374)
    Memory: 102.7M
    CGroup: /system.slice/google-osconfig-agent.service
            └─369 /usr/bin/google_osconfig_agent

Windows

Per verificare che l'agente OS Config sia installato, esegui i seguenti passaggi:

  1. Connettiti all'istanza utilizzando RDP o uno strumento simile e accedi a Windows.

  2. Apri un terminale PowerShell, quindi esegui il seguente comando PowerShell. Non sono necessari privilegi amministrativi.

    Get-Service google_osconfig_agent

Un output di esempio è:

    Status   Name               DisplayName
    ------   ----               -----------
    Running  google_osconfig_a… Google OSConfig Agent

Se l'agente OS Config non è installato, potresti utilizzare un sistema operativo che non supporta VM Manager. Il documento Dettagli del sistema operativo di Compute Engine indica quali funzionalità di VM Manager sono supportate per ogni sistema operativo Compute Engine.

Se il sistema operativo supporta VM Manager, puoi installare manualmente l'agente OS Config.

L'agente OS Config è installato, ma non installa Ops Agent

Per verificare se si verificano errori quando l'agente OS Config applica i criteri, puoi controllare il log dell'agente OS Config. Puoi farlo utilizzando Esplora log o SSH o RDP per controllare le singole istanze di Compute Engine.

Per visualizzare i log dell'agente OS Config in Esplora log, utilizza il seguente filtro:

resource.type="gce_instance"
logId(OSConfigAgent)

Per visualizzare i log dell'agente OS Config:

CentOS, RHEL,
SLES, SUSE

Esegui questo comando: 

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/messages \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Debian, Ubuntu

Esegui questo comando: 

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/syslog \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Windows

  1. Connettiti all'istanza utilizzando RDP o uno strumento simile e accedi a Windows.

  2. Apri l'app Visualizzatore eventi, quindi seleziona Registri di Windows > Applicazione e cerca i log con Source uguale a OSConfigAgent.

Se si verifica un errore di connessione al servizio OS Config, assicurati di eseguire lo script prepare-for-ops-agents-policies.sh come descritto in Prima di iniziare per configurare i metadati di OS Config.

Per verificare che i metadati di OS Config siano abilitati, puoi eseguire il seguente comando:

gcloud compute project-info describe \
    --project PROJECT_ID \
    | grep "enable-osconfig\|enable-guest-attributes" -A 1

Di seguito è riportato l'output previsto:

- key: enable-guest-attributes
  value: 'TRUE'
- key: enable-osconfig
  value: 'TRUE'

Ops Agent è installato, ma non funziona correttamente

Per saperne di più sul debug dei problemi di Ops Agent, consulta Risoluzione dei problemi di Ops Agent.

Attiva i log a livello di debug per l'agente OS Config

Può essere utile attivare la registrazione a livello di debug nell'agente OS Config quando segnali un problema.

Puoi impostare i metadati osconfig-log-level: debug per attivare il logging a livello di debug per l'agente OS Config. I log raccolti contengono più informazioni per aiutare nelle indagini.

Per attivare la registrazione a livello di debug per l'intero progetto, esegui questo comando:

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Per attivare la registrazione a livello di debug per una VM, esegui questo comando:

gcloud compute instances add-metadata INSTANCE_ID \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Script di supporto

Questa sezione fornisce ulteriori informazioni sugli script helper descritti in questo documento:

Lo script prepare-for-ops-agents-policies.sh

Dopo aver scaricato lo script prepare-for-ops-agents-policies.sh, puoi utilizzarlo per eseguire le seguenti azioni, in base agli argomenti che fornisci:

Gli esempi riportati di seguito mostrano alcune invocazioni comuni per lo script. Per ulteriori informazioni, consulta i commenti nello script stesso.

Per abilitare le API, concedi i ruoli necessari al account di servizio predefinito e abilita i metadati di OS Config per un progetto, esegui lo script nel seguente modo:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID

Per concedere inoltre uno dei ruoli OS Config a un utente che non dispone del ruolo Proprietario (roles/owner) nel progetto, esegui lo script nel seguente modo:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

Per concedere uno dei ruoli OS Config a un account di servizio non predefinito, esegui lo script nel seguente modo:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

Lo script diagnose_policies.sh

Dato un ID progetto, un ID istanza Compute Engine, una zona Compute Engine e l'ID criterio dell'agente, lo script diagnose_policies.sh raccoglie automaticamente le informazioni necessarie per diagnosticare i problemi relativi al criterio:

  • La versione dell'agente OS Config
  • L'assegnazione delle policy del sistema operativo sottostante
  • Le assegnazioni delle policy del sistema operativo applicabili a questa istanza Compute Engine
  • Descrizione di questa istanza Compute Engine

Per richiamare lo script, esegui questo comando:

bash diagnose_policies.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID \
  --zone=ZONE

Prezzi

I comandi gcloud compute instances ops-agents policies vengono implementati utilizzando le risorse di assegnazione delle policy del sistema operativo di VM Manager. Lo script prepare-for-ops-agents-policies.sh, descritto in Prima di iniziare, configura VM Manager in modalità con funzionalità limitate (OSCONFIG_B), che è sufficiente per creare e gestire le policy degli agenti. L'utilizzo di VM Manager in modalità limitata non prevede costi.

Se hai configurato VM Manager in modalità con tutte le funzionalità (OSCONFIG_C), potresti sostenere dei costi.