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 nach Informationen über die Instanz wie den Hostnamen, die Instanz-ID, Skripts beim Starten und Beenden, benutzerdefinierte Metadaten und Dienstkontodaten abfragen. 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 das 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 neuste Serverversion verwenden. Google 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!

Hinweise

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 Metadaten für die Instanz festgelegt werden
  • compute.projects.setCommonInstanceMetadata, 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 auf Projekt- und Instanzebene zugewiesen werden. Bei einem Projekt werden die Metadaten allen virtuellen Maschineninstanzen innerhalb des Projekts zur Verfügung gestellt, während sie bei einer Instanz nur für die jeweilige Instanz verfügbar sind.

Standard-Metadatenschlüssel

Google 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. Eine manuelle Bearbeitung dieser Metadatenpaare ist nicht möglich.

Die folgende Liste führt die Standard-Metadaten für ein Projekt auf. Bei einigen Metadaten-Einträgen handelt es sich um Verzeichnisse, die andere Metadatenschlüssel enthalten. Der Unterschied wird durch einen Schrägstrich im Namen der Metadaten angezeigt. So ist zum Beispiel attributes/ ein Verzeichnis, das andere Schlüssel enthält, während numeric-project-id ein Metadatenschlüssel ist, der sich auf einen Wert bezieht.

Bezug nehmend auf http://metadata.google.internal/computeMetadata/v1/project/
Metadateneintrag Beschreibung
attributes/ Ein Verzeichnis mit benutzerdefinierten Metadaten-Werten, 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, um v1-Endpunkte zu 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 Ihr Projekt und Ihre Instanzen 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 in diesem Projekt 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 Platform Console angezeigt wird. Dieser Wert unterscheidet sich vom Wert für project-id des Metadateneintrags.
project-id Die Projekt-ID.

Es folgt eine Liste mit Standard-Metadaten für Instanzen:

Bezug nehmend auf http://metadata.google.internal/computeMetadata/v1/instance/
Metadateneintrag Beschreibung
attributes/ Ein Verzeichnis mit benutzerdefinierten Metadaten-Werten, 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 der Laufwerke, die an diese Instanz angehängt 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. Dies ist eine einzigartige, numerische ID, die von Google Compute Engine erstellt wird. Wenn Sie keine Instanznamen verwenden möchten, bietet sie sich zur Identifizierung von Instanzen an.
machine-type Der Metadatenwert für den Maschinentyp dieser Instanz. Dieser hat folgendes Format: 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. Zum Festlegen des Werts wird das Flag --on_host_maintenance oder die API verwendet.
scheduling/automatic-restart Die Einstellung für den automatischen Neustart der Instanz. Zum Festlegen des Werts wird das Flag ‑‑automatic_restart oder die API verwendet.
scheduling/preemptible Die präemptive Einstellung der Instanz. Die Instanz ist präemptiv, wenn dieser Wert TRUE ist. Dieser Wert wird bei Erstellung einer Instanz eingerichtet und kann nicht mehr 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 Instanz-Metadatenwert müssen Sie den Parameter "audience" in Ihrer Anfrage angeben. Beispiel:"audience=http://www.example.com". Unter Identität von Instanzen prüfen wird beschrieben, wie Instanz-Identitätstoken angefordert und geprüft werden.
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. Zwischen Instanz und Metadatenserver können Sie Standardtools wie curl oder wget verwenden.

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

Beachten Sie, dass beim Abrufen von Metadaten vom Server mit dem Befehl "curl" einige codierte Zeichen im Anforderungspfad nicht unterstützt werden. Codierte Zeichen werden nur im Abfragepfad unterstützt.

Die folgende Anforderung funktioniert beispielsweise eventuell nicht:

http://metadata.goog/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true

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

http://metadata.goog/computeMetadata/v1/instance/service-accounts1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true

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 durch eine Anfrage Informationen vom Metadatenserver abrufen, verlassen die Anfrage und die folgende Antwort zu keinem Zeitpunkt 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

Handelt es sich bei einem Metadatenschlüssel nicht um ein Verzeichnis, dann ist es 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.

