Fehlerbehebung bei VM Manager

In diesem Dokument wird beschrieben, wie Sie Probleme mit VM Manager beheben.

Weitere Informationen zu VM Manager finden Sie unter VM Manager.

Hinweise

  • Richten Sie die Authentifizierung ein, falls Sie dies noch nicht getan haben. Bei der Authentifizierung wird Ihre Identität für den Zugriff auf Google Cloud Dienste und APIs überprüft. Zum Ausführen von Code oder Beispielen aus einer lokalen Entwicklungsumgebung können Sie sich so bei der Compute Engine authentifizieren:

    Wählen Sie den Tab für die gewünschte Verwendung der Beispiele auf dieser Seite aus:

    Console

    Wenn Sie über die Google Cloud Console auf Dienste und APIs von Google Cloud zugreifen, müssen Sie die Authentifizierung nicht einrichten.

    gcloud

    1. Installieren Sie die Google Cloud CLI. Initialisieren Sie die Google Cloud CLI nach der Installation mit dem folgenden Befehl:

      gcloud init

      Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  • Legen Sie eine Standardregion und -zone fest.
  • REST

    Wenn Sie die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, verwenden Sie die Anmeldedaten, die Sie der gcloud CLI bereitstellen.

      Installieren Sie die Google Cloud CLI.

      Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

    Weitere Informationen finden Sie in der Dokumentation zur Google Cloud -Authentifizierung unter Für die Verwendung von REST authentifizieren.

Übersicht

Um Probleme zu beheben, prüfen Sie zuerst, ob VM Manager ordnungsgemäß eingerichtet ist. Wenn die Einrichtung korrekt ist und weiterhin Probleme auftreten, prüfen Sie die Logs. Beim Prüfen von Logs können Sie Probleme mit Ihrer VM oder in Ihrem VM Manager-Workflow ermitteln, z. B. Fehler in Befehlen oder Skripts, die Sie isolieren und beheben können.

Sie können die folgenden Informationen aus Logs erfassen:

  • Jede von der VM protokollierte Fehlermeldung oder Warnung. Anhand dieser Logs können Sie Fehler auf VM-Ebene oder Fehler von anderen Diensten, die auf Ihrer VM ausgeführt werden, identifizieren. Informationen zum Prüfen dieser Logs finden Sie unter Cloud Logging prüfen.

  • Ausführliche Debug-Informationen, die vom OS Config-Agent protokolliert wurden. Mithilfe dieser Logs können Sie Probleme mit den von VM Manager ausgeführten Vorgängen identifizieren. Informationen zum Prüfen von Debug-Logs für den OS Config-Agent finden Sie unter Debug-Logs prüfen.

Nachdem Sie die Probleme oder Fehler identifiziert haben, können Sie sich auch den Abschnitt Häufige Fehler ansehen, um mögliche Lösungen zu finden, oder die Problemumgehung für die Verwaltung von Patch-Bereitstellungen in einer Organisation lesen.

Cloud Logging prüfen

Sie können die Google Cloud Console-Quick-Links für jedes Feature verwenden, um Logs aufzurufen.

OS patch

  1. Rufen Sie in der Google Cloud Console auf der Seite Patch den Tab Ausgeführte Jobs auf.

    Zu „Jobs ausführen“

  2. Klicken Sie auf den Namen des Patchjobs, den Sie debuggen möchten.
  3. Rufen Sie den Abschnitt Aktualisierte VM-Instanzen auf.
  4. Klicken Sie für eine bestimmte VM unter Logs auf Aufrufen.

Betriebssystemrichtlinien

Dieses Verfahren wird für Betriebssystemrichtlinien unterstützt. Verwenden Sie für Gastrichtlinien (Beta) die Option „Debugging-Logs“ im folgenden Abschnitt.

  1. Rufen Sie in der Google Cloud Console den Tab VM-Instanzen auf der Seite Betriebssystemrichtlinien auf.

    Zu "VM-Instanzen"

  2. Klicken Sie auf den Namen der VM, die Sie debuggen möchten.
  3. Gehen Sie zum Abschnitt Richtlinien.
  4. Klicken Sie unter Logs auf Aufrufen.

