Utilizzare i criteri dell'agente

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Le policy dell'agente consentono l'installazione e la manutenzione automatizzate degli agenti di Google Cloud Observability su un parco risorse di VM di Compute Engine che corrispondono ai criteri specificati dall'utente. Puoi creare una policy per un Google Cloud progetto che gestisce le VM esistenti e nuove associate a quel Google Cloud progetto, garantendo la corretta installazione, disinstallazione e l'upgrade automatico facoltativo di tutti gli agenti di Google Cloud Observability su queste VM.

Puoi creare e gestire le policy dell'agente utilizzando il gcloud beta compute instances ops-agents policies gruppo di comandi in Google Cloud CLI o il agent-policy modulo Terraform. 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 gli agenti di Google Cloud Observability: Ops Agent, l'agente Monitoring legacy e l'agente Logging legacy.

Sistemi operativi supportati

Puoi applicare una policy dell'agente alle istanze VM di Compute Engine che eseguono i sistemi operativi mostrati nella tabella seguente:

Sistema operativo	Ops Agent (policy GA & beta^†)	Agente Logging (solo policy beta^†)	Agente Monitoring (solo policy beta^†)
CentOS 8
Rocky Linux 8
RHEL 6
RHEL 7: rhel-7, rhel-7-6-sap-ha, rhel-7-7-sap-ha, rhel-7-9-sap-ha			^‡
RHEL 8: rhel-8, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha			^‡
Debian 9 (Stretch)
Debian 11 (Bullseye)
Deep Learning VM Image basate su Debian 11 (Bullseye)
Ubuntu LTS 18.04 (Bionic Beaver): ubuntu-1804-lts, ubuntu-minimal-1804-lts
Ubuntu LTS 20.04 (Focal Fossa): ubuntu-2004-lts, ubuntu-minimal-2004-lts
Ubuntu LTS 22.04 (Jammy Jellyfish): buntu-2204-lts, ubuntu-minimal-2204-lts
SLES 12: sles-12, sles-12-sp5-sap
SLES 15: sles-15, sles-15-sp2-sap, sles-15-sp3-sap, sles-15-sp4-sap, sles-15-sp5-sap, sles-15-sp6-sap
OpenSUSE Leap 15: opensuse-leap (opensuse-leap-15-3-*, opensuse-leap-15-4-*)
Windows Server: 2016, 2019, 2022, Core 2016, Core 2019, Core 2022

^†  Nelle policy dell'agente beta, le colonne dell'agente vengono mappate a un tipo di agente specificato nell' gcloud beta compute instances ops-agents policies create invocazione:

• Ops Agent viene mappato al tipo di agente ops-agent.
• Agente Logging viene mappato al tipo di agente logging.
• Agente Monitoring viene mappato al tipo di agente metrics.

^‡ L'agente Monitoring non è supportato su rhel-7-9-sap-ha, rhel-8-2-sap-ha, o rhel-8-4-sap-ha.

Creare una policy dell'agente

Questa sezione descrive l'utilizzo di Google Cloud SDK per la gestione delle policy dell'agente. Per informazioni sull'utilizzo di Terraform, consulta Integrazione di Terraform.

Per creare una policy dell'agente utilizzando Google Cloud CLI:

1. Se non l'hai ancora fatto, installa il Google Cloud CLI.

   Le policy dell'agente descritte in questo documento utilizzano il gruppo di comandi beta.

2. Se non l'hai ancora fatto, installa il componente beta di gcloud CLI:

   gcloud components install beta
   

   Per verificare se hai installato il componente beta, esegui:

   gcloud components list
   

   Se hai installato in precedenza il componente beta, assicurati di avere l'ultima versione:

   gcloud components update
   

3. Scarica e utilizza il seguente script per abilitare le API e impostare le autorizzazioni appropriate per l'utilizzo di Google Cloud CLI: set-permissions.sh.

   Per informazioni sullo script, consulta Lo set-permissions.sh script.

   Nota: Lo script set-permissions.sh è progettato per essere eseguito su Linux. Se utilizzi una macchina con un sistema operativo diverso, esegui lo script da Cloud Shell.