So gibt der Schlüssel tags zum Beispiel Daten automatisch im JSON-Format wieder. Sie können mit dem Abfrageparameter alt=text Daten auch als Text anzeigen lassen:

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 unter einem Verzeichnis anzeigen wollen, können Sie dies tun, indem Sie recursive=true bei Ihrer Abfrage verwenden:

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 stattdessen Text sehen möchten, fügen Sie alt=text hinzu:

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

Benutzerdefinierte Metadaten einrichten

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

Größeneinschränkungen bei benutzerdefinierten Metadaten

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

Benutzerdefinierte Metadaten für eine Instanz können Sie über die GCP Console, das gcloud-Tool oder die API festlegen. Instanzmetadaten beziehen sich nur auf eine bestimmte Instanz.

Metadaten beim Erstellen einer Instanz festlegen

Konsole

gcloud

Verwenden Sie das gcloud-Befehlszeilentool, um über das Flag --metadata 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://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

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

Metadaten auf einer laufenden Instanz aktualisieren

Konsole

  1. Öffnen Sie die 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 Instanz-Metadaten 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 \
  --metadata bread=mayo,cheese=cheddar,lettuce=romaine

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

gcloud compute instances add-metadata INSTANCE --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 --keys lettuce

API

Stellen Sie in der API eine Anfrage an die Methode instances().setMetadata. Geben Sie eine Liste mit neuen Metadatenwerten und dem aktuellen fingerprint-Wert 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 Wert des Fingerabdrucks 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://www.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"
   }
  ]
 },
 ...
}

Stellen Sie dann eine Anfrage an die Methode instances().setMetadata und stellen Sie Ihre benutzerdefinierten Metadaten-Schlüssel/Wert-Paare ein. 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://www.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://www.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 zum Beispiel ein Metadatenpaar für baz=bat erstellen, dann wird es automatisch auf alle Instanzen im Projekt angewendet.

Konsole

  1. Öffnen Sie die 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.

Mit dem Flag --metadata-from-file können Sie auch eine oder mehrere Dateien angeben, aus denen die 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 Methode projects().setCommonInstanceMetadata und geben Sie alle neuen Metadatenwerte und einen fingerprint-Wert 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 Wert des Fingerabdrucks 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.

Führen Sie eine project().get-Anfrage durch und kopieren Sie den Fingerabdruckwert:

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

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

Stellen Sie dann eine Anfrage an die Methode projects().setCommonInstanceMetadata und richten Sie Ihre benutzerdefinierten Metadaten-Schlüssel/Wert-Paare ein:

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

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

Benutzerdefinierte Metadaten abfragen

Sie können benutzerdefinierte Instanz- oder Projektmetadaten über die GCP Console, das gcloud-Befehlszeilentool oder die API abfragen.

Konsole

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

Aufrufen der benutzerdefinierten Metadaten für die Instanz:

  1. Gehen Sie auf die Seite VM-Instanzen.
  2. Klicken Sie auf die Instanz, deren Metadaten Sie aufrufen.
  3. Rufen Sie die Daten der Instanz unter Benutzerdefinierte Metadaten auf.

gcloud

Abfrage von Metadaten für ganze Projekte:

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

Abfrage von Instanzmetadaten:

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

Mit dem Flag --flatten können Sie die Ausgabe auf einen relevanten Metadatenschlüssel beschränken. Im folgenden Beispiel ist es eine Instanz mit dem benutzerdefinierten 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 eine leere Anfrage an die Methode projects().get durch, wenn Sie die Metadaten eines Projekts aufrufen wollen:

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

Um die Metadaten einer Instanz abzurufen, müssen Sie eine leere Anfrage an die Methode instance().get durchführen:

GET https://www.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, die kleine Datenmengen erfordern, die sich selten ä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 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, Cloud 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 von außerhalb der Instanz nur dann lesen, wenn sie eine IAM-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:

Konsole

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

  1. Rufen Sie in der GCP Console die Seite "VM-Instanzen" auf.

    Zur Seite "VM-Instanzen"

  2. Klicken Sie auf Instanz erstellen.
  3. Legen Sie auf der Seite Neue Instanz erstellen die gewünschten Attribute für Ihre Instanz fest.
  4. Fügen Sie im Abschnitt Metadaten einen Metadateneintrag mit dem Schlüssel enable-guest-attributes und dem Wert TRUE hinzu.
  5. Klicken Sie auf Erstellen, um die Instanz zu erstellen.

