Utilizzare i criteri dell'agente (beta)

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

Crea una policy dell'agente

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

Per creare un criterio dell'agente utilizzando Google Cloud CLI, completa i seguenti 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 l'hai ancora fatto, installa il componente beta della gcloud CLId:

    gcloud components install beta

    Per verificare se è installato il componente beta, esegui:

    gcloud components list

    Se hai già installato 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 script set-permissions.sh.

  4. Utilizza il comando gcloud beta compute instances ops-agents policies create per creare una policy. Per la sintassi del comando, consulta la documentazione 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 maggiori 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.

Se stai creando un criterio 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 l'Ops Agent.

Di seguito è riportato 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 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 ulteriori informazioni su come specificare il sistema operativo, vedi gcloud beta compute instances ops-agents policies create.

Fase 2: aggiorna la policy in modo che abbia come target le 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 le norme per cancellare il filtro delle zone in modo che vengano implementate 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

Potrebbe essere necessario 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 ai criteri dell'agente beta

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

I comandi ops-agents policy non vanno a buon fine

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 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 in modo più dettagliato queste condizioni.

Autorizzazione IAM insufficiente

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

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 abilitare l'API oppure eseguire lo script set-permissions.sh, descritto in Creare un criterio 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

Di seguito è riportato l'output previsto:

osconfig.googleapis.com    Cloud OS Config API

La norma esiste già

Un errore di esempio è simile al 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 beta compute instances ops-agents policies describe per confermarlo.

Il criterio non esiste

Un errore di esempio è simile al seguente:

NOT_FOUND: Requested entity was not found

Questo errore potrebbe significare che il criterio non è mai stato creato, è stato eliminato o che l'ID criterio specificato non è corretto. Assicurati che POLICY_ID utilizzato in un comando gcloud beta compute instances ops-agents policies describe, update o delete corrisponda a una policy esistente. Per ottenere un elenco di policy dell'agente, utilizza il comando gcloud beta 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 i 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 la presenza di errori durante l'applicazione dei criteri da parte dell'agente OS Config, 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 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 di 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:

Abilita 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 il logging a livello di debug per l'agente OS Config. I log raccolti contengono più informazioni per aiutarti con l'indagine.

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 set-permissions.sh

Dopo aver scaricato lo script set-permissions.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.

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 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 nel seguente modo:

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

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

  • Versione dell'agente OS Config
  • La policy guest OS Config sottostante
  • Le norme applicabili a questa istanza Compute Engine
  • I repository dei pacchetti dell'agente estratti in 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 di 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 degli agenti si basa sui comandi della Google Cloud CLI. Per creare una policy dell'agente utilizzando Terraform, segui le istruzioni del modulo Terraform agent-policy. Puoi trovare esempi di norme anche nella directory examples.