Utilizza i criteri dell'agente

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

I criteri degli agenti consentono l'installazione e la manutenzione automatiche Agenti Google Cloud Observability in un parco risorse di VM di Compute Engine corrispondenti secondo i criteri specificati dall'utente. Puoi creare un criterio per un progetto Google Cloud che regoli le VM esistenti e nuove associate al progetto Google Cloud, garantendo l'installazione, la disinstallazione e l'eventuale upgrade automatico di tutti gli agenti di Google Cloud Observability su queste VM.

Puoi creare e gestire i criteri dell'agente utilizzando il gruppo di comandi gcloud beta compute instances ops-agents policies in Google Cloud CLI o il modulo Terraform agent-policy. I criteri dell'agente utilizzano la suite di strumenti di VM Manager in Compute Engine per gestire i criteri del sistema operativo, che possono automatizzare il deployment e la manutenzione delle configurazioni software come gli agenti di osservabilità di Google Cloud: l'agente Ops, l'agente di monitoraggio precedente e l'agente di logging precedente.

Sistemi operativi supportati

Puoi applicare un criterio dell'agente alle istanze VM di Compute Engine che eseguono i sistemi operativi indicati nella tabella seguente:

Sistema operativo	Ops Agent (norme GA e beta^†)	Agente Logging (solo criteri beta^†)	Agente Monitoring (solo criteri 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

^†  Nei criteri dell'agente beta, le colonne dell'agente sono mappate a un Tipo di agente specificato per Chiamata create a gcloud beta compute instances ops-agents policies:

• Ops Agent corrisponde al tipo di agente ops-agent.
• Agente di logging corrisponde al tipo di agente logging.
• L'agente di monitoraggio viene mappato al tipo di agente metrics.

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

Crea un criterio per gli agenti

Questa sezione descrive l'utilizzo di Google Cloud SDK per gestire i criteri degli agenti. Per informazioni sull'utilizzo di Terraform, consulta Integrazione di Terraform.

Per creare un criterio di agente utilizzando Google Cloud CLI, completa quanto segue passaggi:

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

   I criteri dell'agente descritti in questo documento utilizzano il gruppo di comandi beta.

2. Se non lo hai già fatto, installa il componente beta della gcloud CLI:

   gcloud components install beta
   

   Per verificare se il componente beta è installato, esegui:

   gcloud components list
   

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

   gcloud components update
   

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

   Per informazioni sullo script, consulta la sezione Script set-permissions.sh.

   Nota: lo script set-permissions.sh è progettato per essere eseguito su Linux. Se utilizzando un computer su un altro sistema operativo, quindi esegui lo script Cloud Shell

4. Usa il comando gcloud beta compute instances ops-agents policies create per creare un criterio. Per la sintassi del comando, consulta gcloud beta compute instances ops-agents policies create documentazione.

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

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

Best practice per l'utilizzo dei criteri 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 il criterio.

Ecco un esempio di piano di implementazione graduale per le VM Debian 11 in un progetto chiamato my_project:

Fase 1: crea un criterio denominato ops-agents-policy-safe-rollout per installare gli agenti Logging e Monitoring precedenti 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 su come specificare il sistema operativo, consulta gcloud beta compute instances ops-agents policies create.

Fase 2: aggiorna il criterio per scegliere come target le VM in un'unica zona che hanno 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 il criterio per cancellare il filtro delle zone in modo che venga implementato a livello globale

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

Criteri 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 manuale e verificando l'agente OS Config, consulta Elenco di controllo per la verifica di VM Manager.

Risolvi i problemi relativi ai criteri degli agenti beta

Questa sezione fornisce informazioni per aiutarti a risolvere i problemi relativi ai criteri dell'agente beta per Ops Agent, l'agente di monitoraggio legacy e l'agente di logging legacy.

I comandi ops-agents policy hanno esito negativo

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

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

• Autorizzazione IAM insufficiente
• L'API OS Config non è abilitata
• Il criterio specificato non esiste

Nelle sezioni seguenti vengono descritte queste condizioni in modo più dettagliato.

Autorizzazione IAM insufficiente

Se un comando gcloud beta compute instances ops-agents policies non va a buon fine con un errore di autorizzazione, assicurati di aver eseguito lo script set-permissions.sh come descritto in Creare un criterio dell'agente per configurare i ruoli dei criteri OS Config:

• GuestPolicy Admin (roles/osconfig.guestPolicyAdmin): fornisce accesso completo alle norme per gli ospiti.
• Editor GuestPolicy (roles/osconfig.guestPolicyEditor): Consente agli utenti di ricevere, aggiornare ed elencare i criteri relativi agli ospiti.
• Visualizzatore GuestPolicy (roles/osconfig.guestPolicyViewer): Fornisce l'accesso di sola lettura per recuperare ed elencare i criteri guest.

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

L'API OS Config non è abilitata

Un errore di esempio è simile al 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 attivare l'API oppure eseguire lo script set-permissions.sh, descritto in Creare un criterio per gli agenti, 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

Di seguito è riportato l'output previsto:

osconfig.googleapis.com    Cloud OS Config API

Il criterio non esiste

Un errore di esempio ha il seguente aspetto:

NOT_FOUND: Requested entity was not found

Questo errore potrebbe indicare che il criterio non è mai stato creato, che è stato eliminato o che l'ID criterio specificato non è corretto. Assicurati che il valore POLICY_ID utilizzato in un comando gcloud beta compute instances ops-agents policies, describe, update o delete corrisponda a un criterio esistente. Per ottenere un elenco degli agenti usa il comando gcloud beta compute instances ops-agents policies list.

Il criterio è stato creato, ma sembra non avere alcun effetto

Per gestire le istanze di Compute Engine, viene eseguito il deployment degli agenti OS Config per gli agenti Logging e Monitoring. Il criterio potrebbe non avere alcun 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:

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. Tu non necessitano di privilegi amministrativi.

   Get-Service google_osconfig_agent
   

Un esempio di output è:

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

Se l'agente di configurazione del sistema operativo 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 ciascun 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 l'agente Logging.

Per verificare se si verificano errori quando l'agente OS Config applica i criteri, puoi controllare il log dell'agente. Questa operazione può essere eseguita utilizzando Esplora log o utilizzo di SSH o RDP per controllare singoli Compute Engine di Compute Engine.

Per visualizzare i log dell'agente OS Config 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, poi 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 Script set-permissions.sh come descritto in Crea un criterio dell'agente per impostare i metadati OS Config.

Per verificare che i metadati OS Config siano abilitati, puoi eseguire quanto segue :

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'

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 dell'agente Logging legacy
• Risolvere i problemi dell'agente Monitoring legacy

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

Può essere utile abilitare il logging a livello di debug nell'agente OS Config quando segnalando 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 utili per l'indagine.

Per abilitare il logging 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 abilitare il logging 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 informazioni aggiuntive sugli script di supporto. descritti in questo documento:

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

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 monitoraggio (roles/monitoring.metricWriter) all'account di servizio 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 sia attivo su ogni VM.

• Concedi uno dei seguenti ruoli IAM agli utenti non proprietari o all'account di servizio necessario per creare e gestire i criteri. Progetto i proprietari hanno accesso completo alla creazione e alla gestione dei criteri; tutti gli altri utenti o di servizio agli account deve essere concesso uno dei seguenti ruoli:

  • Amministratore GuestPolicy (roles/osconfig.guestPolicyAdmin): Fornisce l'accesso completo ai criteri guest.
  • Editor GuestPolicy (roles/osconfig.guestPolicyEditor): consente agli utenti di recuperare, aggiornare e elencare le norme per gli ospiti.
  • Visualizzatore GuestPolicy (roles/osconfig.guestPolicyViewer): Fornisce l'accesso di sola lettura per recuperare ed elencare i criteri 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 dello script. Per ulteriori informazioni, vedi i commenti nello script stesso.

Per abilitare le API, concedi i ruoli necessari all'account di servizio predefinito, e abilita i metadati OS Config per un progetto, esegui lo script come segue:

bash set-permissions.sh --project=PROJECT_ID

Per concedere inoltre uno dei ruoli di configurazione del sistema operativo a un utente che non ha il ruolo Proprietario (roles/owner) nel progetto, esegui lo script come segue:

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

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

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 Compute Engine, e l'ID criterio dell'agente, Lo script diagnose.sh raccoglie automaticamente le informazioni necessarie per diagnosticare i problemi relativi alle norme:

• La versione dell'agente OS Config
• Il criterio guest OS Config sottostante
• I criteri applicabili a questa istanza Compute Engine
• I repository dei pacchetti dell'agente che vengono estratti in questa istanza 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 con Terraform

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

Il supporto di Terraform per i criteri dell'agente si basa sui comandi della CLI di Google Cloud. Per creare un criterio dell'agente utilizzando Terraform, segui le agent-policyistruzioni del modulo Terraform. Puoi anche trovare criteri di esempio nella Directory examples.