Gestisci i criteri degli agenti

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 degli agenti di osservabilità di Google Cloud in un parco risorse di VM di Compute Engine che soddisfano i criteri specificati dall'utente. Con un solo comando puoi creare un criterio per un progetto Google Cloud che regola le VM esistenti e nuove associate al progetto Google Cloud, garantendo una corretta installazione e l'upgrade automatico facoltativo di tutti gli agenti Google Cloud Observability su queste VM.

Puoi creare e gestire i criteri degli agenti utilizzando il gruppo di comandi gcloud beta compute instances ops-agents policies in Google Cloud CLI. I comandi in questo gruppo utilizzano la suite di strumenti VM Manager di Compute Engine per gestire i criteri del sistema operativo, che possono automatizzare il deployment e la manutenzione di configurazioni software come gli agenti Google Cloud Observability: Ops Agent, l'agente Monitoring legacy e l'agente Logging legacy.

Sistemi operativi supportati

Puoi applicare un criterio di agente alle istanze VM di Compute Engine che eseguono i sistemi operativi mostrati nella tabella seguente. Nella tabella, le colonne dell'agente sono mappate a un tipo di agente specificato per la chiamata gcloud beta compute instances ops-agents policies create:

• L'agente Logging viene mappato ai criteri con tipo di agente logging.
• L'agente di monitoraggio viene mappato ai criteri con tipo di agente metrics.
• Ops Agent viene mappato ai criteri con tipo di agente ops-agent.

Sistema operativo	Agente Logging	Agente Monitoring	Ops Agent
CentOS 7
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		^1
RHEL 8: rhel-8, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha		^1
Debian 9 (Stretch)
Debian 10 (Buster)
Debian 11 (Bullseye)
Ubuntu LTS 18.04 (Bionic Beaver): ubuntu-1804-lts, ubuntu-minimal-1804-lts
Ubuntu LTS 20.04 (Fossa Fossa): ubuntu-2004-lts, ubuntu-minimal-2004-lts
Ubuntu LTS 22.04 (Jammy Jellyfish): ubuntu-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
OpenSUSE Leap 15: opensuse-leap (opensuse-leap-15-3-*, apreuse-leap-15-4-*)
Windows Server: 2016, 2019, 2022, Core 2016, Core 2019, Core 2022

¹ 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 dell'agente

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

1. Se non lo hai già fatto, installa Google Cloud CLI.

   Questo documento descrive il gruppo di comandi beta per la gestione dei criteri dell'agente.

2. Se non lo hai già fatto, installa il componente beta di 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 la versione più recente:

   gcloud components update
   

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

   Per informazioni sullo script, consulta Che cosa sta facendo lo script set-permissions.sh?.

   Nota: lo script set-permissions.sh è progettato per l'esecuzione su Linux. Se utilizzi una macchina su un sistema operativo diverso, esegui lo script da Cloud Shell.

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

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

   Per ulteriori informazioni sugli altri comandi nel 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 degli agenti

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

Se stai creando un criterio per Ops Agent, assicurati che nelle VM non sia installato l'agente Logging o l'agente Monitoring legacy. L'esecuzione di 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 un criterio per installare Ops Agent.

Ecco un esempio di piano di implementazione graduale per le VM di CentOS 7 in un progetto denominato my_project:

Fase 1: crea un criterio denominato ops-agents-policy-safe-rollout per installare Ops Agent 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=ops-agent,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=centos,version=7 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

Per maggiori 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 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 il criterio per cancellare il filtro delle zone e implementarlo a livello globale

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

Limitazioni

Affinché un criterio venga applicato alle VM precedenti a OS Config, è necessaria un'ulteriore configurazione per garantire che l'agente OS Config su cui si basa il criterio sia installato sulle VM. Per installare l'agente OS Config su un parco risorse di VM, completa i seguenti passaggi:

1. Assicurati di aver eseguito lo script set-permissions.sh nella sezione Crea un criterio dell'agente.