Orchestratoren für Betriebssystemrichtlinien

  1. Rufen Sie in der Google Cloud Console auf der Seite Betriebssystemrichtlinien den Tab Orchestratoren für Betriebssystemrichtlinien auf.

    Zu „Orchestratoren für Betriebssystemrichtlinien“

  2. Klicken Sie auf den Namen des Orchestrators für Betriebssystemrichtlinien, den Sie debuggen möchten.
  3. Gehen Sie zum Abschnitt Logs und prüfen Sie den Logeintrag.

Debug-Logs prüfen

Sie können Probleme mit einem beliebigen VM Manager-Feature ermitteln, indem Sie das Debugging für den OS Config-Agent aktivieren und das Debug-Log aufrufen.

Debug-Logging für den OS Config-Agent aktivieren

Sie können das Debug-Logging durch Festlegen der Metadaten osconfig-log-level=debug für die VM-Instanz oder das Projekt aktivieren.

Führen Sie die folgenden Schritte aus, um das Debug-Logging auf Ihrer VM zu aktivieren:

Console

  1. Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf.

    Zur Seite „VM-Instanzen“

  2. Klicken Sie auf den Namen der VM, für die Sie den Metadatenwert festlegen möchten.

  3. Klicken Sie auf der Seite Instanzdetails auf Bearbeiten, um die Einstellungen zu bearbeiten.

  4. Fügen Sie unter Benutzerdefinierte Metadaten die folgenden Metadateneinträge hinzu:

    Schlüssel: osconfig-log-level
    Wert: debug

  5. Klicken Sie auf Speichern, um Ihre Änderungen für die VM zu übernehmen.

gcloud

Führen Sie den Befehl instances add-metadata mit dem Flag --metadata=osconfig-log-level=debug aus.

gcloud compute instances add-metadata VM_NAME \
    --metadata=osconfig-log-level=debug

Ersetzen Sie VM_NAME durch den Namen Ihrer VM.

REST

Wie Sie Instanzmetadaten festlegen, erfahren Sie in der API-Anleitung unter Metadaten der Instanz festlegen.

Das folgende Schlüssel/Wert-Paar ist als Teil des Metadatenattributs erforderlich:

Schlüssel: osconfig-log-level
Wert: debug

Debug-Logs ansehen

Wenn das Debug-Logging aktiviert ist, schreibt der OS Config-Agent Logeinträge in Cloud Logging und in die serielle Port-Konsole.

Nachdem Sie das Debug-Logging auf der VM aktiviert haben, dauert es etwa zehn Minuten, bis der OS Config-Agent Debug-Nachrichten in Cloud Logging schreibt. Sie können die Wartezeit verkürzen, indem Sie den Agent neu starten oder Ihre VM neu starten. Weitere Informationen zu Cloud Logging finden Sie unter Logs von Cloud Logging ansehen.

Sie können die folgenden Optionen verwenden, um Debug-Logs aufzurufen:

  • Cloud Logging: Verwenden Sie die Google Cloud Console oder die Google Cloud CLI.
  • Serielle Port-Konsole

Console

  1. Rufen Sie in derGoogle Cloud Console die Seite Logging > Log-Explorer auf:

    Zum Log-Explorer

  2. Wählen Sie bei Bedarf oben auf der Seite ein vorhandenes Google Cloud -Projekt aus oder erstellen Sie ein neues Projekt.

  3. Wählen Sie in der Drop-down-Liste Ressource die Option VM-Instanz aus. Eine Liste der verfügbaren VMs (instance_id) wird angezeigt.

  4. Klicken Sie auf die VM, die Sie aufrufen möchten.

  5. Klicken Sie auf Hinzufügen.

  6. Wählen Sie in der Drop-down-Liste Logname die Option OSConfigAgent aus.

  7. Klicken Sie auf Hinzufügen.

  8. Die Abfrage sollte in etwa so aussehen:

    resource.type="gce_instance" resource.labels.instance_id="INSTANCE_ID"
    logName="projects/PROJECT_ID/logs/OSConfigAgent"
    
  9. Klicken Sie auf Abfrage ausführen.

gcloud

Führen Sie den Befehl gcloud logging read aus:

 gcloud logging read "resource.type=gce_instance AND logName=projects/PROJECT_ID/logs/OSConfigAgent"
 

Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

Serieller Port

Wenn Sie Informationen zu Debug-Logs über die serielle Port-Konsole ansehen möchten, finden Sie dazu weitere Informationen unter Ausgabe des seriellen Ports ansehen.

