Agent-Richtlinien verwalten

Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

Agent-Richtlinien ermöglichen die automatische Installation und Wartung der Google Cloud Observability Agents auf einer Reihe von Compute Engine-VMs, die den vom Nutzer angegebenen Kriterien entsprechen. Mit einem Befehl können Sie eine Richtlinie für ein Google Cloud-Projekt erstellen, die vorhandene und neue VMs regelt, die mit diesem Google Cloud-Projekt verknüpft sind. Dadurch werden die ordnungsgemäße Installation und optionale automatische Upgrades aller Google Cloud Observability-Agents auf diesen VMs sichergestellt.

Agent-Richtlinien werden mithilfe der Befehlsgruppe gcloud beta compute instances ops-agents policies in der Google Cloud CLI erstellt und verwaltet. Mit den Befehlen in dieser Gruppe werden die VM Manager -Tools in Compute Engine zum Verwalten Betriebssystemrichtlinien verwendet, mit denen die Bereitstellung und Wartung von Softwarekonfigurationen wie den Google Cloud-Agents für Beobachtbarkeit (Ops-Agent, Legacy-Monitoring-Agent und Legacy-Logging-Agent) automatisiert werden kann.

Unterstützte Betriebssysteme

Sie können eine Agent-Richtlinie auf Compute Engine-VM-Instanzen anwenden, auf denen die in der folgenden Tabelle aufgeführten Betriebssysteme ausgeführt werden. In der Tabelle sind die Agent-Spalten einem Agent-Typ zugeordnet, der für den gcloud beta compute instances ops-agents policies-create-Aufruf angegeben ist:

• Der Logging-Agent ist Richtlinien mit dem Agent-Typ logging zugeordnet.
• Monitoring-Agent ist Richtlinien mit dem Agent-Typ metrics zugeordnet.
• Ops-Agent ist Richtlinien mit dem Agent-Typ ops-agent zugeordnet.

Betriebssystem	Logging-Agent	Monitoring-Agent	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)
Deep Learning VM Images basierend auf 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): 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-*, opensuse-leap-15-4-*)
Windows Server: 2016, 2019, 2022, Core 2016, Core 2019, Core 2022

¹ Der Monitoring-Agent wird auf rhel-7-9-sap-ha, rhel-8-2-sap-ha und rhel-8-4-sap-ha nicht unterstützt.

Agent-Richtlinie erstellen

Führen Sie die folgenden Schritte aus, um eine Agent-Richtlinie mithilfe der Google Cloud CLI zu erstellen:

1. Installieren Sie das Google Cloud CLI, falls noch nicht geschehen.

   In diesem Dokument wird die beta-Befehlsgruppe zum Verwalten von Agent-Richtlinien beschrieben.

2. Falls noch nicht geschehen, installieren Sie die Komponente beta der gcloud CLI.

   gcloud components install beta
   

   Prüfen Sie mit dem folgenden Befehl, ob die Komponente beta für die installierte Komponente vorhanden ist:

   gcloud components list
   

   Wenn Sie die Komponente beta bereits installiert haben, prüfen Sie, ob Sie die neueste Version haben:

   gcloud components update
   

3. Verwenden Sie das folgende Skript, um die APIs zu aktivieren und die richtigen Berechtigungen für die Verwendung des Google Cloud CLI festzulegen: set-permissions.sh.

   Weitere Informationen zum Skript finden Sie unter Was macht das Skript set-permissions.sh?.

   Hinweis: Das Skript set-permissions.sh wurde für die Ausführung unter Linux entwickelt. Wenn Sie einen Computer mit einem anderen Betriebssystem verwenden, führen Sie das Skript über Cloud Shell aus.

4. Verwenden Sie den Befehl gcloud beta compute instances ops-agents policies create, um eine Richtlinie zu erstellen. Informationen zur Syntax des Befehls finden Sie in der Dokumentation zu gcloud beta compute instances ops-agents policies create.

   Beispiele zum Formatieren des Befehls finden Sie in der Dokumentation zur Google Cloud CLI im Abschnitt Beispiele.

   Weitere Informationen zu den anderen Befehlen in der Befehlsgruppe und den verfügbaren Optionen finden Sie in der gcloud beta compute instances ops-agents policies-Dokumentation.

Best Practices für die Verwendung von Agent-Richtlinien

Um die Auswirkungen auf Produktionssysteme während des Roll-outs zu kontrollieren, empfehlen wir Ihnen, Instanzlabels und Zonen zu verwenden, um die Instanzen zu filtern, für die die Richtlinie gilt.

