Metadaten einer Instanz speichern und abrufen

Jede Instanz speichert ihre Metadaten auf einem Metadatenserver. Sie können diesen Metadatenserver aus der Instanz und von der Compute Engine-API programmatisch abfragen. Sie können Informationen über die Instanz abfragen, z. B. den Hostnamen der Instanz, die Instanz-ID, Skripts beim Starten und Beenden, benutzerdefinierte Metadaten und Dienstkontodaten. Ihre Instanz hat automatisch ohne zusätzliche Autorisierung Zugriff auf die Metadatenserver-API.

Der Metadatenserver ist besonders in Kombination mit Startskripts und Shutdown-Skripts von Vorteil, da Sie mit ihm programmgesteuert und ohne zusätzliche Autorisierung eindeutige Informationen über eine Instanz erhalten. So können Sie zum Beispiel ein Startskript schreiben, das das Metadaten-Schlüssel/Wert-Paar für die externe Instanz-IP holt und diese in Ihrem Skript einsetzt, um eine Datenbank zu erstellen. Da die Standard-Metadatenschlüssel für jede Instanz identisch sind, können Sie Ihr Skript immer wieder neu verwenden, ohne es für jede Instanz aktualisieren zu müssen. So müssen Sie weniger problemanfälligen Code für Ihre Anwendungen erstellen.

Metadaten werden im Format key:value gespeichert. Es existiert ein Standardsatz mit Metadateneinträgen, auf den jede Instanz zugreifen kann. Alternativ können Sie auch benutzerdefinierte Metadaten einrichten.

Sie können die Metadaten-URL abfragen, um auf den Metadatenserver zuzugreifen.

Aktuelle Version: v1

Es kann sein, dass Compute Engine mehr als eine Version von Metadaten anbietet, aber wir empfehlen, dass Sie immer nur die neueste Serverversion verwenden. Compute Engine kann dem Metadatenserver jederzeit neue Einträge sowie neue Felder zu Antworten hinzufügen. Sehen Sie regelmäßig nach, ob es Veränderungen gegeben hat.

Informationen zum Überprüfen der Version Ihres Metadatenserver-Endpunkts finden Sie unter Version Ihres Serverendpunkts prüfen.

v1beta1-Server- und v0.1-Metadatenserver-Endpunkte wurden verworfen und sollen eingestellt werden. Sorgen Sie dafür, dass alle Anfragen für die Verwendung der v1 aktualisiert werden. Weitere Informationen finden Sie unter Auf Metadaten-Server-Endpunkt v1 umstellen.

Vorbereitung

Erforderliche Berechtigungen für diese Aufgabe

Zum Ausführen dieser Aufgabe benötigen Sie die folgenden Berechtigungen.

  • compute.instances.setMetadata für die Instanz, wenn Instanzmetadaten festgelegt werden
  • compute.projects.setCommonInstanceMetadata für das Projekt, wenn projektweite Metadaten festgelegt werden
  • compute.projects.get für das Projekt, wenn nur Metadaten abgerufen werden
  • compute.instances.get für die Instanz, wenn nur Metadaten abgerufen werden

Metadaten für Projekte und Instanzen

Metadaten können sowohl Projekten als auch Instanzen zugewiesen werden. Bei einem Projekt werden die Metadaten allen VM-Instanzen innerhalb des Projekts zur Verfügung gestellt, während Instanzmetadaten nur diese Instanz betreffen.

Standard-Metadatenschlüssel

Compute Engine definiert einen Satz mit Standard-Metadateneinträgen, die Informationen über Ihre Instanz oder Ihr Projekt enthalten. Die Standard-Metadaten werden immer vom Server definiert und festgelegt. Sie können keines dieser Metadatenpaare manuell bearbeiten.

Die folgenden Metadaten sind standardmäßig für ein Projekt verfügbar. Einige Metadateneinträge sind Verzeichnisse, die andere Metadatenschlüssel enthalten. Der Unterschied wird durch einen Schrägstrich im Namen der Metadaten angezeigt. Beispiel: attributes/ ist ein Verzeichnis, das andere Schlüssel enthält, während numeric-project-id ein Metadatenschlüssel ist, der einem Wert zugeordnet wird.

Relativ zu http://metadata.google.internal/computeMetadata/v1/project/
Metadateneintrag Beschreibung
attributes/ Ein Verzeichnis mit benutzerdefinierten Metadatenwerten, die für dieses Projekt festgelegt wurden.
attributes/disable-legacy-endpoints Deaktiviert Legacy-Metadatenserver-Endpunkte für alle Instanzen in Ihrem Projekt. Legen Sie immer disable-legacy-endpoints=TRUE fest, es sei denn, Ihr Projekt verwendet Legacy-Endpunkte. Aktualisieren Sie Ihre Anwendungen so, dass sie die v1-Endpunkte verwenden.
attributes/enable-oslogin Aktiviert das Feature OS Login zur SSH-Schlüsselverwaltung für Ihr Projekt, wenn Sie enable-oslogin=TRUE festlegen.
attributes/vmdnssetting Konfiguriert, wie interne DNS-Namen für die Instanzen in Ihrem Projekt formatiert werden. Weitere Informationen zu internen DNS-Namen finden Sie unter DNS-Namen für Projekte konfigurieren.
attributes/ssh-keys Wenn das Projekt und die Instanz nicht für die Verwendung von OS Login zur SSH-Schlüsselverwaltung konfiguriert sind, können Sie mit diesem Attribut öffentliche SSH-Schlüssel konfigurieren, die eine Verbindung zu Instanzen dieses Projekts ermöglichen. Sollte es mehrere SSH-Schlüssel geben, wird jeder Schlüssel durch ein Zeilenvorschubzeichen abgetrennt (\n). Dieser Wert ist ein String. SSH-Schlüssel, die von OS Login verwaltet werden, sind in diesem Metadatenwert nicht sichtbar.

Beispiel: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

