Gastattribute festlegen und abfragen

Gastattribute sind ein bestimmter Typ von benutzerdefinierten Metadaten, in die Anwendungen Daten schreiben können, während sie auf der VM-Instanz ausgeführt werden. Jede Anwendung oder jeder Nutzer auf der VM-Instanz kann Daten aus den Metadatenwerten der Gastattribute lesen und in diese schreiben.

Hinweise

  • Verwenden Sie für Windows Server-VMs PowerShell 3.0 oder höher. Wir empfehlen, die kopierten Codeblöcke mit ctrl+v einzufügen.
  • 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. Zur Ausführung von Code oder Beispielen aus einer lokalen Entwicklungsumgebung können Sie sich so bei Compute Engine authentifizieren.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. REST

      Verwenden Sie die von der gcloud CLI bereitgestellten Anmeldedaten, um die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung zu verwenden.

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

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

Erforderliche Rollen

Die erforderlichen Berechtigungen oder Rollen hängen davon ab, ob Sie Aufgaben innerhalb oder außerhalb der VM ausführen.

Innerhalb der VM

Wenn Sie die Gastattribute innerhalb der VM festlegen, abfragen oder löschen, benötigen Sie nur die Rollen und Berechtigungen zum Herstellen einer Verbindung zur VM. Jeder in der VM-Instanz ausgeführte Prozess kann Daten in die Gastattributwerte schreiben. Das gilt auch für Skripts und Anwendungen, die keine Sudo- oder Administratorberechtigungen haben.

Für Lese- und Schreibvorgänge innerhalb einer VM bietet der Metadatenserver automatische Authentifizierung und Autorisierung auf Instanzebene. Jede VM kann nur auf ihrem eigenen Metadatenserver Daten lesen oder schreiben. Andere VMs können nicht auf den Metadatenserver einer anderen VM zugreifen.

Außerhalb der VM

Die folgenden Rollen und Berechtigungen sind erforderlich, um Gastattribute zu aktivieren oder mithilfe der Google Cloud CLI oder REST Gastattribute von außerhalb der VM aufzurufen. Sie können Gastattribute von außerhalb einer VM weder festlegen noch löschen.

Bitten Sie Ihren Administrator, Ihrem Nutzer oder Dienstkonto die IAM-Rolle Compute Instanz Admin (Version 1) (roles/compute.instanceAdmin.v1) für die VM oder das Projekt zu erteilen, um sicher zu stellen, dass Ihr Nutzer oder Ihr Dienstkonto die erforderlichen Berechtigungen zum Aktivieren oder Aufrufen von Gastattributen hat. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Aktivieren oder Aufrufen von Gastattributen erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Gastattribute zu aktivieren oder aufzurufen:

  • So aktivieren Sie Gastattribute: compute.instances.setMetadata auf der VM oder im Projekt
  • So rufen Sie Gastattribute auf: compute.instances.getGuestAttributes auf der VM oder im Projekt

Ihr Administrator kann Ihrem Nutzer oder Dienstkonto diese Berechtigungen möglicherweise auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erteilen.

Wann sind Gastattribute zu verwenden?

Verwenden Sie Gastattribute nur für Anwendungsfälle, in denen kleine Datenmengen erforderlich sind, die sich nicht häufig ändern. Folgende Anwendungsfälle eignen sich für Gastattribute am besten:

  • Die Anzahl der Abfragen ist auf maximal zehn Abfragen pro Minute und VM-Instanz beschränkt.
  • Es werden niemals mehr als drei Abfragen pro Sekunde ausgeführt. Wenn diese maximale Rate überschritten wird, kann Compute Engine Gastattribute, die gerade geschrieben werden, beliebig entfernen. Durch das Entfernen dieser Daten wird dafür gesorgt, dass andere kritische Systemdaten auf den Server geschrieben werden können.

Gastattribute eignen sich gut für geringe Datenmengen, die selten veröffentlicht werden. Verwenden Sie Gastattribute beispielsweise in folgenden Anwendungsfällen:

  • Startskripts können eine erfolgreiche Initialisierung signalisieren, indem sie einen benutzerdefinierten Statuswert in Gastattributen festlegen.
  • Konfigurationsverwaltungs-Agents können den Namen und die Version eines Gastbetriebssystems in Gastattributen veröffentlichen.
  • Bestandsverwaltungs-Agents können eine Liste der in der VM-Instanz installierten Pakete in Gastattributen veröffentlichen.
  • Software zur Arbeitslastorchestrierung kann den Abschluss eines Vorgangs innerhalb des Gasts an die Steuerungsebene der Software weitergeben, indem sie einen benutzerdefinierten Statuswert in Gastattributen festlegt.