2. Identifica le VM su cui vuoi installare l'agente OS Config ed elencale in un file CSV. Ad esempio, per ottenere un elenco di VM non gestite da Google Kubernetes Engine, App Engine o da altri servizi Google Cloud e quindi salvarlo in un file denominato instances.csv, esegui questo comando:

     gcloud compute instances list \
         --filter="-labels.list(show="keys"):goog-" \
         --format="csv(name,zone)" \
         | grep -v -x -F -f  <(gcloud compute instances os-inventory list-instances \
             --format="csv(name,zone)") \
         | sed 's/$/,update/' > instances.csv
   

   La sezione grep esclude le VM su cui l'agente OS Config è già installato e abilitato. L'esclusione delle etichette VM basata su goog- esclude le VM di Compute Engine gestite da GKE, App Engine e altri servizi.

   Per filtrare ulteriormente le istanze per zone o etichette, modifica il valore del flag --filter in modo simile a questo:

     "-labels.list(show="keys"):goog- AND zone:(ZONE_1,ZONE_2) AND labels.KEY_1:VALUE_1 AND labels.KEY_2=VALUE_2"
   

3. Per installare l'agente OS Config sulle VM Linux, scarica ed esegui lo script mass-install-osconfig-agent.sh.

   Nota: lo script mass-install-osconfig-agent.sh, che automatizza le istruzioni per l'installazione dell'agente OS Config, può installare l'agente OS Config solo su VM Linux. Se hai VM Windows, esegui le istruzioni di installazione manualmente.

   Il seguente comando installa l'agente OS Config sulle VM specificate nel file instances.csv nel progetto specificato:

      bash mass-install-osconfig-agent.sh --project PROJECT_ID --input-file instances.csv
   

   Per ulteriori informazioni sull'utilizzo dello script, consulta i commenti nello script.

Risoluzione dei problemi

I comandi ops-agents policy hanno esito negativo

In caso di errore di un comando gcloud beta compute instances ops-agents policies, la risposta mostra un errore di convalida. Correggi gli errori correggendo gli argomenti e i flag dei comandi come suggerito dal messaggio di errore.

Oltre agli errori di convalida, potresti visualizzare i seguenti errori:

• Autorizzazione IAM insufficiente

  Un errore di esempio ha il seguente aspetto:

  ERROR: (gcloud.beta.compute.instances.ops-agents.policies.command) PERMISSION_DENIED: Caller does not have required permission to command
  

  Assicurati di eseguire lo script set-permissions.sh nella sezione Crea un criterio agente per configurare il ruolo IAM specifico per osconfig.guestPolicy.

  Per verificare se hai abilitato il ruolo del criterio guest di OS Config sufficiente per il progetto, puoi eseguire questo comando. In questo esempio, il comando verifica se l'utente ha il ruolo roles/osconfig.guestPolicyAdmin. Il valore GCLOUD_MEMBER deve essere nel formato user:USER_EMAIL o serviceaccount:SERVICE_ACCOUNT_EMAIL.

  gcloud projects get-iam-policy PROJECT_ID \
      --filter=--member=GCLOUD_MEMBER \
      | grep "roles/osconfig.guestPolicyAdmin" -B 2
  

  L'output previsto è:

  - members:
    - GCLOUD_MEMBER
    role: roles/osconfig.guestPolicyAdmin
  

• L'API OS Config non è abilitata

  Un errore di esempio ha il seguente aspetto:

  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)?
  

  Assicurati di eseguire lo script set-permissions.sh nella sezione Crea un criterio dell'agente per concedere tutte le autorizzazioni necessarie.

  Per verificare se l'API OS Config è abilitata per il progetto, puoi eseguire questi comandi:

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

  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
  

  Ciò indica che il criterio è già stato eliminato. Assicurati che l'ID criterio nel comando describe, update o delete sia mappato a un criterio esistente.

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