numeric-project-id Die numerische Projekt-ID (Projektnummer) der Instanz. Diese unterscheidet sich vom Projektnamen, der in der Google Cloud Console angezeigt wird. Dieser Wert unterscheidet sich vom project-id-Wert des Metadateneintrags.
project-id Die Projekt-ID.

Die folgenden Metadaten sind standardmäßig für eine Instanz verfügbar:

Relativ zu http://metadata.google.internal/computeMetadata/v1/instance/
Metadateneintrag Beschreibung
attributes/ Ein Verzeichnis mit benutzerdefinierten Metadatenwerten, die die Instanz beim Starten oder beim Beenden erhält. Weitere Informationen finden Sie unten stehend unter Konfiguration von benutzerdefinierten Metadaten.
attributes/enable-oslogin Aktiviert das Feature OS Login zur SSH-Schlüsselverwaltung für diese Instanz, wenn Sie enable-oslogin=TRUE festlegen.
attributes/vmdnssetting Konfiguriert, wie interne DNS-Namen für diese Instanz formatiert werden. Weitere Informationen zu internen DNS-Namen finden Sie unter DNS-Namen für Projekte konfigurieren.
attributes/ssh-keys Wenn Ihre Instanz nicht für die Verwendung von OS Login zur SSH-Schlüsselverwaltung konfiguriert ist, können Sie mit diesem Attribut öffentliche SSH-Schlüssel konfigurieren, die eine Verbindung zu dieser Instanz ermöglichen. Sollte es mehrere SSH-Schlüssel geben, wird jeder Schlüssel durch ein Zeilenvorschubzeichen abgetrennt (\n). Dieser Wert ist ein String. SSH-Schlüssel, die von OS Login verwaltet werden, sind in diesem Metadatenwert nicht sichtbar.

Beispiel: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

cpu-platform CPU-Plattform der Instanz.
description Die Textbeschreibung einer Instanz, die über das --description-Flag zugewiesen oder in der API eingerichtet wird.
disks/ Ein Verzeichnis von Laufwerken, die mit dieser Instanz verbunden sind.
guest-attributes/ Benutzerdefinierte Metadatenwerte für die Instanz, mit denen Sie unregelmäßige Statusbenachrichtigungen, kleinere Datenmengen oder selten verwendete Daten veröffentlichen können. Diese Werte sind nützlich, um das Ende von Startskripts anzuzeigen oder sonstige unregelmäßige Statusbenachrichtigungen an andere Anwendungen zu übergeben. Jeder Nutzer oder Prozess auf der VM-Instanz kann Werte aus den Namespaces und Schlüsseln in den "guest-attributes"-Metadaten lesen und in diese schreiben.
hostname Der Hostname der Instanz.
id Die ID der Instanz. Hierbei handelt es sich um eine eindeutige numerische ID, die von Compute Engine erstellt wird. Dies ist nützlich, um Instanzen zu identifizieren, wenn Sie keine Instanznamen verwenden möchten.
machine-type Der Metadatenwert für den Maschinentyp dieser Instanz, der folgendes Format hat: projects/[NUMERIC_PROJECT_ID]/machineTypes/[MACHINE_TYPE]
name Der Name der Instanz.
network-interfaces/ Ein Verzeichnis mit Netzwerkschnittstellen für die Instanz.
network-interfaces/<index>/forwarded-ips/ Ein Verzeichnis aller externen IP-Adressen, die aktuell für die Netzwerkschnittstelle unter <index> auf diese VM-Instanz verweisen. Bietet eine Liste mit externen IPs, die über Weiterleitungsregeln Pakete an diese Instanz weiterleiten.
scheduling/ Ein Verzeichnis mit den Zeitplanoptionen für diese Instanz.
scheduling/on-host-maintenance Einstellung für das Verhalten des transparenten Wartungsereignisses dieser Instanz. Dieser Wert ist mit dem Flag --on_host_maintenance oder mithilfe der API festgelegt.
scheduling/automatic-restart Die Einstellung für den automatischen Neustart der Instanz. Dieser Wert ist mit dem Flag ‑‑automatic_restart oder mithilfe der API festgelegt.
scheduling/preemptible Die präemptive Einstellung der Instanz. Die Instanz ist präemptiv, wenn dieser Wert TRUE ist. Dieser Wert wird beim Erstellen einer Instanz festgelegt und kann nicht geändert werden.
maintenance-event Der Pfad, der darauf hinweist, dass ein transparentes Wartungsereignis diese Instanz beeinträchtigt. Weitere Informationen finden Sie unter Transparenter Wartungshinweis.
service-accounts/ Ein Verzeichnis mit Dienstkonten für diese Instanz.
service-accounts/<service-account-name>/identity Ein JSON-Webtoken, das für die Instanz eindeutig ist. Für diesen Instanzmetadatenwert müssen Sie den Parameter "audience" in Ihrer Anfrage angeben. Beispiel: "?audience=http://www.example.com". Unter Identität von Instanzen prüfen erfahren Sie, wie Sie Instanz-Identitätstoken anfordern und ansehen können.
tags Alle Tags für diese Instanz.
zone Der Metadatenwert für die Zone, in der diese Instanz ausgeführt wird. Dieser Wert hat folgendes Format: projects/[NUMERIC_PROJECT_ID]/zones/zone

Metadaten aufrufen

Sie können den Metadatenserver abfragen, indem Sie aus der VM-Instanz eine Anfrage an die folgenden Stamm-URLs richten. Verwenden Sie die URL http://metadata.google.internal/computeMetadata/v1/, um Anfragen an den Metadatenserver zu stellen.

Alle Metadatenwerte werden als Subpfade unterhalb dieser Stamm-URLs definiert.

Standard-Metadatenwerte können nur aus der zugehörigen Instanz selbst abgefragt werden. Sie können weder aus anderen Instanzen noch von Ihrem lokalen Computer aus abgefragt werden. Sie können Standardtools wie curl oder wget von der Instanz auf ihren Metadatenserver anwenden.

Bei einer Metadatenabfrage muss der folgende Header Bestandteil aller Anfragen sein:

Metadata-Flavor: Google

Dieser Header weist darauf hin, dass eine Anfrage zum Aufruf von Metadatenwerten gesendet wurde und diese nicht unbeabsichtigt aus einer unsicheren Quelle kommen. Auf diese Weise kann der Metadatenserver Ihnen die entsprechenden Daten zurückgeben. Ohne diesen Header lehnt der Metadatenserver Ihre Anfrage ab.

X-Forwarded-For-Header

Anfragen mit dem Header X-Forwarded-For werden automatisch vom Metadatenserver abgewiesen. Dieser Header zeigt normalerweise an, dass die Anfrage weitergeleitet wurde und eventuell nicht von einem autorisierten Nutzer stammt. Aus Sicherheitsgründen werden Anfragen dieser Art abgelehnt.

Beschränkungen

Wenn Sie den Befehl curl verwenden, um Metadaten vom Server abzurufen, beachten Sie, dass einige codierte Zeichen im Anfragepfad nicht unterstützt werden. Codierte Zeichen werden nur im Abfragepfad unterstützt.

Die folgende Anforderung funktioniert beispielsweise eventuell nicht:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

Damit diese Anfrage funktioniert, ersetzen Sie das nicht unterstützte codierte Zeichen im Anfragepfad (%40) durch den entsprechenden zulässigen Wert (@).

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

In der folgenden Tabelle sind die codierten Zeichen aufgeführt, die in Anfragepfaden nicht unterstützt werden.

Codiertes Zeichen Zulässiger Wert
%21

!
%24

$
%27

'
%28

(
%29

)
%2A

*
%2C

,
%40

@

Sind Metadaten-Informationen sicher?

Wenn Sie eine Anfrage zum Abrufen von Informationen vom Metadatenserver senden, verlassen Ihre Anfragen und die nachfolgende Metadatenantwort niemals den physischen Host, auf dem die VM-Instanz ausgeführt wird.

Verzeichniseinträge abfragen

Der Metadatenserver setzt Verzeichnisse ein, um bestimmte Metadatenschlüssel zu organisieren. Alle Metadateneinträge, die mit einem Schrägstrich enden, sind Verzeichnisse. So ist zum Beispiel disks/ ein Verzeichnis von Laufwerken, die an diese Instanz angehängt sind:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
    
    0/
    1/
    2/
    

Wenn Sie mehr Informationen zum Laufwerksverzeichnis 0/ wünschen, können Sie auf ähnliche Weise die jeweilige URL für dieses Verzeichnis abfragen:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/" -H "Metadata-Flavor: Google"
    
    device-name
    index
    mode
    type
    

Endpunkte abfragen

Wenn ein Metadatenschlüssel kein Verzeichnis ist, ist er ein Endpunkt, der einen oder mehrere Werte zurückgibt. So können Sie zum Beispiel den folgenden Endpunkt abfragen, wenn Sie den Modus eines bestimmten Laufwerks sehen möchten:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/mode" -H "Metadata-Flavor: Google"
    
    READ_WRITE
    

Standardmäßig besitzt jeder Endpunkt ein vordefiniertes Format für die Antwort. Einige Endpunkte können JSON-Daten zurückgeben, während andere die Daten als String darstellen. Sie können das Standardformat für Daten mit den Abfrageparametern alt=json oder alt=text ändern, die Daten als JSON-String oder als reinen Text wiedergeben.

Der Schlüssel tags gibt beispielsweise Daten automatisch im JSON-Format wieder. Sie können stattdessen Daten im Textformat zurückgeben, indem Sie den Abfrageparameter alt=text angeben:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
    
    ["bread","butter","cheese","cream","lettuce"]
    
    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"
    
    bread
    butter
    cheese
    cream
    lettuce
    

Metadaten rekursiv abfragen

Wenn Sie alle Inhalte in einem Verzeichnis zurückgeben möchten, verwenden Sie den Abfrageparameter recursive=true mit Ihrer Anfrage:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"
    
    [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
    {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
    {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
    

Standardmäßig werden rekursive Inhalte im JSON-Format angezeigt. Wenn Sie diese Inhalte im Textformat zurückgeben möchten, hängen Sie den Abfrageparameter alt=text an:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"
    
    0/device-name boot
    0/index 0
    0/mode READ_WRITE
    0/type PERSISTENT
    1/device-name persistent-disk-1
    1/index 1
    1/mode READ_WRITE
    1/type PERSISTENT
    2/device-name persistent-disk-1
    2/index 2
    2/mode READ_ONLY
    2/type PERSISTENT
    

Boolesche Werte festlegen

Für Felder, die die booleschen Werte TRUE oder FALSE annehmen, können die folgenden Werte verwendet werden:

Status Alternative Werte
TRUE Y, Yes, 1
FALSE N, No, 0

Bei booleschen Werten wird nicht zwischen Groß- und Kleinschreibung unterschieden. Sie können z. B. False , false oder FALSE verwenden, um ein Feature zu deaktivieren.

Benutzerdefinierte Metadaten einrichten

Sie können benutzerdefinierte Metadaten für eine Instanz oder ein Projekt über die Google Cloud Console, das Befehlszeilentool gcloud oder die Compute Engine API festlegen. Benutzerdefinierte Metadaten eignen sich zur Übergabe beliebiger Werte an Ihr Projekt oder Ihre Instanz und zum Festlegen von Startup- und Shutdown-Skripts.

Größeneinschränkungen bei benutzerdefinierten Metadaten

Compute Engine erzwingt die folgenden Einschränkungen für die Länge Ihrer benutzerdefinierten Metadatenwerte:

  • 256 KB für jeden einzelnen Metadateneintrag
  • 512 KB Gesamtgröße für alle Metadateneinträge pro Instanz

Vor allem SSH-Schlüssel werden als benutzerdefinierte Metadaten im Schlüssel ssh-keys gespeichert. Wenn Ihr Metadateninhalt für diesen Schlüssel die Grenze von 256 KB überschreitet, können Sie keine weiteren SSH-Schlüssel hinzufügen. Sollten Sie Probleme mit dieser Einschränkung haben, können Sie unbenutzte Schlüssel entfernen, um Platz für neue zu schaffen.

Wenn Sie für Startskripts oder Shutdown-Skripts Inhalte direkt angeben, kann es sein, dass diese ebenfalls als benutzerdefinierte Metadaten gespeichert und auf diese Größeneinschränkung angerechnet werden. Dies können Sie vermeiden, wenn Sie Ihre Startskripts oder Shutdown-Skripts als Datei speichern, die an einem externen Speicherort wie Cloud Storage gehostet wird, und beim Erstellen einer Instanz dann die Startskript-URL angeben. Diese Dateien werden auf die VM-Instanz heruntergeladen und nicht auf dem Metadatenserver gespeichert.

Metadaten der Instanz festlegen

Legen Sie benutzerdefinierte Metadaten für eine Instanz in der Cloud Console, dem gcloud-Tool oder der API fest. Instanzmetadaten beziehen sich nur auf eine bestimmte Instanz.

Metadaten beim Erstellen einer Instanz festlegen

Console

console true

gcloud

Verwenden Sie das Flag --metadata, um mit dem gcloud-Befehlszeilentool benutzerdefinierte Metadaten festzulegen.

gcloud compute instances create example-instance \
        --metadata foo=bar

API

Geben Sie die benutzerdefinierten Metadaten als Teil des Metadatenattributs für Ihre Anfrage ein:

    POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

    {
      "...
            }
          ]
        }
      ],
      "metadata": {
        "items": [
          {
           "key": "foo",
           "value": "bar"
          }
        ]
      },
      ..
    }
    