Häufige Fehler

Authentifizierungsprobleme

Damit VM Manager funktioniert, müssen folgende Voraussetzungen erfüllt sein:

  • Ein angehängtes Dienstkonto. VM Manager verwendet dieses Dienstkonto, um Anfragen an den API-Dienst zu signieren.
  • Prüfen Sie, ob das angehängte Dienstkonto die Rolle roles/logging.logWriter zum Schreiben von Logs in die Logging API hat.
  • Google Cloud OS Config-Dienst-Agent. VM Manager erstellt diesen Dienst-Agent beim Starten von Patch-Jobs und weist ihm die Rolle „Cloud OS Config-Dienst-Agent“ zu. Zum Erstellen von Betriebssystemrichtlinien müssen Sie diesen Dienst-Agent nicht konfigurieren.

Wenn Sie VM Manager verwenden und kein angehängtes Dienstkonto oder keinen Google Cloud OS Config-Dienst-Agent haben, werden bei der Arbeit mit Patch-Jobs möglicherweise die folgenden Fehler angezeigt:

Service account permissions are missing. Verify that the service account has the correct permissions and try again.
OSConfigAgent Error main.go:88: error getting token from metadata: metadata: GCE metadata "instance/service-accounts/default/identity?audience=osconfig.googleapis.com&format=full" not defined
message: "Error running OPERATION_NAME: error calling OPERATION_NAME: code: "PermissionDenied", message: "The caller does not have permission", details: []"

Authentifizierungsprobleme können auch verhindern, dass VM-Instanzen im Patch-Dashboard angezeigt werden.

Versuchen Sie Folgendes, um diese Probleme zu beheben:

  • Prüfen Sie, ob alle VMs ein angehängtes Dienstkonto haben.
  • Prüfen Sie, ob die Rolle „Cloud OS Config-Dienst-Agent“ (roles/osconfig.serviceAgent) für den Google Cloud OS Config-Dienst-Agent festgelegt ist.

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-osconfig.iam.gserviceaccount.com' \
      --role='roles/osconfig.serviceAgent'
    

    Dabei gilt:

Fehler beim Ausschließen von Paketen für Patchupdates

Wenn Sie Platzhalter oder Sonderzeichen für den Namen des Pakets angeben, wenn Sie Pakete in einem Patch-Job ausschließen, ignoriert OS Patch Management die Liste möglicherweise und aktualisiert alle Pakete.

Um dieses Problem zu beheben, aktualisieren Sie den OS Config-Agent auf Version 20220829.00 und verwenden Sie Schrägstriche (/), um den Paketnamen zu umschließen.

Im folgenden Beispiel schließt OS Patch Management yum-Pakete mit dem Präfix google- im Paketnamen aus.

      gcloud compute os-config patch-jobs execute --instance-filter-all 
--yum-excludes=/google-.*/

Problemumgehung für die Verwaltung von Patch-Deployments in einer Organisation

Patch-Deployments und Patchjobs sind auf einzelne Google Cloud -Projekte beschränkt, im Gegensatz zu Betriebssystemrichtlinien, die Sie mit Richtlinien-Orchestratoren in einer Organisation oder einem Ordner orchestrieren können.

Als Behelfslösung für die Verwaltung von Patch-Deployments in großem Umfang können Sie Cloud Asset Inventory und die Google Cloud CLI in einem Bash-Script verwenden, um alle Projekte in Ihrer Organisation zu durchlaufen. Mit diesem Script können Sie die folgenden Aufgaben ausführen:

  1. VM Manager projektübergreifend aktivieren

  2. Projektübergreifendes Patch-Deployment erstellen

  3. Ergebnisse von Patchjobs projektübergreifend in eine CSV-Datei exportieren

Erforderliche Berechtigungen und Organisations-ID