So legen Sie enable-guest-attributes in den Projektmetadaten fest, damit der Metadateneintrag für alle Instanzen im Projekt gilt:

  1. Öffnen Sie die 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 festlegen, um dieses Feature zu deaktivieren.
  4. Klicken Sie auf Speichern, um die Änderungen zu übernehmen.

So legen Sie enable-guest-attributes in den Metadaten einer vorhandenen Instanz fest:

  1. Öffnen Sie die 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 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 den Wert auf FALSE festlegen, um die Instanz von diesem Feature auszuschließen.
  5. Klicken Sie unten auf der Seite mit den Instanzdetails auf Speichern, um die Änderungen für die Instanz zu übernehmen.

gcloud

So legen Sie enable-oslogin-2fa beim Erstellen einer Instanz in den Instanzmetadaten fest:

Führen Sie im gcloud-Befehlszeilentool den Befehl gcloud compute instances create aus und legen Sie enable-guest-attributes=TRUE fest, um Gastattribute zu aktivieren:

gcloud compute instances create [INSTANCE_NAME] --metadata enable-guest-attributes=TRUE

So legen Sie enable-guest-attributes in den Projektmetadaten fest, damit der Metadateneintrag für alle Instanzen im Projekt gilt:

Führen Sie im gcloud-Befehlszeilentool den Befehl project-info add-metadata aus 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.

So legen Sie enable-guest-attributes in den Metadaten einer vorhandenen Instanz fest:

Führen Sie im gcloud-Befehlszeilentool den Befehl instances add-metadata aus und legen Sie enable-guest-attributes=TRUE fest, um Gastattribute zu aktivieren:

gcloud compute instances add-metadata [INSTANCE_NAME] --metadata enable-guest-attributes=TRUE

Alternativ können Sie enable-guest-attributes auf FALSE festlegen, um die Instanz von der Verwendung von Gastattributen auszuschließen.

Gastattribute festlegen

Jeder in der virtuellen Maschine 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 innerhalb der Instanz verwenden, um einen Wert in den guest-attributes-Metadatenpfad 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] ist eine logische Gruppierung für [KEY]. Gastattribute müssen einen Namespace haben.
  • [VALUE] ist der Wert, den Sie schreiben möchten.
  • [KEY] ist der Pfad innerhalb von guest-attributes, in dem der Wert gespeichert wird.

Gastattribute abrufen

Nutzer oder Dienstkonten können Gastattribute lesen, wenn sie eine 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 in der virtuellen Maschine ausgeführte Prozess kann Gastattributwerte abrufen. Das gilt auch für Skripts und Anwendungen, die keine Sudo- oder Administratorberechtigungen haben. Sie können beispielsweise eine curl-Anfrage innerhalb der Instanz verwenden, um einen Wert aus dem guest-attributes-Metadatenpfad zu lesen:

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

Dabei gilt: [KEY] ist der Pfad innerhalb von guest-attributes, aus dem der Metadatenwert gelesen werden soll.

Alternativ können Sie alle Gastattributwerte mit einer einzigen Anfrage zurückgeben:

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

Dabei gilt:

  • [NAMESPACE] ist eine logische Gruppierung für [KEY]. Gastattribute müssen einen Namespace haben.
  • [KEY] ist der Pfad innerhalb von guest-attributes, in dem der Wert gespeichert ist.

gcloud

Verwenden Sie das gcloud-Befehlszeilentool, 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]

Dabei gilt:

  • [INSTANCE_NAME] ist der Name der Instanz, aus der Sie den Metadatenwert des Gastattributs lesen möchten.
  • [KEY] ist der Pfad innerhalb der guest-attributes-Metadaten, in dem der Wert gespeichert ist.
  • [ZONE] ist die Zone, in der sich die Instanz befindet.

API

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

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

Dabei gilt:

  • [PROJECT_ID] ist die Projekt-ID.
  • [ZONE] ist die Zone, in der sich Ihre Instanz befindet.
  • [INSTANCE_NAME] ist der Name der Instanz, aus der Sie den Metadatenwert des Gastattributs lesen möchten.
  • [KEY] ist der Pfad innerhalb der guest-attributes-Metadaten, in dem der Wert gespeichert ist.

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

