Utilizza i criteri degli agenti (beta)

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.

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.

Nota: questo documento descrive i comandi compute instances ops-agents policies beta. Questi comandi sono disponibili anche in una release GA. Per informazioni sui comandi compute instances ops-agents policies di GA, consulta Utilizzare i criteri dell'agente (GA). Per informazioni sulle differenze tra le due release e sulla conversione dei criteri degli agenti beta in criteri degli agenti GA, consulta Panoramica dei criteri degli agenti per Ops Agent.

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. Scarica e 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 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 un piano di implementazione graduale per le VM Debian 11 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=debian,version=11 \
    --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

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

Risolvi i problemi relativi ai criteri dell'agente beta

Questa sezione fornisce informazioni utili per risolvere i problemi relativi ai criteri degli agenti beta per Ops Agent, l'agente Monitoring legacy e l'agente Logging legacy.

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 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 e restituisce 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 di OS Config:

• GuestPolicy Admin (roles/osconfig.guestPolicyAdmin): fornisce l'accesso completo ai criteri guest.
• Editor GuestPolicy (roles/osconfig.guestPolicyEditor): consente agli utenti di ottenere, aggiornare ed elencare i criteri relativi agli ospiti.
• GuestPolicy Viewer (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 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)?

Puoi inserire y per abilitare l'API oppure eseguire lo script set-permissions.sh, descritto in Creare un criterio dell'agente, per concedere tutte le autorizzazioni necessarie. Se inserisci y nella richiesta del 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 questi 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 significare 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 dei criteri degli agenti, usa il comando gcloud beta compute instances ops-agents policies list.

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

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 hai bisogno di 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, è possibile che tu stia utilizzando un sistema operativo che non supporta VM Manager. Il documento Dettagli del sistema operativo di Compute Engine indica le funzionalità di VM Manager supportate per ciascun sistema operativo Compute Engine.

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

L'agente OS Config è installato, ma non installa 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"
logId(OSConfigAgent)

Per visualizzare i log degli agenti OS Config, segui questi passaggi:

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 script set-permissions.sh come descritto in Creare un criterio dell'agente per configurare i metadati di OS Config.

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

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:

• 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

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 utilizzare lo script per eseguire le seguenti azioni, in base agli argomenti forniti:

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

• Concedi i ruoli Identity and Access Management Writer log (roles/logging.logWriter) e Writer metriche Monitoring (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 all'account utente o di servizio degli utenti non proprietari necessari per creare e gestire i criteri. I proprietari del progetto hanno accesso completo per creare e gestire i criteri; a tutti gli altri utenti o account di servizio deve essere concesso uno dei seguenti ruoli:

  • GuestPolicy Admin (roles/osconfig.guestPolicyAdmin): fornisce l'accesso completo ai criteri guest.
  • Editor GuestPolicy (roles/osconfig.guestPolicyEditor): consente agli utenti di ottenere, aggiornare ed elencare i criteri relativi agli ospiti.
  • GuestPolicy Viewer (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 chiamate comuni allo 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 OS Config a un utente che non dispone del 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 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

Una volta forniti un ID progetto, un ID istanza di Compute Engine e l'ID criterio dell'agente, 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 dei pacchetti dell'agente di cui viene eseguito il pull su questa istanza Compute Engine

Per richiamare lo script, esegui questo comando:

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

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.