Per gestire i pacchetti per gli agenti Logging e Monitoring, viene eseguito il deployment degli agenti OS Config in ogni istanza Compute Engine. 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

FINESTRE

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 hai bisogno di privilegi amministrativi.

   Get-Service google_osconfig_agent
   

Un output di esempio è:

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

Nelle istanze SUSE e Ubuntu Compute Engine non è preinstallato l'agente OS Config, quindi devi seguire le instructions per l'installazione dell'agente OS Config per installare l'agente OS Config nelle istanze di Compute Engine.

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

Per verificare se sono presenti errori quando l'agente OS Config applica i criteri, puoi controllare il log dell'agente OS Config. Per farlo, utilizza Esplora log oppure utilizza 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"
logName="projects/PROJECT_ID/logs/OSConfigAgent"

Per visualizzare i log dell'agente OS Config mediante SSH per singole istanze Linux di Compute Engine, esegui questo comando:

• CentOS / RHEL / SLES / SUSE

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

• Debian / Ubuntu

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

Per visualizzare i log degli agenti OS Config utilizzando l'RDP per singole istanze di Windows di Compute Engine, segui questi passaggi:

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

2. Apri l'app Event Viewer, in Windows Logs => Application, cerca i log con Source uguale a OSConfigAgent.

Se si verifica un errore durante la connessione al servizio OS Config, assicurati di eseguire lo script set-permissions.sh nella sezione Creazione di un criterio dell'agente per configurare i metadati.

Per verificare che i metadati OS Config siano abilitati, puoi eseguire questo comando:

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

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:

• Risolvi i problemi di Ops Agent
• Risolvi 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 durante la segnalazione di un problema.

Puoi impostare i metadati osconfig-log-level: debug per abilitare il logging a livello di debug per l'agente OS Config. I log raccolti contengono ulteriori informazioni per facilitare 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

Che cosa sta facendo lo script set-permissions.sh?

Una volta fornito un ID progetto, un ruolo Identity and Access Management (IAM) e un'email o un account di servizio, lo script set-permissions.sh esegue le seguenti azioni:

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

• Concede i ruoli roles/logging.logWriter e 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 gli agenti OS Config vengano attivati nelle VM.

• Concede il ruolo IAM specificato all'utente gcloud o all'account di servizio. I proprietari del progetto hanno accesso completo per creare e gestire un criterio. Per tutti gli altri utenti o account di servizio, i proprietari del progetto devono concedere uno dei seguenti ruoli:

  • roles/osconfig.guestPolicyAdmin: fornisce l'accesso completo a un criterio.

  • roles/osconfig.guestPolicyEditor: consente agli utenti di scaricare, aggiornare ed elencare un criterio.

  • roles/osconfig.guestPolicyViewer: fornisce l'accesso di sola lettura per recuperare ed elencare un criterio.

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

La seguente chiamata dello script abilita le API, concede i ruoli necessari all'account di servizio predefinito e abilita i metadati di OS Config:

bash set-permissions.sh --project=PROJECT_ID

Per utilizzare lo script in modo da concedere anche uno dei ruoli di OS Config a un utente che non dispone del ruolo roles/owner (Proprietario) 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 utilizzare lo script in modo da concedere anche uno dei ruoli 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]

Per ulteriori informazioni, consulta il contenuto dello script.

Che cosa sta facendo lo script diagnose.sh?

Dati un progetto, un ID istanza Compute Engine e un ID criterio Ops Agent, lo script diagnose.sh raccoglie automaticamente le informazioni necessarie per diagnosticare i problemi relativi al criterio:

• La versione dell'agente OS Config

• Il criterio guest di OS Config sottostante

• I criteri applicabili a questa istanza Compute Engine

• I repository del pacchetto dell'agente di cui viene eseguito il pull su un'istanza Compute Engine

Integrazione con Terraform

Il supporto di Terraform si basa sui comandi Google Cloud CLI. Per creare un criterio dell'agente utilizzando Terraform, segui le istruzioni del modulo Terraform.