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 VMs, die benutzerdefinierten Kriterien entsprechen. Sie können mit einem einzigen Befehl eine Richtlinie für Ihr Google Cloud-Projekt erstellen, die mit diesem Google Cloud-Projekt verknüpfte vorhandene und neue VMs regelt. So sorgen Sie für eine ordnungsgemäße Installation und ein optionales automatisches Upgrade aller Agents.

Unterstützte Betriebssysteme

Sie können eine Agen-Richtlinie auf Compute Engine-Instanzen mit den folgenden Betriebssystemen anwenden.

Logging agent verweist auf Richtlinien mit dem Agent-Typ logging. Monitoring agent verweist auf Richtlinien mit dem Agent-Typ metrics. Ops Agent verweist auf Richtlinien mit dem Agent-Typ ops-agent.

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

Gehen Sie so vor, um mithilfe des Google Cloud CLI eine Agent-Richtlinie zu erstellen:

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

   In der gcloud CLI befindet sich die Befehlsgruppe zum Verwalten von Agent-Richtlinien im Release beta.

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
   

   1. 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: set-permissions.sh wurde für die Ausführung unter Linux entwickelt. Wenn Sie einen Computer auf einem anderen Betriebssystem verwenden, führen Sie das Skript in 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 im Abschnitt Beispiele in der Dokumentation zum Google Cloud CLI.

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

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.

Wenn Sie eine Richtlinie für den Ops-Agent erstellen, achten Sie darauf, dass auf Ihren VMs nicht der Legacy-Logging-Agent oder der Monitoring-Agent installiert ist. Die Ausführung des Ops-Agents und der Legacy-Agents auf derselben VM kann dazu führen, dass doppelte Logs oder ein Konflikt bei der Messwertaufnahme entstehen. Deinstallieren Sie bei Bedarf den Monitoring-Agent und deinstallieren Sie den Logging-Agent, bevor Sie eine Richtlinie erstellen, um den Ops-Agent zu installieren.

Das folgende Beispiel zeigt einen stufenweisen Rolloutplan für VMs mit CentOS 7:

Phase 1: Erstellen Sie eine Richtlinie, um den Ops-Agent auf allen VMs mit dem Label 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 zur Angabe des Betriebssystems finden Sie unter gcloud beta compute instances ops-agents policies create.

Phase 2: Aktualisieren Sie diese Richtlinie, damit sie für env=prod und app=myproduct gilt und auf eine einzelne Zone beschränkt ist.

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 werden kann, die vor OS Config liegen, ist eine zusätzliche Einrichtung erforderlich, damit 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. Vergewissern Sie sich, dass das Skript set-permissions.sh aus dem Abschnitt Agent-Richtlinie erstellen ausgeführt wird.

2. Legen Sie fest, auf welchen VMs Sie den OS Config-Agent installieren möchten, und listen Sie diese in einer CSV-Datei auf.

   Führen Sie Folgendes aus, um eine Liste aller nicht von Google verwalteten Instanzen (z. B. von Google Kubernetes Engine oder Google App Engine) in einer CSV-Datei zu erhalten:

     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 Bereich grep werden die VMs herausgefiltert, auf denen der OS Config-Agent bereits installiert und aktiviert ist. Der VM-Labelausschluss basierend auf goog- filtert Compute Engine-VMs, die von GKE, App Engine usw. verwaltet werden.

   Wenn Sie die Instanzen weiter nach Zonen oder Labels filtern möchten, ändern Sie --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"
   

Hinweis: mass-install-osconfig-agent.sh wurde für die Ausführung unter Linux entwickelt. Wenn Sie einen Computer auf einem anderen Betriebssystem verwenden, führen Sie das Skript in Cloud Shell aus.

1. Laden Sie das Skript mass-install-osconfig-agent.sh herunter und führen Sie es aus. Folgen Sie dabei der Anleitung im Skript, um einen Befehl wie den folgenden auszuführen:

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

   Dieses Skript bietet eine Automatisierung der Anleitung OS Config-Agent installieren.

Fehlerbehebung

Die Befehle der Ops-Agent-Richtlinie schlagen fehl

Wenn die Befehle der Ops-Agent-Richtlinie fehlschlagen, wird ein entsprechender Validierungsfehler angezeigt. Korrigieren Sie diesen Fehler. Ändern Sie dafür die Befehlsargumente sowie die Flags wie in der Fehlermeldung vorgeschlagen.

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.XXX) PERMISSION_DENIED: Caller does not have required permission to XXX
  

  Führen Sie das Skript set-permissions.sh aus dem 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. GCLOUD_MEMBER sollte 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 [XXX].
  Would you like to enable and retry (this will take a few minutes)?
  (y/N)?
  

  Führen Sie das Skript set-permissions.sh aus dem Abschnitt 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, weil 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 Anleitung 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. Verwenden Sie dazu entweder den Log-Explorer oder eine SSH-/RDP-Verbindung zu einzelnen Compute Engine-Instanzen.

Verwenden Sie zum Aufrufen der OS Config-Agent-Logs im Log-Explorer den folgenden Filter:

resource.type="gce_instance"
logName="projects/project-id/logs/OSConfigAgent"

Führen Sie den folgenden Befehl aus, um die OS Config-Agent-Logs für einzelne Compute Engine-Instanzen über SSH 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 Logs des OS Config-Agents über RDP für einzelne Compute Engine-Windows-Instanzen 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'

Ops-Agents sind installiert, funktionieren jedoch nicht ordnungsgemäß

Informationen zur Behebung bestimmter Probleme finden Sie auf den Seiten zur Fehlerbehebung für den Logging-Agent und den Monitoring-Agent.

Logs auf Debug-Ebene aktivieren

Beim Melden eines Problems ist es sehr hilfreich, das Logging auf Debug-Ebene für den 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

Weitere Informationen

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 vollständigen Zugriff für das 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, Richtlinien abzurufen, zu aktualisieren und aufzulisten.

  • roles/osconfig.guestPolicyViewer: Bietet Lesezugriff für das 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 festgelegt sind, erfasst das Skript diagnose.sh automatisch die erforderlichen Informationen, um Probleme in 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 Anleitung zum Terraform-Modul, um eine Agent-Richtlinie mit Terraform zu erstellen.