4. Utilizza il comando gcloud beta compute instances ops-agents policies create per creare una policy. Per la sintassi del comando, consulta la gcloud beta compute instances ops-agents policies create documentazione.

   Per esempi che mostrano come formattare il comando, consulta la sezione Esempi nella documentazione di Google Cloud CLI.

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

Best practice per l'utilizzo delle policy dell'agente

Per controllare l'impatto sui sistemi di produzione durante l'implementazione, ti consigliamo di utilizzare le etichette e le zone delle istanze per filtrare le istanze a cui si applica la policy.

Di seguito è riportato un esempio di piano di implementazione graduale per le VM Debian 11 in un progetto denominato my_project:

Fase 1: crea una policy denominata ops-agents-policy-safe-rollout per installare l'agente Logging legacy e l'agente Monitoring su tutte le VM con le etichette env=test e app=myproduct.

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=logging,version=current-major,package-state=installed,enable-autoupgrade=true;type=metrics,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=debian,version=11 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

Per ulteriori informazioni sulla specifica del sistema operativo, consulta gcloud beta compute instances ops-agents policies create.

Fase 2: aggiorna la policy in modo che sia destinata alle VM in una singola zona con le etichette env=prod e app=myproduct.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c \

Fase 3: aggiorna la policy per cancellare il filtro delle zone in modo che venga implementata a livello globale.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --clear-zones

Policy sulle VM precedenti a OS Config

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

Risolvere i problemi relativi alle policy dell'agente beta

Questa sezione fornisce informazioni per aiutarti a risolvere i problemi relativi alle policy dell'agente beta per Ops Agent, l'agente Monitoring legacy e l'agente Logging legacy.

I comandi ops-agents policy non riescono

Quando un comando gcloud beta compute instances ops-agents policies non riesce, 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:

• Autorizzazione IAM insufficiente
• L'API OS Config non è abilitata
• La policy specificata non esiste

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

Autorizzazione IAM insufficiente

Se un comando gcloud beta compute instances ops-agents policies non riesce a causa di un errore di autorizzazione, allora assicurati di aver eseguito lo script set-permissions.sh come descritto in Creare una policy dell'agente per configurare i ruoli delle policy OS Config:

• GuestPolicy Admin (roles/osconfig.guestPolicyAdmin): fornisce l'accesso completo alle policy guest.
• GuestPolicy Editor (roles/osconfig.guestPolicyEditor): consente agli utenti di recuperare, aggiornare ed elencare le policy guest.
• GuestPolicy Viewer (roles/osconfig.guestPolicyViewer): fornisce l'accesso di sola lettura per recuperare ed elencare le policy guest.

Per ulteriori informazioni sullo script set-permissions.sh, consulta Lo script set-permissions.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 set-permissions.sh script, descritto in Creare una policy dell'agente, per concedere tutte le autorizzazioni necessarie. Se inserisci y al prompt nel messaggio di errore, devi comunque eseguire lo script set-permissions.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

L'output previsto è il seguente:

osconfig.googleapis.com    Cloud OS Config API

La policy esiste già

Un esempio di errore è il seguente:

ALREADY_EXISTS: Requested entity already exists

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

La policy non esiste

Un esempio di errore è il seguente:

NOT_FOUND: Requested entity was not found

Questo errore potrebbe indicare che la policy non è mai stata creata, è stata eliminata o che l'ID policy specificato non è corretto. Assicurati che il POLICY_ID utilizzato in un gcloud beta compute instances ops-agents policies describe, update o delete comando corrisponda a una policy esistente. Per ottenere un elenco delle policy dell'agente, utilizza il comando gcloud beta compute instances ops-agents policies list.

La policy viene creata, ma sembra non avere alcun effetto

Gli agenti OS Config vengono sottoposti a deployment su ogni istanza di Compute Engine per gestire i pacchetti per gli agenti Logging e Monitoring. La policy potrebbe sembrare non avere alcun effetto se l'agente OS Config sottostante non è installato.

Linux

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

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