Gastattribute sind kein Ersatz für Ereignisstreaming, Pub/Sub oder andere Formen von Datenspeicherung und Konfigurations-Repositories.

Gastattribute und andere Google Cloud-Dienste

Gastattribute werden von anderen Google Cloud-Diensten so verwendet:

  • SSH-Sicherheit: Wenn Gastattribute aktiviert und OS Login deaktiviert ist, verwenden die Gastumgebung und die gcloud-CLI Gastattribute, um die SSH-Sicherheit zu verbessern. Dazu wird die Google API verwendet, um Hostschlüssel abzurufen, bevor Sie über SSH eine Verbindung zu Ihrer VM herstellen können.
  • VM Manager: Der OS Config-Agent veröffentlicht Betriebssystemdaten in Gastattributen.

Informationen zu den von diesen Diensten gespeicherten Metadateneinträgen finden Sie unter Metadatenschlüssel für vordefinierte Gastattribute.

Gastattribute auf der VM aktivieren

Gastattribute sind standardmäßig deaktiviert. Zum Aktivieren von Gastattributen legen Sie die erforderlichen Metadatenwerte entweder auf den einzelnen VMs oder in den Projektmetadaten fest:

Console

Legen Sie enable-guest-attributes beim Erstellen einer VM in Instanzmetadaten fest:

  1. Rufen Sie in der Google Cloud Console die Seite Instanz erstellen auf.

    Zur Seite „Instanz erstellen“

  2. Geben Sie die VM-Details an

  3. Maximieren Sie den Abschnitt Erweiterte Optionen und tun Sie Folgendes:

    1. Maximieren Sie den Bereich Verwaltung.

    2. Klicken Sie im Abschnitt Metadaten auf Element hinzufügen und fügen Sie folgende Metadateneinträge hinzu:

      • Key: enable-guest-attributes
      • Wert: TRUE

  4. Klicken Sie auf Erstellen, um die VM zu erstellen.

Legen Sie enable-guest-attributes in den projektweiten Metadaten fest, damit es für alle VMs im Projekt gilt:

  1. Rufen Sie in der Google Cloud Console die Seite Metadaten auf.

    Zur Seite "Metadaten"

  2. Klicken Sie auf Bearbeiten.

  3. Fügen Sie einen Metadateneintrag mit dem Schlüssel enable-guest-attributes und dem Wert TRUE hinzu. Alternativ können Sie den Wert auf FALSE setzen, um das Feature zu deaktivieren.

  4. Klicken Sie auf Speichern, um die Änderungen zu übernehmen.

Legen Sie enable-guest-attributes in den Metadaten einer vorhandenen VM fest:

  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 oben auf der Seite mit den Instanzdetails auf Bearbeiten, um die Instanzeinstellungen zu bearbeiten.
  4. Fügen Sie unter Benutzerdefinierte Metadaten einen Metadateneintrag mit dem Schlüssel enable-guest-attributes und dem Wert TRUE hinzu. Alternativ können Sie für den Wert FALSE festlegen, damit dieses Feature nicht für Ihre VM verwendet wird.
  5. Klicken Sie unten auf der Seite mit den Instanzdetails auf Speichern, um die Änderungen für die VM zu übernehmen.

gcloud

Legen Sie enable-guest-attributes beim Erstellen einer VM in den Instanzmetadaten fest:

Verwenden Sie den Befehl gcloud compute instances create im Google Cloud CLI und legen Sie enable-guest-attributes=TRUE fest, um Gastattribute zu aktivieren. Ersetzen Sie VM_NAME durch den Namen Ihrer VM.

gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE

Legen Sie enable-guest-attributes in den projektweiten Metadaten fest, damit es für alle VMs im Projekt gilt:

Verwenden Sie den Befehl project-info add-metadata im Google Cloud CLI und legen Sie enable-guest-attributes=TRUE fest, um Gastattribute zu aktivieren.

