Agent-Richtlinien verwenden

Agent-Richtlinien ermöglichen die automatische Installation und Wartung der Google Cloud Observability-Agents auf einer Reihe von Compute Engine-VMs, die benutzerdefinierten Kriterien entsprechen. Sie können eine Richtlinie für ein 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, Deinstallation und optional ein automatisches Upgrade aller Google Cloud Observability-Agents auf diesen VMs.

Sie können Agent-Richtlinien mithilfe der Befehlsgruppe gcloud beta compute instances ops-agents policies in der Google Cloud CLI oder dem agent-policy Terraform-Modul erstellen und verwalten. Agent-Richtlinien verwenden die VM Manager -Tools in Compute Engine zur Verwaltung von OS-Richtlinien, die die Bereitstellung und Wartung von Softwarekonfigurationen wie den Google Cloud Observability-Agents automatisieren können: dem Ops-Agent, dem bisherigen Monitoring-Agent und dem bisherigen Logging-Agent.

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:

Agent-Richtlinie erstellen

In diesem Abschnitt wird beschrieben, wie Sie das Google Cloud SDK zum Verwalten von Richtlinien für Kundenservicemitarbeiter verwenden. Informationen zur Verwendung von Terraform finden Sie unter Terraform-Integration.

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.

   Die in diesem Dokument beschriebenen Richtlinien für Kundenservicemitarbeiter verwenden die Befehlsgruppe 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
   

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

   gcloud components update
   

3. Laden Sie das folgende Skript herunter und verwenden Sie es, 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 Skript set-permissions.sh.

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.

   Informationen zu den anderen Befehlen in der Befehlsgruppe und 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.

Hier ein Beispiel für einen stufenweisen Roll-out-Plan für Debian 11-VMs in einem Projekt namens my_project:

Phase 1: Erstellen Sie eine Richtlinie mit dem Namen ops-agents-policy-safe-rollout, um den bisherigen Logging- und Monitoring-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=logging,version=current-major,package-state=installed,enable-autoupgrade=true;type=metrics,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

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 VMs in einer einzelnen Zone mit den Labels env=prod und app=myproduct gilt.

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

Richtlinien für VMs, die vor OS Config erstellt wurden

Möglicherweise müssen Sie den OS Config-Agent manuell auf VMs installieren und konfigurieren, die vor OS Config liegen. Informationen zum manuellen Installieren und Prüfen des OS Config-Agents finden Sie in der Checkliste zur Bestätigung für VM Manager.

Fehlerbehebung bei Beta-Agent-Richtlinien

Dieser Abschnitt enthält Informationen zur Behebung von Problemen mit Beta-Agent-Richtlinien für den Ops-Agent, den bisherigen Monitoring-Agent und den bisherigen Logging-Agent.

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 diesen Fehler. Ändern Sie dafür die Befehlsargumente sowie die Flags wie in der Fehlermeldung vorgeschlagen.

Zusätzlich zu den Validierungsfehlern können Fehler angezeigt werden, die auf die folgenden Bedingungen hinweisen:

• Unzureichende IAM-Berechtigung
• Die OS Config API ist nicht aktiviert
• Die angegebene Richtlinie existiert nicht

Diese Schritte werden in den folgenden Abschnitten näher erläutert.

Unzureichende IAM-Berechtigung

Wenn ein gcloud beta compute instances ops-agents policies-Befehl mit einem Berechtigungsfehler fehlschlägt, führen Sie das Skript set-permissions.sh wie unter Agent-Richtlinie erstellen beschrieben aus, um die OS Config-Richtlinienrollen einzurichten:

• GuestPolicy-Administrator (roles/osconfig.guestPolicyAdmin): Gewährt vollständigen Zugriff auf Gastrichtlinien.
• GuestPolicy-Bearbeiter (roles/osconfig.guestPolicyEditor): Mit dieser Berechtigung können Nutzer Gastrichtlinien abrufen, aktualisieren und auflisten.
• GuestPolicy-Betrachter (roles/osconfig.guestPolicyViewer): Bietet Lesezugriff für das Abrufen und Auflisten von Gastrichtlinien.

Weitere Informationen zum Skript set-permissions.sh finden Sie unter Skript set-permissions.sh.

OS Config API ist nicht aktiviert

Ein Beispiel für einen solchen Fehler sieht 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)?

Sie können y eingeben, um die API zu aktivieren, oder das Skript set-permissions.sh ausführen, wie in Agent-Richtlinie erstellen beschrieben, um alle erforderlichen Berechtigungen zuzuweisen. Wenn Sie bei der Eingabeaufforderung in der Fehlermeldung y eingeben, müssen Sie dennoch das Skript set-permissions.sh ausführen, um die erforderlichen Berechtigungen festzulegen.

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

Die erwartete Ausgabe sieht so aus:

osconfig.googleapis.com    Cloud OS Config API

Die Richtlinie ist bereits vorhanden

Ein Beispiel für einen solchen Fehler sieht so aus:

ALREADY_EXISTS: Requested entity already exists

Dieser Fehler bedeutet, dass diese Richtlinie bereits mit demselben Namen, derselben Projekt-ID und derselben Region vorhanden ist. Sie können dies mit dem Befehl gcloud beta compute instances ops-agents policies describe prüfen.

Die Richtlinie existiert nicht.

Ein Beispiel für einen solchen Fehler sieht so aus:

NOT_FOUND: Requested entity was not found