Di seguito è riportato 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:

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 i privilegi di amministratore.

   Get-Service google_osconfig_agent
   

Di seguito è riportato 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 di Compute Engine.

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

L'agente OS Config è installato, ma non installa l'agente Logging

Per verificare se si sono verificati errori durante l'applicazione delle policy da parte dell'agente OS Config, puoi controllare il log dell'agente OS Config. Puoi farlo utilizzando Esplora log o utilizzando 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 Log di Windows > Applicazione e cerca i log con Source uguale a OSConfigAgent.

Se si verifica un errore durante la connessione al servizio OS Config, assicurati di eseguire lo set-permissions.sh script come descritto in Creare una policy dell'agente per configurare i metadati OS Config.

Per verificare che i metadati 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

L'output previsto è il seguente:

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

Gli agenti di osservabilità sono installati, ma non funzionano correttamente

Per informazioni sul debug di agenti specifici, consulta i seguenti documenti:

• Risolvere i problemi relativi a Ops Agent
• Risolvere i problemi relativi all'agente Logging legacy
• Risolvere i problemi relativi all'agente Monitoring legacy

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

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

Puoi impostare i metadati osconfig-log-level: debug per abilitare la registrazione a livello di debug per l'agente OS Config. I log raccolti contengono ulteriori informazioni utili per l'indagine.

Per abilitare la registrazione a livello di debug per l'intero progetto, esegui il seguente comando:

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

Per abilitare la registrazione a livello di debug per una VM, esegui il seguente 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 di supporto descritti in questo documento:

• Lo set-permissions.sh script
• Lo diagnose.sh script

Lo script set-permissions.sh

Dopo aver scaricato lo script set-permissions.sh, puoi utilizzarlo per eseguire le seguenti azioni, in base agli argomenti forniti:

• Abilita l'API Cloud Logging, l'API Cloud Monitoring e l'API OS Config per il progetto.

• Concedi i ruoli di Identity and Access Management Writer log (roles/logging.logWriter) e Writer metriche Monitoring (roles/monitoring.metricWriter) al service account predefinito di Compute Engine in modo che gli agenti possano scrivere log e metriche nelle API Logging e Cloud Monitoring.

• Abilita i metadati OS Config per il progetto in modo che l'agente OS Config su ogni VM sia attivo.

• Concedi uno dei seguenti ruoli IAM all'utente o al account di servizio non proprietario necessario per creare e gestire le policy. I proprietari del progetto hanno accesso completo per creare e gestire le policy; a tutti gli altri utenti o service account deve essere concesso uno dei seguenti ruoli:

  • GuestPolicy Admin (roles/osconfig.guestPolicyAdmin): fornisce l'accesso completo alle policy guest.
  • GuestPolicy Editor (roles/osconfig.guestPolicyEditor): consente agli utenti di recuperare, aggiornare ed elencare le policy guest.
  • GuestPolicy Viewer (roles/osconfig.guestPolicyViewer): fornisce l'accesso di sola lettura per recuperare ed elencare le policy guest.

  Quando esegui lo script, devi specificare solo la parte guestPolicy* del nome del ruolo. Lo script fornisce la parte roles/osconfig. del nome.

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

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

bash set-permissions.sh --project=PROJECT_ID

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

bash set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

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

bash set-permissions.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

Lo script diagnose.sh

Dato un ID progetto, un ID istanza di Compute Engine e l'ID policy dell'agente, lo script raccoglie automaticamente le informazioni necessarie per diagnosticare i problemi relativi alla policy:diagnose.sh

• La versione dell'agente OS Config
• La policy guest OS Config sottostante
• Le policy applicabili a questa istanza di Compute Engine
• I repository dei pacchetti dell'agente che vengono estratti in questa istanza di Compute Engine

Per richiamare lo script, esegui il seguente comando:

bash diagnose.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID 

Integrazione di Terraform

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

Il supporto di Terraform per le policy dell'agente si basa sui comandi di Google Cloud CLI. Per creare una policy dell'agente utilizzando Terraform, segui le istruzioni del modulo Terraform agent-policy. Puoi anche trovare policy di esempio nella examples directory.