GET https://www.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://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes

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

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

Dabei gilt:

  • [OAUTH_TOKEN] ist das OAuth-Token.
  • [PROJECT_ID] ist die Projekt-ID.
  • [ZONE] ist die Zone, in der sich Ihre Instanz befindet.
  • [INSTANCE_NAME] ist der Name der Instanz, aus der Sie den Metadatenwert des Gastattributs lesen möchten.
  • [NAMESPACE] ist eine logische Gruppierung für [KEY]. Gastattribute müssen einen Namespace haben.
  • [KEY] ist der Pfad innerhalb der guest-attributes-Metadaten, in dem der Wert gespeichert ist.

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"

Dabei gilt:

  • [NAMESPACE] ist eine logische Gruppierung für [KEY]. Gastattribute müssen einen Namespace haben.
  • [KEY] ist der Pfad innerhalb von guest-attributes, in dem der Wert gespeichert ist.

Gastattribute für Ihre Organisation oder Ihren Ordner deaktivieren

Wenn Sie nicht möchten, dass für eine der Instanzen in Ihrer Organisation oder in Ihrem Ordner Gastattribute aktiviert sind, können Sie das Feature außer Kraft setzen und damit vollständig deaktivieren.

Legen Sie die Einschränkung constraints/compute.disableGuestAttributesAccess für Ihre Organisation oder Ihren Ordner fest:

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

Dabei ist [PROJECT_ID] der Name des Projekts.

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 noch läuft, bietet der Metadatenserver Ihnen die Möglichkeit, sich benachrichtigen zu lassen, falls sich etwas ändert. Mit dieser Funktion können Sie ausstehende HTTP GET-Anfragen durchführen, die nur antworten, wenn die angegebenen Metadaten geändert wurden. Sie können diese Funktion 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 zum Beispiel eine Anfrage an den Schlüssel tags schicken, so dass die Anfrage nur zurückgeschickt wird, wenn sich der Inhalt der Tag-Metadaten 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.

Um den aktuellen ETag-Wert für einen Metadatenschlüssel zu erhalten, können Sie eine Anfrage an den Schlüssel stellen und die Header ausdrucken. In CURL ist dies mit dem Flag -v möglich:

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 auf Änderungen überwachen 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 den von Ihnen angegebenen Wert. 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. Der Metadatenserver erhält also Wartungsereignis-Benachrichtigungen, 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 gesetzt 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, so dass 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 in diesen Fällen aus:

  • Sie haben die Verfügbarkeitsoptionen der Instanz so eingestellt, 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.

Gehen Sie für die Abfrage des Attributs maintenance-event wie folgt vor:

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. Vor einer Wartung geschieht mit dem Wert maintenance-event Folgendes:

  1. Er ändert sich von NONE in MIGRATE_ON_HOST_MAINTENANCE.
  2. Während des Ereignisses und während Ihre VM 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.


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

Umstellung auf v1

Der v1 Metadatenserver unterscheidet sich in seiner Funktionsweise leicht vom v1beta1-Server. Dies sind einige der Änderungen, die für den neuen Server vorgenommen werden müssen:

  • Aktualisieren Sie Metadatenanfragen, um den Header Metadata-Flavor: Google mit aufzunehmen.

    Für den neuen Metadatenserver müssen alle Anfragen den Header Metadata-Flavor: Google besitzen. Dieser zeigt an, dass die Anfrage zum Aufrufen von Metadatenwerten gestellt wird. Aktualisieren Sie Ihre Anfragen, damit sie diesen Header einschließen. Eine Anfrage an das Attribut disks/ würde nun wie folgt aussehen:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
    
  • Aktualisieren Sie Anfragen, die den Header X-Forwarded-For verwenden

    Diese Anfragen werden vom Server automatisch abgelehnt, da es oftmals ein Anzeichen ist, dass sie weitergeleitet wurden. Aktualisieren Sie Ihre Anfragen, damit Sie diesen Header nicht mehr enthalten.

Weitere Informationen

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Compute Engine-Dokumentation