Utilizzare i criteri dell'agente (beta)

Puoi creare e gestire i criteri degli agenti utilizzando Comando gcloud beta compute instances ops-agents policies in Google Cloud CLI o agent-policy Modulo Terraform. I criteri dell'agente utilizzano Suite di strumenti VM Manager in Compute Engine per gestire i criteri del sistema operativo, che può automatizzare il deployment e la manutenzione delle configurazioni software come Agenti Google Cloud Observability: Ops Agent, l'agente Monitoring legacy e l'agente Logging legacy.

Crea un criterio dell'agente

Questa sezione descrive l'utilizzo dell'SDK Google Cloud per la gestione dei 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 l'hai ancora fatto, installa il componente beta dell'interfaccia a riga di comando gcloud:

    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 il seguente script per attivare le API e impostare le autorizzazioni appropriate per l'utilizzo di Google Cloud CLI: set-permissions.sh.

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

  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 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 degli agenti

Per controllare l'impatto sui sistemi di produzione durante il lancio, è consigliabile puoi utilizzare le etichette e le zone delle istanze per filtrare le istanze a cui il criterio a cui si applica.

Se stai creando un criterio per Ops Agent, assicurati che le tue VM non hanno installato l'agente Logging o l'agente Monitoring legacy. L'esecuzione Ops Agent e gli agenti legacy sulla stessa VM possono 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 l'agente Ops.

Ecco un esempio di un 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 il criterio in modo che abbia 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 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 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

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 del comando e come suggerito dal messaggio di errore.

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

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 riesce e restituisce un errore di autorizzazione: assicurati di aver eseguito lo script set-permissions.sh come descritto in Crea un criterio dell'agente per impostare i ruoli dei criteri di 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 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 nel messaggio di errore, devi ancora eseguire 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 POLICY_ID in uso in gcloud beta compute instances ops-agents policies describe, update o Il comando delete corrisponde a un criterio esistente. Per ottenere un elenco di criteri agenti, utilizza il comando gcloud beta compute instances ops-agents policies list.

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

Gli agenti di configurazione del sistema operativo vengono dipartiti in ogni istanza Compute Engine per gestire i pacchetti per gli agenti Logging e Monitoring. Il criterio potrebbe non avere alcun effetto se l'agente di configurazione del sistema operativo sottostante non è installato.

Linux

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

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 ed esegui il seguente comando PowerShell. Non sono necessari privilegi di amministratore.

    Get-Service google_osconfig_agent

Un esempio di output è:

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

Se l'agente OS Config non è installato, è possibile che sia in uso un che non supporta VM Manager. La Documento sui dettagli del sistema operativo di Compute Engine indica quali funzionalità di VM Manager sono supportate il 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, controllare il log dell'agente OS Config. Puoi farlo utilizzando Logs Explorer o SSH o RDP per controllare le singole istanze 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 lo scriptset-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 il seguente 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:

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

Può essere utile attivare la registrazione a livello di debug nell'agente OS Config quando si segnala 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 maggiori informazioni e aiutarti con 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 attivare il logging a livello di debug per una VM, esegui il comando seguente:

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

Dopo aver scaricato lo script set-permissions.sh, può utilizzare lo script per eseguire le azioni seguenti, in base agli argomenti che fornisci:

Gli esempi seguenti mostrano alcune chiamate comuni allo script. Per ulteriori informazioni, consulta i commenti nello script stesso.

Per abilitare le API, concedi i ruoli necessari all'account di servizio predefinito e attiva i metadati di OS Config per un progetto eseguendo 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 hanno il ruolo Proprietario (roles/owner) per il progetto, esegui lo script come che segue:

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

Per concedere inoltre a uno dei ruoli OS Config un ruolo non predefinito account di servizio, 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

Dati 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 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 questo 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

Scopri come applicare o rimuovere un file Terraform. consulta la sezione Nozioni di base su Terraform comandi. Per informazioni su come funziona Terraform, consulta Utilizzo di Terraform.

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