Metadaten auf einer laufenden Instanz aktualisieren

Console

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

    Zur Seite "VM-Instanzen"

  2. Klicken Sie auf die Instanz, deren Metadaten Sie aktualisieren möchten.
  3. Klicken Sie oben auf der Seite auf Bearbeiten.
  4. Klicken Sie unter Benutzerdefinierte Metadaten auf Element hinzufügen oder bearbeiten Sie vorhandene Metadaten.
  5. Speichern Sie die Änderungen.

gcloud

Wenn Sie Instanzmetadaten mit dem gcloud-Tool ändern, fügen Sie neue Daten hinzu. Geben Sie nur die Metadatenschlüssel an, die Sie hinzufügen oder ändern möchten. Wenn ein Schlüssel bereits existiert, wird der Wert des Schlüssels mit dem neuen Wert aktualisiert.

Führen Sie mit dem gcloud-Befehlszeilentool den Befehl instances add-metadata aus:

gcloud compute instances add-metadata instance-name \
          --metadata bread=mayo,cheese=cheddar,lettuce=romaine
    

Wenn Sie den Eintrag lettuce=romaine in lettuce=green ändern möchten, verwenden Sie Folgendes:

gcloud compute instances add-metadata instance-name \
        --metadata lettuce=green
    

Wenn Sie den Eintrag lettuce=romaine entfernen möchten, geben Sie den vorhandenen Schlüssel an und schließen Sie den Wert aus.

gcloud compute instances remove-metadata instance-name \
        --keys lettuce
    

API

Führen Sie in der API eine Anfrage an die Methode instances().setMetadata aus. Geben Sie eine Liste der neuen Metadatenwerte und des aktuellen Werts fingerprint an.

Ein Fingerabdruck ist eine Reihe zufälliger Zeichen, die von Compute Engine erstellt wird und für ein optimistisches Sperrverfahren genutzt wird. Geben Sie den entsprechenden Fingerabdruckwert an, um Ihre Anfrage durchzuführen. Dieser Fingerabdruck ändert sich nach jeder Anfrage. Geben Sie einen falschen an, wird Ihre Anfrage abgelehnt. So kann nur eine Aktualisierung auf einmal stattfinden und Probleme werden vermieden.

Um den aktuellen Fingerabdruck einer Instanz zu erhalten und vorhandene Schlüssel/Wert-Paare für die Instanz anzuzeigen, senden Sie eine instances().get-Anfrage.

    GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

    {
     ...
     "name": "example-instance",
     "metadata": {
      "kind": "compute#metadata",
      "fingerprint": "zhma6O1w2l8="
      "items": [
       {
        "key": "foo",
        "value": "bar"
       }
      ]
     },
     ...
    }
    

Senden Sie nun eine Anfrage an die Methode instances().setMetadata und legen Sie die Schlüssel/Wert-Paare Ihrer benutzerdefinierten Metadaten fest. Wenn die Instanz bereits Schlüssel/Wert-Paare hat, die Sie behalten möchten, müssen Sie sie der Anfrage mit den neuen Paaren hinzufügen:

    POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

    {
     "fingerprint": "zhma6O1w2l8=",
     "items": [
      {
       "key": "foo",
       "value": "bar"
      },
      {
       "key": "baz",
       "value": "bat"
      }
     ]
    }
    

Sie können alle Metadaten-Schlüssel/Wert-Paare aus einer Instanz entfernen, indem Sie eine instances().setMetadata-Anfrage stellen und das items-Attribut ausschließen. Bitte achten Sie darauf, dass Sie trotzdem das aktuelle Metadaten-Fingerabdruckattribut für die Anfrage hinzufügen müssen:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

{ "fingerprint": "5rC_DXxBUZw=" }

Benutzerdefinierte Metadaten für das gesamte Projekt einrichten

Sie können Metadaten einrichten, die sich auf alle Instanzen im Projekt beziehen. Wenn Sie beispielsweise ein projektweites Metadatenpaar für baz=bat definieren, dann wird es automatisch auf alle Instanzen im Projekt angewendet.

Console

  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 Eintrag hinzu oder bearbeiten Sie ihn.
  4. Speichern Sie die Änderungen.

gcloud

Führen Sie mit dem gcloud-Befehlszeilentool den Befehl project-info add-metadata aus: Beispiel:

gcloud compute project-info add-metadata \
        --metadata foo=bar,baz=bat
    

Weitere Informationen finden Sie in den Metadaten, indem Sie den Befehl describe ausführen:

gcloud compute project-info describe

Beispielsweise können Sie eine ähnliche Antwort wie die folgende erhalten:

    ...
    commonInstanceMetadata:
      fingerprint: RfOFY_-eS64=
      items:

  • key: baz value: bat
  • key: foo value: bar
  • key: ssh-keys ...
Ein Metadaten-Schlüssel/Wert-Paar wird mit einem Gleichheitszeichen angegeben, wie zum Beispiel key=value. Mehrere Schlüssel/Wert-Paare werden mit Leerzeichen voneinander getrennt.

Sie können mit dem Flag --metadata-from-file optional eine oder mehrere Dateien angeben, aus denen Metadaten gelesen werden sollen. Mit dem Befehl project-info remove-metadata können Sie Metadatenwerte entfernen.

API

Stellen Sie in der API eine Anfrage an die projects().setCommonInstanceMetadata-Methode, wobei alle neuen Metadatenwerte und ein fingerprint-Wert bereitgestellt werden.

Ein Fingerabdruck ist eine Reihe zufälliger Zeichen, die von Compute Engine erstellt und für ein optimistisches Sperrverfahren genutzt werden. Geben Sie den entsprechenden Fingerabdruckwert an, um Ihre Anfrage durchzuführen. Dieser Fingerabdruck ändert sich nach jeder Anfrage. Geben Sie einen falschen an, wird Ihre Anfrage abgelehnt. So kann nur eine Aktualisierung auf einmal stattfinden und Probleme werden vermieden.