gcloud compute project-info add-metadata \
    --metadata=enable-guest-attributes=TRUE

Alternativ können Sie enable-guest-attributes auf FALSE festlegen, um Gastattribute zu deaktivieren.

Legen Sie enable-guest-attributes in den Metadaten einer vorhandenen VM fest:

Verwenden Sie den Befehl instances add-metadata im Google Cloud CLI und legen Sie enable-guest-attributes=TRUE fest, um Gastattribute zu aktivieren. Ersetzen Sie VM_NAME durch den Namen Ihrer VM.

gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-guest-attributes=TRUE

Alternativ können Sie enable-guest-attributes auf FALSE festlegen, damit keine Gastattribute für Ihre VM verwendet werden.

Gastattribute festlegen

Jeder in der VM-Instanz ausgeführte Prozess kann Daten in die Gastattributwerte schreiben. Das gilt auch für Skripts und Anwendungen, die keine Sudo- oder Administratorberechtigungen haben. Nutzer oder Dienstkonten außerhalb der VM können keine Daten in Metadatenwerte von Gastattributen schreiben.

Linux-VMs

Sie können beispielsweise eine curl-Anfrage aus Ihrer VM verwenden, um einen Wert in den Metadatenpfad guest-attributes zu schreiben:

curl -X PUT --data "VALUE" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

Dabei gilt:

  • NAMESPACE: logische Gruppierung für den KEY. Gastattribute müssen einen Namespace haben.
  • VALUE: Wert, den Sie schreiben möchten.
  • KEY: Metadatenpfad in guest-attributes, in dem der Wert gespeichert wird.

Verwenden Sie für die Felder NAMESPACE und KEY nur Buchstaben, Ziffern, Unterstriche (_) und Bindestriche (-).

Windows-VMs

Sie können beispielsweise eine Invoke-RestMethod-Anfrage aus Ihrer VM verwenden, um einen Wert in den Metadatenpfad guest-attributes zu schreiben:

PS C:\> 
$value = (Invoke-RestMethod `
         -Method PUT -Body "VALUE" `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

Dabei gilt:

  • NAMESPACE: logische Gruppierung für den KEY. Gastattribute müssen einen Namespace haben.
  • VALUE: Wert, den Sie schreiben möchten.
  • KEY: Metadatenpfad in guest-attributes, in dem der Wert gespeichert wird.

Verwenden Sie für die Felder NAMESPACE und KEY nur Buchstaben, Ziffern, Unterstriche (_) und Bindestriche (-).

Gastattribute abrufen

Nutzer oder Dienstkonten können Gastattribute von außerhalb einer VM lesen, wenn sie die erforderliche Rolle haben. Darüber hinaus kann jeder Nutzer oder jede Anwendung innerhalb einer VM die Metadatenwerte für diese VM lesen.

Jeder Prozess, der in der virtuellen Maschine ausgeführt wird, kann in den Wert des Gastattributs schreiben. Das gilt auch für Skripts und Anwendungen, die keine Sudo- oder Administratorberechtigungen haben.

Metadatenserver abfragen

Verwenden Sie die folgende Anleitung, um Gastattribute von innerhalb einer VM abzufragen.

  1. Stellen Sie eine Verbindung zur VM her.

  2. Fragen Sie die Gastattribute ab.

    Linux-VMs

    Sie können beispielsweise eine curl-Anfrage aus Ihrer VM verwenden, um einen Wert aus dem Metadatenpfad guest-attributes zu lesen:

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

    Dabei gilt:

    • NAMESPACE: Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten.
    • KEY: Pfad innerhalb von guest-attributes, aus dem der Metadatenwert gelesen werden soll.

    Alternativ können Sie alle Gastattributwerte mit einer einzigen Anfrage zurückgeben: Ersetzen Sie NAMESPACE durch den Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten.

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/ -H "Metadata-Flavor: Google"

    Windows-VMs

    Sie können beispielsweise eine Invoke-RestMethod-Anfrage aus Ihrer VM verwenden, um einen Wert aus dem Metadatenpfad guest-attributes zu lesen:

    PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

    Dabei gilt:

    • NAMESPACE: Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten.
    • KEY: Pfad innerhalb von guest-attributes, aus dem der Metadatenwert gelesen werden soll.

    Alternativ können Sie alle Gastattributwerte mit einer einzigen Anfrage zurückgeben: Ersetzen Sie NAMESPACE durch den Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten.

    PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/")
$value

Google Cloud CLI oder REST verwenden

So rufen Sie Gastattribute von außerhalb einer VM auf:

gcloud

Verwenden Sie das Google Cloud CLI, um Metadatenwerte von Gastattributen für eine VM zu lesen. Sie können beispielsweise sämtliche Werte für die VM abrufen:

gcloud compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

Wenn Sie alle Werte unter einem bestimmten Namespace abrufen möchten, fügen Sie das Flag --query-path und den von Ihnen definierten Namespace hinzu:

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE \
    --zone=ZONE

Wenn Sie einen einzelnen Wert unter einem bestimmten Namespace abrufen möchten, fügen Sie das Flag --query-path, den Namespace und den Schlüssel für den von Ihnen definierten Wert hinzu:

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE/KEY \
    --zone=ZONE

Dabei gilt:

  • VM_NAME: Name der VM, von der Sie den Metadatenwert des Gastattributs lesen möchten
  • NAMESPACE: Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten
  • KEY: Pfad innerhalb von guest-attributes-Metadaten, in dem der Wert gespeichert wird
  • ZONE: die Zone, in der sich die VM befindet

REST

Verwenden Sie die Methode compute.instances.getguestattributes:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Projekt-ID
  • ZONE: Zone, in der sich Ihre VM befindet
  • VM_NAME: Name der VM, von der Sie den Metadatenwert des Gastattributs lesen möchten
  • NAMESPACE: Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten
  • KEY: Pfad innerhalb von guest-attributes-Metadaten, in dem der Wert gespeichert wird

Wenn Sie alle Schlüssel für einen NAMESPACE abrufen möchten, lassen Sie KEY weg:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

Zum Abrufen aller Schlüssel in jedem Namespace auf der VM lassen Sie NAMESPACE und queryPath komplett weg:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes

Wenn Sie ein OAuth-Token haben, können Sie alternativ curl verwenden:

curl -H "Authorization: Bearer OAUTH_TOKEN" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

Dabei gilt:

  • OAUTH_TOKEN: Ihr OAuth-Token
  • PROJECT_ID: Ihre Projekt-ID
  • ZONE: Zone, in der sich Ihre VM befindet
  • VM_NAME: Name der VM, von der Sie den Metadatenwert des Gastattributs lesen möchten
  • NAMESPACE: Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten
  • KEY: Pfad innerhalb von guest-attributes-Metadaten, in dem der Wert gespeichert wird

Gastattribute löschen

Verwenden Sie die folgende Anleitung, um Gastattribute von innerhalb einer VM zu entfernen.

  1. Stellen Sie eine Verbindung zur VM her.

  2. Löschen Sie die Gastattribute.

    Linux-VMs

    Sie können Gastattribute auch löschen. Verwenden Sie beispielsweise curl, um einen bestimmten Schlüssel zu löschen:

    curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

    Dabei gilt:

    • NAMESPACE: Namespace für den Schlüssel guest-attributes, den Sie löschen möchten
    • KEY: Pfad innerhalb von guest-attributes, in dem der Wert gespeichert wird

    Windows-VMs

    Sie können Gastattribute auch löschen. Verwenden Sie beispielsweise Invoke-RestMethod, um einen bestimmten Schlüssel zu löschen:

    PS C:\> 
$value = (Invoke-RestMethod `
          -Method DELETE `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

    Dabei gilt:

    • NAMESPACE: Namespace für den Schlüssel guest-attributes, den Sie löschen möchten
    • KEY: Pfad innerhalb von guest-attributes, in dem der Wert gespeichert wird

Gastattribute für Ihre Organisation oder Ihren Ordner deaktivieren

Wenn Sie nicht möchten, dass eine der VMs in Ihrer Organisation oder Ihrem Ordner Gastattribute aktiviert, können Sie das Feature vollständig überschreiben und deaktivieren.

Legen Sie die Einschränkung constraints/compute.disableGuestAttributesAccess für Ihre Organisation oder Ihren Ordner fest und ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts:

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess \
    --project=PROJECT_ID

Weitere Informationen zum Festlegen und Verwalten von Einschränkungen für Ihre Organisationen finden Sie unter Einschränkungen verwenden.

Nächste Schritte