Achten Sie beim Erstellen einer Richtlinie für den Ops-Agent darauf, dass auf Ihren VMs nicht der Legacy-Logging- oder -Monitoring-Agent installiert ist. Das Ausführen des Ops-Agents und der Legacy-Agents auf derselben VM kann zur Aufnahme doppelter Logs oder zu einem Konflikt bei der Messwertaufnahme führen. Falls erforderlich, deinstallieren Sie den Monitoring-Agent und deinstallieren Sie den Logging-Agent, bevor Sie eine Richtlinie zum Installieren des Ops-Agent erstellen.

Hier ist ein Beispiel für einen gestaffelten Rolloutplan für CentOS 7-VMs in einem Projekt namens my_project:

Phase 1: Erstellen Sie eine Richtlinie mit dem Namen ops-agents-policy-safe-rollout, um den Ops-Agent auf allen VMs mit den Labels env=test und app=myproduct zu installieren.

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

Weitere Informationen zum Angeben des Betriebssystems finden Sie unter gcloud beta compute instances ops-agents policies create.

Phase 2: Aktualisieren Sie diese Richtlinie, um VMs mit den Labels env=prod und app=myproduct in einer einzelnen Zone als Ziel zu verwenden.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c \

Phase 3: Aktualisieren Sie die Richtlinie, um den Zonenfilter zu bereinigen, sodass ein globaler Rollout erfolgen kann.

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

Beschränkungen

Damit eine Richtlinie auf VMs wirksam wird, die aus der Zeit vor OS Config ausgeführt wurden, ist eine zusätzliche Einrichtung erforderlich. Dadurch wird sichergestellt, dass der OS Config-Agent, auf den sich die Richtlinie stützt, auf den VMs installiert ist. Führen Sie die folgenden Schritte aus, um den OS Config-Agent auf einer Reihe von VMs zu installieren:

1. Prüfen Sie, ob das Skript set-permissions.sh im Abschnitt Agent-Richtlinie erstellen ausgeführt wurde.

2. Identifizieren Sie die VMs, auf denen Sie den OS Config-Agent installieren möchten, und listen Sie sie in einer CSV-Datei auf. Führen Sie beispielsweise den folgenden Befehl aus, um eine Liste der VMs abzurufen, die nicht von Google Kubernetes Engine, App Engine oder anderen Google Cloud-Diensten verwaltet werden, und diese dann in einer Datei namens instances.csv zu speichern:

     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
   

   Im Abschnitt grep werden die VMs herausgefiltert, auf denen der OS Config-Agent bereits installiert und aktiviert ist. Der Ausschluss von VM-Labels basierend auf goog- filtert Compute Engine-VMs heraus, die von GKE, App Engine und anderen Diensten verwaltet werden.

   Wenn Sie die Instanzen weiter nach Zonen oder Labels filtern möchten, ändern Sie den Wert des Flags --filter in etwa so:

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

3. Laden Sie das Skript mass-install-osconfig-agent.sh herunter und führen Sie es aus, um den OS Config-Agent auf Linux-VMs zu installieren.

   Hinweis: Mit dem Skript mass-install-osconfig-agent.sh, das die Anleitung zum Installieren des OS Config-Agents automatisiert, kann der OS Config-Agent nur auf Linux-VMs installiert werden. Wenn Sie Windows-VMs haben, führen Sie die Installationsanleitung manuell aus.

   Mit dem folgenden Befehl wird der OS Config-Agent auf den in der Datei instances.csv angegebenen VMs im angegebenen Projekt installiert:

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

   Weitere Informationen zur Verwendung des Skripts finden Sie in den Kommentaren im Skript.

Fehlerbehebung

Die ops-agents policy-Befehle schlagen fehl

Wenn ein gcloud beta compute instances ops-agents policies-Befehl fehlschlägt, wird in der Antwort ein Validierungsfehler angezeigt. Korrigieren Sie die Fehler, indem Sie die Befehlsargumente und Flags entsprechend der Fehlermeldung korrigieren.

Zusätzlich zu den Validierungsfehlern können die folgenden Fehler auftreten:

• Unzureichende IAM-Berechtigung

  Ein Fehler dieser Art sieht in etwa so aus:

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

  Führen Sie das Skript set-permissions.sh im Abschnitt Agent-Richtlinie erstellen aus, um die für osconfig.guestPolicy spezifische IAM-Rolle einzurichten.

  Mit dem folgenden Befehl können Sie prüfen, ob eine ausreichende OS Config-Gastrichtlinienrolle für das Projekt aktiviert ist. In diesem Beispiel wird mit dem Befehl geprüft, ob der Nutzer die Rolle roles/osconfig.guestPolicyAdmin hat. Der Wert für GCLOUD_MEMBER muss das Format user:USER_EMAIL oder serviceaccount:SERVICE_ACCOUNT_EMAIL haben.

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

  Folgende Ausgabe wird erwartet:

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

• OS Config API ist nicht aktiviert

  Ein Fehler dieser Art sieht in etwa so aus:

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

  Führen Sie das Skript set-permissions.sh im Bereich Agent-Richtlinie erstellen aus, um alle erforderlichen Berechtigungen zu gewähren.

  Mit den folgenden Befehlen können Sie prüfen, ob die OS Config API für das Projekt aktiviert ist:

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

  Folgende Ausgabe wird erwartet:

  osconfig.googleapis.com    Cloud OS Config API
  

• Die Richtlinie existiert nicht.

  Ein Fehler dieser Art sieht in etwa so aus:

  NOT_FOUND: Requested entity was not found
  

  Möglicherweise wurde die Richtlinie bereits gelöscht. Prüfen Sie, ob die Richtlinien-ID im Befehl describe, update oder delete einer vorhandenen Richtlinie zugeordnet ist.

Die Richtlinie wurde erstellt, hat aber scheinbar keine Auswirkungen

OS Config-Agents werden auf jeder Compute Engine-Instanz bereitgestellt, um die Pakete für die Logging- und Monitoring-Agents zu verwalten. Die Richtlinie hat möglicherweise keine Auswirkungen, wenn der zugrunde liegende OS Config-Agent nicht installiert ist.

LINUX

Mit dem folgenden Befehl können Sie prüfen, ob der OS Config-Agent installiert ist.

gcloud compute ssh instance-id \
    --project project-id \
    -- sudo systemctl status google-osconfig-agent

Die Ausgabe sieht beispielsweise so aus:

    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

Mit den folgenden Schritten können Sie prüfen, ob der OS Config-Agent installiert ist.

1. Stellen Sie mithilfe von RDP oder einem ähnlichen Tool eine Verbindung zu Ihrer Instanz her und melden Sie sich bei Windows an.

2. Öffnen Sie ein PowerShell-Terminal und führen Sie den folgenden PowerShell-Befehl aus. Sie benötigen keine Administratorberechtigungen.

   Get-Service google_osconfig_agent
   

Die Ausgabe sieht beispielsweise so aus:

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

Bei Compute Engine-Instanzen mit SUSE oder Ubuntu ist der OS Config-Agent nicht vorinstalliert. Folgen Sie daher der instructions für die OS Config-Agent-Installation, um den OS Config-Agent auf diesen Compute Engine-Instanzen zu installieren.

Der OS Config-Agent ist installiert, aber die Ops-Agents werden nicht installiert

Um festzustellen, ob Fehler auftreten, wenn der OS Config-Agent Richtlinien anwendet, können Sie das Log des OS Config-Agents prüfen. Dazu können Sie entweder den Log-Explorer verwenden oder einzelne Compute Engine-Instanzen über SSH oder RDP prüfen.

Verwenden Sie den folgenden Filter, um die OS Config-Agent-Logs im Log-Explorer aufzurufen:

resource.type="gce_instance"
logName="projects/PROJECT_ID/logs/OSConfigAgent"

Führen Sie den folgenden Befehl aus, um die OS Config-Agent-Logs mithilfe von SSH für einzelne Linux-Instanzen von Compute Engine aufzurufen:

• 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"
  

Führen Sie die folgenden Schritte aus, um die OS Config-Agent-Logs über RDP für einzelne Windows-Instanzen von Compute Engine aufzurufen:

1. Stellen Sie mithilfe von RDP oder einem ähnlichen Tool eine Verbindung zu Ihrer Instanz her und melden Sie sich bei Windows an.

2. Öffnen Sie die Anwendung Event Viewer unter Windows Logs => Application und suchen Sie nach Logs mit Source, die gleich OSConfigAgent sind.

Wenn beim Herstellen der Verbindung zum OS Config-Dienst ein Fehler auftritt, führen Sie das Skript set-permissions.sh aus dem Abschnitt Agent-Richtlinie erstellen aus, um die Metadaten einzurichten.

Mit dem folgenden Befehl können Sie prüfen, ob die OS Config-Metadaten aktiviert sind.

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

Folgende Ausgabe wird erwartet:

- key: enable-guest-attributes
  value: 'TRUE'
- key: enable-osconfig
  value: 'TRUE'

Beobachtbarkeits-Agents wurden installiert, funktionieren aber nicht richtig

Informationen zum Debuggen bestimmter Agents finden Sie in den folgenden Dokumenten:

• Fehler beim Ops-Agent beheben
• Fehler beim Legacy-Logging-Agent beheben
• Fehler beim Legacy-Monitoring-Agent beheben

Logs auf Debug-Ebene für den OS Config-Agent aktivieren

Wenn Sie ein Problem melden, kann es hilfreich sein, das Logging auf Debug-Ebene im OS Config-Agent zu aktivieren.

Sie können die osconfig-log-level: debug-Metadaten festlegen, um das Logging auf Debug-Ebene für den OS Config-Agent zu aktivieren Die dabei erfassten Logs bieten Ihnen weitere Informationen für die Untersuchung.

Führen Sie den folgenden Befehl aus, um das Logging auf Debug-Ebene für das gesamte Projekt zu aktivieren:

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Führen Sie den folgenden Befehl aus, um das Logging auf Debug-Ebene für eine VM zu aktivieren:

gcloud compute instances add-metadata INSTANCE_ID \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Was macht das Skript set-permissions.sh?

Wenn eine Projekt-ID, eine IAM-Rolle und eine E-Mail-Adresse oder ein Dienstkonto festgelegt sind, führt das Skript set-permissions.sh die folgenden Aktionen aus:

• Für das Projekt werden die Cloud Logging API, die Cloud Monitoring API und die OS Config API aktiviert.

• Dem Compute Engine-Standarddienstkonto werden die Rollen roles/logging.logWriter und roles/monitoring.metricWriter gewährt, damit die Agents Logs und Messwerte in die Logging API und in die Cloud Monitoring API schreiben können.

• Die OS Config-Metadaten für das Projekt werden aktiviert, sodass OS Config-Agents auf den VMs aktiviert werden.

• Dem gcloud-Nutzer oder dem Dienstkonto werden die angegebenen IAM-Rollen gewährt. Projektinhaber haben uneingeschränkten Zugriff zum Erstellen und Verwalten einer Richtlinie. Allen anderen Nutzern oder Dienstkonten müssen Projektinhaber eine der folgenden Rollen zuweisen:

  • roles/osconfig.guestPolicyAdmin: Bietet vollständigen Zugriff auf eine Richtlinie.

  • roles/osconfig.guestPolicyEditor: Ermöglicht Nutzern, eine Richtlinie abzurufen, zu aktualisieren und aufzulisten.

  • roles/osconfig.guestPolicyViewer: Gewährt Lesezugriff zum Abrufen und Auflisten einer Richtlinie.

  Wenn Sie das Skript ausführen, müssen Sie nur den Teil guestPolicy* des Rollennamens angeben. Das Skript stellt den Teil roles/osconfig. des Namens bereit.

Mit dem folgenden Aufruf des Skripts werden die APIs aktiviert, dem Standarddienstkonto die erforderlichen Rollen zugewiesen und die OS Config-Metadaten aktiviert:

bash set-permissions.sh --project=PROJECT_ID

Wenn Sie das Skript verwenden möchten, um einem Nutzer, der nicht die Rolle roles/owner (Inhaber) für das Projekt hat, eine der OS Config-Rollen zuzuweisen, führen Sie das Skript so aus:

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

Wenn Sie das Skript verwenden möchten, um einem nicht standardmäßigen Dienstkonto auch eine der OS Config-Rollen zuzuweisen, führen Sie das Skript so aus:

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

Weitere Informationen finden Sie im Inhalt des Skripts.

Was macht das Skript diagnose.sh?

Wenn ein Projekt, eine Compute Engine-Instanz-ID und eine Ops-Agent-Richtlinien-ID angegeben werden, erfasst das diagnose.sh-Skript automatisch die erforderlichen Informationen, um Probleme mit der Richtlinie zu diagnostizieren:

• Die Version des OS Config-Agents

• Die zugrunde liegende OS Config-Gastrichtlinie

• Die für diese Compute Engine-Instanz geltenden Richtlinien

• Die Repositories des Agent-Pakets, die in eine Compute Engine-Instanz geladen werden

Einbindung von Terraform

Die Terraform-Unterstützung basiert auf den Befehlen des Google Cloud CLI. Folgen Sie der Terraform-Modulanleitung, um eine Agent-Richtlinie mit Terraform zu erstellen.