Bevor Sie die Skripts in diesem Abschnitt ausführen, müssen Sie die erforderlichen IAM-Berechtigungen (Identity and Access Management) und Ihre Organisations-ID haben:

  • Organisationsebene: Wenn Sie alle Projekte in Ihrer Organisation mit Cloud Asset Inventory auflisten möchten, muss Ihr Nutzerkonto oder Dienstkonto die Berechtigung cloudasset.assets.searchAllResources (in der Rolle „Cloud Asset Viewer“, roles/cloudasset.viewer enthalten) für die Organisation haben.

  • Zielprojektebene: Je nach den Aufgaben, die Sie in Ihrer Organisation ausführen, muss Ihr Nutzerkonto oder Dienstkonto die folgenden Berechtigungen für jedes Zielprojekt haben (z. B. von einer Rollenbindung auf Organisationsebene übernommen):

    • Zum Aktivieren der OS Config API und zum Festlegen von Projektmetadaten: serviceusage.services.enable (Service Usage-Administrator, roles/serviceusage.serviceUsageAdmin) und compute.projects.setCommonInstanceMetadata (Compute-Instanzadministrator (v1), roles/compute.instanceAdmin.v1).

    • Zum Erstellen von Patch-Deployments: osconfig.patchDeployments.create (OS Config Patch Deployment Admin, roles/osconfig.patchDeploymentAdmin).

    • Zum Auflisten von Patchjobs und Aufrufen von VM-Instanzdetails: osconfig.patchJobs.list und osconfig.patchJobs.get (OS Config Patch Job Viewer, roles/osconfig.patchJobViewer).

Führen Sie den Befehl gcloud projects get-ancestors für ein beliebiges Projekt in Ihrer Organisation aus, um Ihre Organisations-ID zu ermitteln:

gcloud projects get-ancestors PROJECT_ID

Ersetzen Sie PROJECT_ID durch die ID eines Projekts in Ihrer Organisation. In der Ausgabe werden die übergeordneten Ordner des Projekts und die organization-ID aufgeführt.

VM Manager projektübergreifend aktivieren

Wenn Sie VM Manager für alle vorhandenen und zukünftigen Projekte in einer Organisation oder einem Ordner aktivieren möchten, empfiehlt Google die Verwendung von hierarchischen Dienstaktivierungs- und Organisationsrichtlinien oder Terraform.

Alternativ können Sie die OS Config API (osconfig.googleapis.com) aktivieren und die Projektmetadaten enable-osconfig=TRUE für alle vorhandenen Projekte in Ihrer Organisation mit einem Bash-Skript festlegen. Führen Sie dazu den folgenden Befehl aus:

for project in $(gcloud asset search-all-resources \
    --scope=organizations/ORGANIZATION_ID \
    --asset-types=cloudresourcemanager.googleapis.com/Project \
    --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
  gcloud services enable osconfig.googleapis.com --project="$project"
  gcloud compute project-info add-metadata --project="$project" \
      --metadata=enable-osconfig=TRUE
done

Ersetzen Sie ORGANIZATION_ID durch Ihre Organisations-ID.

Patch-Deployment projektübergreifend erstellen

Wenn Sie einen standardisierten Patch-Bereitstellungszeitplan für alle Projekte in Ihrer Organisation anwenden möchten, erstellen Sie eine Konfigurationsdatei für die Patch-Bereitstellung und wenden Sie sie auf jedes Projekt an:

  1. Erstellen Sie eine JSON- oder YAML-Vorlagendatei mit dem Namen patch_deployment_template.json, in der der Filter für die Zielinstanz, die Patchkonfiguration und der Zeitplan definiert sind. Weitere Informationen zu den unterstützten Konfigurationsfeldern finden Sie unter Patch-Deployment erstellen und in der Ressourcenreferenz zu PatchDeployment.

    In der folgenden patch_deployment_template.json-Datei wird beispielsweise ein wiederkehrender wöchentlicher Patchjob für alle VM-Instanzen in einem Projekt geplant, der jeden Dienstag um 19:30 Uhr in der Zeitzone America/Los_Angeles ausgeführt wird:

    {
      "instanceFilter": {
        "all": true
      },
      "patchConfig": {
        "rebootConfig": "DEFAULT"
      },
      "recurringSchedule": {
        "frequency": "WEEKLY",
        "weekly": {
          "dayOfWeek": "TUESDAY"
        },
        "timeOfDay": {
          "hours": 19,
          "minutes": 30
        },
        "timeZone": {
          "id": "America/Los_Angeles"
        }
      }
    }
    
  2. Führen Sie die folgende Schleife aus, um das Patch-Deployment in jedem Projekt in Ihrer Organisation mit dem Befehl gcloud compute os-config patch-deployments create zu erstellen:

    for project in $(gcloud asset search-all-resources \
        --scope=organizations/ORGANIZATION_ID \
        --asset-types=cloudresourcemanager.googleapis.com/Project \
        --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
      gcloud compute os-config patch-deployments create patch-"$project" \
          --project="$project" \
          --file=patch_deployment_template.json
    done
    

    Ersetzen Sie ORGANIZATION_ID durch Ihre Organisations-ID.

Ergebnisse von Patchjobs projektübergreifend in eine CSV-Datei exportieren

Wenn Sie die Ergebnisse von Patchjobs prüfen möchten, können Sie mit dem Befehl gcloud compute os-config patch-jobs list-instance-details VM-Instanzdetails für fehlgeschlagene oder erfolgreiche Patchjobs in eine CSV-Datei exportieren.

  • Einzelner Patchjob: Führen Sie die folgenden Befehle aus, um die VM-Instanzen zu exportieren, die in einem bestimmten Patchjob fehlgeschlagen sind oder erfolgreich waren:

    • Fehlgeschlagene VM-Instanzen exportieren:

      gcloud compute os-config patch-jobs list-instance-details PATCH_JOB_ID \
          --project=PROJECT_ID \
          --filter="state:(FAILED OR TIMED_OUT OR NO_AGENT_DETECTED)" \
          --format="csv(name.basename():label=INSTANCE_NAME,zone:label=ZONE,state:label=STATE,failureReason:label=FAILURE_REASON)" > failed_patches.csv
      
    • Erfolgreich exportierte VM-Instanzen:

      gcloud compute os-config patch-jobs list-instance-details PATCH_JOB_ID \
          --project=PROJECT_ID \
          --filter="state=SUCCEEDED" \
          --format="csv(name.basename():label=INSTANCE_NAME,zone:label=ZONE,state:label=STATE,attemptCount:label=ATTEMPT_COUNT)" > succeeded_patches.csv
      

    Ersetzen Sie Folgendes:

    • PATCH_JOB_ID: die ID des Patchjobs

    • PROJECT_ID: die Projekt-ID

  • Alle Projekte in einer Organisation: Führen Sie das folgende Script aus, um alle Projekte in Ihrer Organisation zu durchlaufen und fehlgeschlagene und erfolgreiche VM-Instanzen über Patchjobs hinweg in CSV-Dateien zu exportieren:

    echo "PROJECT_ID,PATCH_JOB_ID,INSTANCE_NAME,ZONE,STATE,FAILURE_REASON" > failed_patches.csv
    echo "PROJECT_ID,PATCH_JOB_ID,INSTANCE_NAME,ZONE,STATE,ATTEMPT_COUNT" > succeeded_patches.csv
    
    for project in $(gcloud asset search-all-resources \
        --scope=organizations/ORGANIZATION_ID \
        --asset-types=cloudresourcemanager.googleapis.com/Project \
        --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
      for job in $(gcloud compute os-config patch-jobs list \
          --project="$project" \
          --format="value(name.basename())"); do
        gcloud compute os-config patch-jobs list-instance-details "$job" \
            --project="$project" \
            --filter="state:(FAILED OR TIMED_OUT OR NO_AGENT_DETECTED)" \
            --format="csv[no-heading](name.basename(),zone,state,failureReason)" | \
            sed "s/^/${project},${job},/" >> failed_patches.csv
        gcloud compute os-config patch-jobs list-instance-details "$job" \
            --project="$project" \
            --filter="state=SUCCEEDED" \
            --format="csv[no-heading](name.basename(),zone,state,attemptCount)" | \
            sed "s/^/${project},${job},/" >> succeeded_patches.csv
      done
    done
    

    Ersetzen Sie ORGANIZATION_ID durch Ihre Organisations-ID.

    Standardmäßig gibt der Befehl gcloud compute os-config patch-jobs list bis zu 10 Patchjobs pro Projekt zurück. Wenn Sie nur die Ergebnisse des letzten Patchjobs in jedem Projekt exportieren möchten, fügen Sie dem Befehl gcloud compute os-config patch-jobs list das Flag --sort-by="~update_time" --limit=1 hinzu.

Informationen zur organisationsweiten Patch-Compliance und zu Berichten über Sicherheitslücken in derGoogle Cloud Console oder in BigQuery finden Sie unter Patchübersicht für VMs in einer Organisation oder einem Ordner aufrufen und Berichte zu Sicherheitslücken für Ihre Organisation aufrufen.

Nächste Schritte