Dieser Fehler kann bedeuten, dass die Richtlinie nie erstellt oder gelöscht wurde oder dass die angegebene Richtlinien-ID falsch ist. Achten Sie darauf, dass die in einem gcloud beta compute instances ops-agents policies describe-, update- oder delete-Befehl verwendete POLICY_ID einer vorhandenen Richtlinie entspricht. Eine Liste der Agent-Richtlinien rufen Sie mit dem Befehl gcloud beta compute instances ops-agents policies list ab.

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.

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

    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

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

Wenn der OS Config-Agent nicht installiert ist, verwenden Sie möglicherweise ein Betriebssystem, das VM Manager nicht unterstützt. Im Dokument Details zu Betriebssystemen von Compute Engine wird angegeben, welche VM Manager-Features für die einzelnen Compute Engine-Betriebssysteme unterstützt werden.

Wenn das Betriebssystem VM Manager unterstützt, können Sie den OS Config-Agent manuell installieren.

Der OS Config-Agent ist installiert, aber der Monitoring-Agent wird 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 verwenden Sie SSH bzw. RDP, um einzelne Compute Engine-Instanzen zu überprüfen.

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

resource.type="gce_instance"
logId(OSConfigAgent)

So rufen Sie die Logs des OS Config-Agents auf:

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/messages \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/syslog \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Wenn beim Herstellen der Verbindung zum OS Config-Dienst ein Fehler auftritt, führen Sie das Skript set-permissions.sh aus, wie unter Agent-Richtlinie erstellen beschrieben, um die Metadaten von OS Config 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

Die erwartete Ausgabe sieht so aus:

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

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

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

• Ops-Agent – Fehlerbehebung
• Fehlerbehebung beim alten Logging-Agent
• Fehlerbehebung beim Legacy-Monitoring-Agent

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

Beim Melden eines Problems kann es nützlich 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

Hilfsskripts

In diesem Abschnitt finden Sie zusätzliche Informationen zu den in diesem Dokument beschriebenen Hilfsskripts:

• Das Skript set-permissions.sh
• Das Skript diagnose.sh

Das Skript set-permissions.sh

Nachdem Sie das Skript set-permissions.sh heruntergeladen haben, können Sie mithilfe des Skripts die folgenden Aktionen auf der Grundlage der von Ihnen angegebenen Argumente ausführen:

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

• Gewähren Sie dem Compute Engine-Standarddienstkonto die Identitäts- und Zugriffsverwaltungsrollen Logs Writer (roles/logging.logWriter) und Monitoring Metric Writer (roles/monitoring.metricWriter) zu, damit die Agenten Protokolle und Metriken an die Protokollierungs- und Cloud-Überwachungs-APIs schreiben können.

• Aktivieren Sie die OS Config-Metadaten für das Projekt, damit der OS Config-Agent auf jeder VM aktiv ist.

• Weisen Sie dem Nicht-Inhaber-Nutzer oder Dienstkonto, das zum Erstellen und Verwalten von Richtlinien erforderlich ist, eine der folgenden IAM-Rollen zu. Projektinhaber haben vollständigen Zugriff zum Erstellen und Verwalten von Richtlinien. Allen anderen Nutzern oder Dienstkonten muss eine der folgenden Rollen zugewiesen sein:

  • GuestPolicy-Administrator (roles/osconfig.guestPolicyAdmin): Gewährt vollständigen Zugriff auf Gastrichtlinien.
  • GuestPolicy-Bearbeiter (roles/osconfig.guestPolicyEditor): Nutzer können Gastrichtlinien abrufen, aktualisieren und auflisten.
  • GuestPolicy-Betrachter (roles/osconfig.guestPolicyViewer): Bietet Lesezugriff für das Abrufen und Auflisten von Gastrichtlinien.

  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.

Die folgenden Beispiele zeigen einige gängige Aufrufe für das Skript. Weitere Informationen finden Sie in den Kommentaren im Skript selbst.

Zum Aktivieren der APIs weisen Sie dem Standarddienstkonto die erforderlichen Rollen zu und aktivieren die OS Config-Metadaten für ein Projekt. Gehen Sie dazu so vor:

bash set-permissions.sh --project=PROJECT_ID

So führen Sie das Skript aus, um einem Nutzer, der nicht die Rolle "Inhaber" (roles/owner) für das Projekt hat, eine der OS Config-Rollen zuzuweisen:

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

So führen Sie das Skript aus, um einem nicht standardmäßigen Dienstkonto zusätzlich eine der OS Config-Rollen zuzuweisen:

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

Das Skript diagnose.sh

Wenn eine Projekt-ID, eine Compute Engine-Instanz-ID und die Agent-Richtlinien-ID festgelegt sind, erfasst das Skript diagnose.sh automatisch die erforderlichen Informationen zur Diagnose von Problemen mit der Richtlinie:

• 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 diese Compute Engine-Instanz geladen werden

Führen Sie den folgenden Befehl aus, um das Skript aufzurufen:

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

Einbindung von Terraform

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle. Informationen zur Funktionsweise von Terraform finden Sie unter Terraform verwenden.

Die Terraform-Unterstützung für Agent-Richtlinien basiert auf den Befehlen der Google Cloud CLI. Folgen Sie der Anleitung für das Terraform-Modul agent-policy, um eine Agent-Richtlinie mit Terraform zu erstellen. Im Verzeichnis examples finden Sie auch Beispielrichtlinien.