Sie rufen den aktuellen Fingerabdruck einer Instanz ab, wenn Sie eine project().get-Anfrage ausführen und den Fingerabdruckwert kopieren:

    GET https://compute.googleapis.com/compute/v1/projects/myproject

    {
     "name": "myproject",
     "commonInstanceMetadata": {
      "kind": "compute#metadata",
      "fingerprint": "FikclA7UBC0=",
      ...
    }
    

Senden Sie nun eine Anfrage an die Methode projects().setCommonInstanceMetadata und legen Sie die Schlüssel/Wert-Paare Ihrer benutzerdefinierten Metadaten fest:

    POST https://compute.googleapis.com/compute/v1/projects/myproject/setCommonInstanceMetadata

    {
     "fingerprint": "FikclA7UBC0=",
     "items": [
      {
       "key": "foo",
       "value": "bar"
      }
     ]
    }
    

Benutzerdefinierte Metadaten abfragen

Fragen Sie benutzerdefinierte Instanz- oder Projektmetadaten über die Cloud Console, das Befehlszeilentool gcloud oder die API ab.

Console

Benutzerdefinierte Metadaten für das gesamte Projekt finden Sie auf der Seite Metadaten.

Aufrufen der benutzerdefinierten Metadaten für die Instanz:

  1. Rufen Sie die Seite VM-Instanzen auf.
  2. Klicken Sie auf die Instanz, für die Sie Metadaten aufrufen möchten.
  3. Rufen Sie die Daten unter Benutzerdefinierte Metadaten auf.

gcloud

Projektmetadaten abfragen:

gcloud compute project-info describe \
        --flatten="commonInstanceMetadata[]"
    

Instanzmetadaten abfragen:

gcloud compute instances describe example-instance \
        --flatten="metadata[]"
    

Mit dem Flag --flatten können Sie die Ausgabe auf einen relevanten Metadatenschlüssel beschränken. Die folgende Instanz hat beispielsweise ein benutzerdefiniertes Metadaten-Schlüssel/Wert-Paar foo:bar.

    $ gcloud compute instances describe example-instance
    
    ...
    metadata:
      fingerprint: Cad2L9eKNR0=
      items:
      - key: foo
        value: bar
      kind: compute#metadata
    ...
    
    

Führen Sie Folgendes aus, um den Schlüsselwert foo abzufragen:

    gcloud compute instances describe example-instance \
        --flatten="metadata[foo]"
    
    ---
      bar
    
    

API

Führen Sie zum Abfragen der Metadaten eines Projekts eine leere Anfrage für die projects().get-Methode aus:

GET https://compute.googleapis.com/compute/v1/projects/myproject

Führen Sie zum Abfragen der Metadaten einer Instanz eine leere Anfrage für die instance().get-Methode aus:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

Gastattribute festlegen und abfragen

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

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 Anwendungsfälle, bei denen Daten unregelmäßig und in geringer Menge veröffentlicht werden müssen. Beispiele:

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

Für Lese- und Schreibvorgänge innerhalb einer Instanz bietet der Metadatenserver automatische Authentifizierung und Autorisierung auf Instanzebene. Jede Instanz kann nur auf ihrem eigenen Metadatenserver Daten lesen oder schreiben. Instanzen können nicht auf den Metadatenserver einer anderen Instanz zugreifen. Nutzer und Dienstkonten können die Gastattribute einer Instanz nur von außerhalb der Instanz lesen, wenn sie eine Cloud Identity and Access Management-Rolle mit der Berechtigung compute.instances.getGuestAttributes haben.

Gastattribute auf der Instanz aktivieren

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

Console

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

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

    Zur Seite "VM-Instanzen"

  2. Klicken Sie auf Instanz erstellen.
  3. Tragen Sie auf der Seite Eine neue Instanz erstellen die gewünschten Eigenschaften für Ihre Instanz ein.
  4. Fügen Sie im Bereich Metadaten einen Metadateneintrag hinzu, in dem sich der Schlüssel enable-guest-attributes befindet und der Wert TRUE ist.
  5. Klicken Sie auf Erstellen, um die Instanz zu erstellen.

Legen Sie enable-guest-attributes in den projektweiten Metadaten fest, sodass er für alle Instanzen im Projekt gültig ist:

  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 Instanz 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 Instanz, für die Sie den Metadatenwert festlegen möchten.
  3. Klicken Sie oben auf der Seite "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 den Wert auf FALSE setzen, um die Instanz von dem Feature auszuschließen.
  5. Klicken Sie unten auf der Seite "Instanzdetails" auf Speichern, um die Änderungen für die Instanz zu übernehmen.

gcloud

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

Verwenden Sie den Befehl gcloud compute instances create im Befehlszeilentool gcloud und legen Sie enable-guest-attributes=TRUE fest, um Gastattribute zu aktivieren. Ersetzen Sie dabei instance-name durch den Namen Ihrer Instanz.

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

Legen Sie enable-guest-attributes in den projektweiten Metadaten fest, sodass er für alle Instanzen im Projekt gültig ist:

Verwenden Sie den Befehl project-info add-metadata im Befehlszeilentool gcloud 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 Instanz fest:

Verwenden Sie den Befehl instances add-metadata im Befehlszeilentool gcloud und legen Sie enable-guest-attributes=TRUE fest, um Gastattribute zu aktivieren. Ersetzen Sie dabei instance-name durch den Namen Ihrer Instanz.

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

Alternativ können Sie enable-guest-attributes auf FALSE setzen, damit keine Gastattribute für Ihre Instanz 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 Instanz können keine Daten in Metadatenwerte von Gastattributen schreiben.

Sie können beispielsweise eine curl-Anfrage aus Ihrer Instanz 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"

Ersetzen Sie Folgendes:

  • namespace: Eine logische Gruppierung für key. Gastattribute müssen einen Namespace haben.
  • value: Der Wert, den Sie schreiben möchten.
  • key: Der 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 lesen, wenn sie eine Cloud IAM-Rolle mit der Berechtigung compute.instances.getGuestAttributes haben. Darüber hinaus kann jeder Nutzer oder jede Anwendung innerhalb einer Instanz die Metadatenwerte für diese Instanz 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. Sie können beispielsweise eine curl-Anfrage aus Ihrer Instanz 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"

Ersetzen Sie Folgendes:

  • namespace: Der Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten.
  • key: Der Pfad innerhalb von guest-attributes, von 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"

gcloud

Verwenden Sie das Befehlszeilentool gcloud, um Metadatenwerte von Gastattributen aus einer Instanz zu lesen. Sie können beispielsweise sämtliche Werte für die Instanz abrufen:

    gcloud compute instances get-guest-attributes instance-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 instance-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 instance-name \
        --query-path=namespace/key \
        --zone zone

Ersetzen Sie Folgendes:

  • instance-name: Der Name der Instanz, aus der der Metadatenwert des Gastattributs gelesen werden soll.
  • namespace: Der Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten.
  • key: Der Pfad innerhalb von guest-attributes-Metadaten, in dem der Wert gespeichert wird.
  • zone: Die Zone, in der sich die Instanz befindet.

API

Verwenden Sie die API-Methode compute.instances.getguestattributes:

    GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes?queryPath=namespace/key
    

Ersetzen Sie Folgendes:

  • project-id: Ihre Projekt-ID.
  • zone: Die Zone, in der sich Ihre Instanz befindet.
  • instance-name: Der Name der Instanz, aus der der Metadatenwert des Gastattributs gelesen werden soll.
  • namespace: Der Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten.
  • key: Der 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/instance-name/getGuestAttributes?queryPath=namespace

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

GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-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/instance-name/getGuestAttributes?queryPath=namespace/key

Ersetzen Sie Folgendes:

  • oauth-token: Ihr OAuth-Token.
  • project-id: Ihre Projekt-ID.
  • zone: Die Zone, in der sich Ihre Instanz befindet.
  • instance-name: Der Name der Instanz, aus der der Metadatenwert des Gastattributs gelesen werden soll.
  • namespace: Der Namespace für den Schlüssel guest-attributes, den Sie abfragen möchten.
  • key: Der Pfad innerhalb von guest-attributes-Metadaten, in dem der Wert gespeichert wird.

Gastattribute löschen

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"

Ersetzen Sie Folgendes:

  • namespace: Der Namespace für den Schlüssel guest-attributes, den Sie löschen möchten.
  • key: Der 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 Instanzen 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.

Auf Aktualisierungen warten

Da sich Metadatenwerte ändern können, während Ihre Instanz ausgeführt wird, kann der Metadatenserver mithilfe des Features "wait-for-change" über Änderungen an Metadaten informiert werden. Mit diesem Feature können Sie ausstehende HTTP GET-Anfragen durchführen, die nur antworten, wenn die angegebenen Metadaten geändert wurden. Sie können dieses Feature für benutzerdefinierte oder serverdefinierte Metadaten verwenden. Sobald sich also etwas an Ihrer Instanz oder Ihrem Projekt ändert, oder jemand benutzerdefinierte Metadaten aktualisiert, können Sie programmatisch auf die Änderung reagieren. Sie können beispielsweise eine Anfrage für den Schlüssel tags ausführen, sodass die Anfrage nur zurückgegeben wird, wenn sich der Inhalt der Metadaten der Tags geändert hat. Wird die Anfrage zurückgegeben, beinhaltet sie den neuen Wert des Metadatenschlüssels.

Wenn Sie eine wait-for-change-Anfrage ausführen möchten, fragen Sie einen Metadatenschlüssel ab und hängen den Abfrageparameter ?wait_for_change=true an:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"
    

Wenn der angegebene Metadatenschlüssel verändert wurde, gibt die Anfrage den neuen Wert zurück. In diesem Beispiel wurde eine Anfrage an die Methode setInstanceTags gerichtet und diese wurde mit den neuen Werten zurückgegeben:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"
    
    cheese
    lettuce
    

Sie können auch eine wait-for-change-Anfrage rekursiv für die Inhalte eines Verzeichnisses durchführen:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"
    

Der Metadatenserver gibt die neuen Inhalte an, sollte es Veränderungen gegeben haben:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"
    
    {"cheese":"lettuce","cookies":"cream"}
    

Durch das Feature "wait-for-change" können Sie Ihre Anfragen auf Übereinstimmungen prüfen und Zeitlimits festlegen.

ETags verwenden

Wenn Sie eine wait-for-change-Anfrage abschicken, dann antwortet der Metadatenserver, wenn sich die Inhalte der Metadaten geändert haben. Jedoch gibt es immer einen Wettlauf zwischen der Aktualisierung von Metadaten und einer wait-for-change-Anfrage. Deswegen lohnt es sich, eine verlässliche Methode zu haben, um herauszufinden, dass Sie den neusten Metadatenwert erhalten.

Dafür haben wir Ihnen den last_etag-Anfrageparameter zur Verfügung gestellt, der Ihren ETag-Wert mit dem vergleicht, der auf dem Metadatenserver gespeichert ist. Stimmen die ETag-Werte überein, wird die wait-for-change-Anfrage angenommen. Stimmen die ETag-Werte nicht überein, dann bedeutet das, dass sich seit dem letzten Aufruf des ETag-Werts etwas verändert hat. Der Metadatenserver sendet diesen neuen Wert sofort zurück.

Sie erhalten den aktuellen ETag-Wert für einen Metadatenschlüssel, indem Sie eine Anfrage an den Schlüssel stellen und die Header ausdrucken. In curl können Sie dazu das Flag -v verwenden:

    user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
    
    * About to connect() to metadata port 80 (#0)
    *   Trying 169.254.169.254... connected
    * Connected to metadata (169.254.169.254) port 80 (#0)
    > GET /computeMetadata/v1/instance/tags HTTP/1.1
    > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
    > Host: metadata
    > Accept: */*
    >
    < HTTP/1.1 200 OK
    < Content-Type: application/text
    < ETag: 411261ca6c9e654e
    < Date: Wed, 13 Feb 2013 22:43:45 GMT
    < Server: Metadata Server for VM
    < Content-Length: 26
    < X-XSS-Protection: 1; mode=block
    < X-Frame-Options: SAMEORIGIN
    <
    cheese
    lettuce

Sie können den ETag-Wert dann in Ihrer wait-for-change-Anfrage verwenden:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"
    

Der Metadatenserver überprüft diesen ETag-Wert und gibt die neuen Inhalte Ihres Metadatenschlüssels zurück, sollte er sich ändern.

In dem folgenden Beispiel für Python ist gut zu sehen, wie Sie den Metadatenserver programmatisch im Hinblick auf Änderungen beobachten können:

last_etag = '0'

    while True:
        r = requests.get(
            url,
            params={'last_etag': last_etag, 'wait_for_change': True},
            headers=METADATA_HEADERS)

        # During maintenance the service can return a 503, so these should
        # be retried.
        if r.status_code == 503:
            time.sleep(1)
            continue
        r.raise_for_status()

        last_etag = r.headers['etag']

Zeitlimits einrichten

Sie können den timeout_sec=<timeout-in-seconds>-Anfrageparameter einrichten, wenn Sie möchten, dass Ihre wait-for-change-Anfrage eine bestimmte Zeit in Sekunden nicht überschreitet. Der Parameter timeout_sec beschränkt die Wartezeit Ihrer Anfrage auf die von Ihnen angegebene Anzahl an Sekunden. Erreicht die Anfrage diesen Wert, ruft sie den aktuellen Inhalt des Metadatenschlüssels auf. Hier ist ein Beispiel für eine Anfrage mit einem Zeitlimit von 360 Sekunden:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"
    

Wenn Sie den timeout_sec-Parameter einrichten, wird die Anfrage jeweils unabhängig davon, ob sich die Metadatenwerte verändert haben, nach Ablauf der Zeit zurückgegeben. Nur ganze Zahlen dürfen als Zeitlimit festgelegt werden.

Statuscodes

Wenn Sie eine wait-for-change-Anfrage durchführen, ruft der Metadatenserver reguläre HTTP-Statuscodes auf, um Erfolg oder Misserfolg anzuzeigen. Tritt ein Fehler auf, kann es sein, dass der Metadatenserver Ihre Anfrage abweist und Ihnen einen Fehlercode schickt. Geschieht dies, sollten Sie Ihre Anwendung so ändern, dass sie fehlertolerant ist und diese Art von Fehlern erkennen und mit ihnen umgehen kann.

Mögliche Statusanzeigen des Metadatenservers:

Status Beschreibung
HTTP 200 Fertig! Ein Wert wurde geändert oder der für timeout_sec angegebene Wert wurde erreicht und die Anfrage wurde erfolgreich beantwortet.
Error 400 Ihre Anfrage war ungültig. Bitte korrigieren Sie Ihre Anfrage und versuchen Sie es erneut.
Error 404 Der Metadatenwert, den Sie angegeben haben, existiert nicht mehr. Der Metadatenserver zeigt diesen Fehler an, wenn Ihre Metadaten gelöscht wurden, während Sie auf eine Veränderung warten.
Error 503 Ein temporärer Serverfehler oder ein temporäres Wartungsereignis ist aufgetreten. Wiederholen Sie die Anfrage.

Live-Migrationshinweise abrufen

Der Metadatenserver stellt Informationen zu den Planungsoptionen und -einstellungen einer Instanz über das Verzeichnis scheduling/ und das Attribut maintenance-event zur Verfügung. Sie können sich mit diesen Attributen über die Planungsoptionen einer VM-Instanz informieren. Die Metadaten können Sie nutzen, um sich benachrichtigen zu lassen, wenn ein Wartungsereignis bevorsteht. Hierzu wird das Attribut maintenance-event verwendet. Standardmäßig sind alle VM-Instanzen auf Live-Migration eingestellt, sodass der Metadatenserver Benachrichtigungen für Wartungsereignisse erhält, bevor eine VM-Instanz live migriert wird. Wenn Sie die Einstellungen so gewählt haben, dass Ihre VM-Instanz während der Wartung beendet wird, dann wird Ihre VM-Instanz durch die Compute Engine automatisch beendet und optional neu gestartet, wenn das Attribut automaticRestart festgelegt ist. Weitere Informationen zu Wartungsereignissen und dem Verhalten von Instanzen während Wartungsereignissen finden Sie unter Planungsoptionen und -Einstellungen.

Durch regelmäßige Abfrage des Attributs maintenance-event können Sie sich darüber informieren, wann ein Wartungsereignis stattfinden wird. Der Wert dieses Attributs ändert sich 60 Sekunden, bevor eine Wartung stattfindet, sodass Ihr Anwendungscode die Möglichkeit hat, Aufgaben einzuleiten, die vor einer Wartung durchgeführt werden sollen, zum Beispiel Datensicherungen oder Aktualisierungen von Logs. Die Compute Engine bietet auch ein Beispielskript in Python, in dem demonstriert wird, wie Sie nach Benachrichtigungen für Wartungsereignisse suchen können.

Die Compute Engine gibt die 60-Sekunden-Warnung nur dann aus, wenn:

  • Sie die Verfügbarkeitsoptionen der Instanz so eingestellt haben, dass bei einem Wartungsereignis live migriert werden soll.

  • Sie haben das Attribut maintenance-event seit dem letzten Wartungsereignis mindestens einmal abgefragt. Wenn Sie noch nie eine Anfrage an das maintenance-event-Attribut geschickt haben oder zumindest nicht seit der letzten Migration, dann geht Compute Engine davon aus, dass die Instanz keine Warnung vor bevorstehenden Wartungen benötigt. In diesem Fall wird die 60-Sekunden-Warnung übersprungen und das Wartungsereignis unmittelbar ausgeführt. Wenn Sie die 60-Sekunden-Warnung nicht überspringen möchten, sollten Sie darauf achten, dass Ihr Clientcode nach einer Migration mindestens einmal das Attribut maintenance-event abfragt.

So fragen Sie das Attribut maintenance-event ab:

    user@myinst:~$ curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event -H "Metadata-Flavor: Google"
    
    NONE
    

Der Start- und Standardwert des Attributs maintenance-event ist NONE.

Bei GPU-Instanzen während eines Wartungsereignis ändert sich das Attribut von NONE in TERMINATE_ON_HOST_MAINTENANCE. Dieses Attribut wird 60 Minuten vor Beginn des Beendigungsereignisses aktualisiert.

Bei Nicht-GPU-Instanzen mit der Planungsoption migrate ändert sich das Attribut maintenance-event so:

  1. Zu Beginn des Migrationsereignisses ändert sich der Wert von NONE in MIGRATE_ON_HOST_MAINTENANCE.
  2. Während des Ereignisses und während Ihre VM-Instanz live migriert wird, bleibt der Wert MIGRATE_ON_HOST_MAINTENANCE.
  3. Nach der Wartung ändert sich der Wert wieder in NONE.

Sie können das Attribut maintenance-event mit dem Feature zum Warten auf Aktualisierungen verwenden, um eine Benachrichtigung über den Beginn und das Ende einer Wartung an Ihre Skripts und Anwendungen zu senden. So können Sie Aktionen automatisieren, die Sie vor oder nach der Wartung ausführen möchten. Das folgende Beispiel für Python zeigt Ihnen, wie Sie die beiden Features zusammen implementieren können.

Beispielskript in Python zum Abfragen von Wartungsereignissen


    import time

    import requests

    METADATA_URL = 'http://metadata.google.internal/computeMetadata/v1/'
    METADATA_HEADERS = {'Metadata-Flavor': 'Google'}

    def wait_for_maintenance(callback):
        url = METADATA_URL + 'instance/maintenance-event'
        last_maintenance_event = None
        last_etag = '0'

        while True:
            r = requests.get(
                url,
                params={'last_etag': last_etag, 'wait_for_change': True},
                headers=METADATA_HEADERS)

            # During maintenance the service can return a 503, so these should
            # be retried.
            if r.status_code == 503:
                time.sleep(1)
                continue
            r.raise_for_status()

            last_etag = r.headers['etag']

            if r.text == 'NONE':
                maintenance_event = None
            else:
                maintenance_event = r.text

            if maintenance_event != last_maintenance_event:
                last_maintenance_event = maintenance_event
                callback(maintenance_event)

    def maintenance_callback(event):
        if event:
            print('Undergoing host maintenance: {}'.format(event))
        else:
            print('Finished host maintenance')

    def main():
        wait_for_maintenance(maintenance_callback)

    if __name__ == '__main__':
        main()

Version des Serverendpunkts prüfen

Die Version Ihres Metadatenserver-Endpunkts prüfen Sie mithilfe des URI, den Sie verwenden, um Anfragen an den Server zu senden.

Version des Metadatenendpunkts URI
v0.1 http://metadata.google.internal/0.1/meta-data/…
v1beta1 http://metadata.google.internal/computeMetadata/v1beta1/…
v1 http://metadata.google.internal/computeMetadata/v1/…

Ältere Endpunkte deaktivieren

Zur Vorbereitung auf das Herunterfahren der Metadatenserver-Endpunkte v0.1 und v1beta1 können Sie diese Endpunkte auf Projekt- oder Instanzebene deaktivieren.

Folgen Sie zum Deaktivieren der Metadatenserver-Endpunkte v0.1 und v1beta1 der Anleitung zum Festlegen von benutzerdefinierten Metadaten und legen Sie disable-legacy-endpoints=TRUE fest.

Führen Sie beispielsweise den folgenden Befehl aus, um den Metadatenserver-Endpunkt auf Projektebene mit dem Befehlszeilentool gcloud zu deaktivieren:

gcloud compute project-info add-metadata \
        --metadata disable-legacy-endpoints=TRUE 

Auf Metadatenserver-Endpunkt v1 umstellen

Informationen zur Umstellung von v0.1 oder v1beta1 auf den v1-Endpunkt finden Sie unter Zum Metadatenserver-Endpunkt v1 migrieren.

Weitere Informationen