Instanzattribute aktualisieren

Sie können eine einzelne Anfrage über die Google Cloud CLI oder die Compute Engine API verwenden, um mehrere Instanzattribute zu aktualisieren und die Instanz bei Bedarf optional neu zu starten. Die Aktualisierungsmethode verarbeitet die Logik zur Validierung der aktualisierten Instanzattribute und sorgt dafür, dass die erforderlichen Ressourcen verfügbar sind, um die Aktualisierung erfolgreich abzuschließen. Wenn die Anfrage ungültige Attribute enthält oder die angeforderten Ressourcen nicht verfügbar sind, gibt die Anfrage einen Fehler zurück und nimmt keine Änderungen an Ihrer Instanz vor. Dadurch wird die Instanz vor Teilaktualisierungen geschützt und es wird verhindert, dass die Instanz gestoppt wird und nicht wieder auf für einen Neustart nötige Ressourcen zugreifen kann.

Vorbereitung

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

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

    Console

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

    gcloud

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

      gcloud init
    2. Set a default region and zone.

      3. REST

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

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

        gcloud init

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

Beschränkungen

  • Anfragen zur Instanzaktualisierung mit der gcloud CLI oder der Compute Engine API unterstützen keine PATCH-Semantik. Die Instanzressource in der Aktualisierungsanfrage muss alle Attribute der Instanz enthalten. Attribute, die in der Instanzkonfiguration der Aktualisierungsanfrage fehlen, werden als von der Instanz gelöscht betrachtet.
  • Sie können nur bestimmte Liste von Attributen aktualisieren.
  • Instanzen lassen sich auf diesem Wege nicht in Instanzen für einzelne Mandanten ändern oder andersherum.
  • Sie können eine Instanz mithilfe des Aktualisierungsvorgangs von einer Reservierung zu einer anderen ändern, aber nicht eine Instanz an eine Reservierung anhängen oder davon trennen.
  • Wenn an die Instanz eine lokale SSD angehängt ist, können Sie keine Attribute aktualisieren, für die die Instanz neu gestartet werden muss. Sie müssen die Instanz löschen und neu erstellen. Achten Sie darauf, dass Sie Ihre kritischen Daten von der lokalen SSD zu einem nichtflüchtigen Speicher oder zu einer anderen VM migrieren, bevor Sie die VM löschen.
  • Wenn eine Instanz Ressourcen verwendet, die nur in der Betaversion der Compute Engine API verfügbar sind, müssen Sie diese Attribute mit der richtigen Version der Methode instances.update aktualisieren. Wenn Sie zum Beispiel eine Instanz mit der Beta Compute Engine API erstellen und die Instanz mit einer Ressource konfigurieren, die nur die Betaversion der API erkennt, müssen Sie diese Ressourcen auch mit der Betaversion der Methode instances.update aktualisieren. Die v1-Version der Methode instances.update erkennt die von Ihrer Instanz verwendeten Betaressourcen nicht. Deshalb werden diese Betaressourcen während der Aktualisierung aus der Instanzkonfiguration gelöscht. Dies gilt auch für Ressourcen in der Alpha API.

Berechtigungen

Zum Aktualisieren von Instanzen benötigen Sie die Berechtigung compute.instances.update. Diese Berechtigung ist in mehreren vorhandenen IAM-Rollen (Identity and Access Management, Identitäts- und Zugriffsverwaltung) enthalten. Sie benötigen außerdem die Berechtigung, die Ressourcen zu verwenden, die Sie auf der Instanz ändern möchten. Wenn Sie einer Instanz beispielsweise ein Laufwerk hinzufügen möchten, benötigen Sie die folgenden Berechtigungen:

  • Die Berechtigung compute.instances.update für die Instanz, die Sie aktualisieren möchten.
  • Entweder die Berechtigung compute.disks.use für ein vorhandenes Laufwerk oder compute.disks.create für ein Projekt, in dem Sie ein neues Laufwerk erstellen möchten.

Best Practices

Achten Sie auf die folgenden Best Practices, damit die Schnittstelle zur Instanzaktualisierung so effektiv wie möglich funktioniert:

  • Verwenden Sie nach Möglichkeit immer dieselbe Version der Compute Engine API, um Instanzen zu erstellen, festzulegen und zu aktualisieren. Dadurch wird sichergestellt, dass Sie alle Instanzressourcen aktualisieren und ändern können, wenn sie nur in einer Version der API verfügbar sind.
  • Sie können die Methode instances.update auch zum Aktualisieren von Instanzen in einer verwalteten Instanzgruppe verwenden. In den meisten Fällen ist es jedoch besser, stattdessen die Instanzvorlage der Gruppe zu ändern und dieses Update auf die verwaltete Instanzgruppe anzuwenden.

Attribute, die aktualisiert werden können

Sie können mit der Aktualisierungsmethode nur bestimmte Instanzattribute ändern. Für die Aktualisierung einiger Attribute muss die Instanz neu gestartet werden. Damit versehentliche Neustarts der Instanzen verhindert werden, muss in der Anfrage festgelegt sein, welche Aktion für Ihre Instanzen zulässig ist. Sie können in der Anfrage eine der folgenden Aktionen angeben:

  • NO_EFFECT: Die Aktualisierungsanfrage prüft, ob die Anfrage gültig ist und ob die Ressourcen verfügbar sind. Die Aktualisierung wird jedoch nicht ausgeführt. Verwenden Sie diese Option, um Befehle zu testen, ohne tatsächliche Aktualisierungen zu starten.
  • REFRESH: Die Aktualisierungsanfrage wird nur ausgeführt, wenn die Instanz nicht aufgrund der geänderten Instanzattribute neu gestartet werden muss. Die Anfrage gibt den Fehler INFEASIBLE zurück, wenn die Anfrage gültig ist, aber ein Neustart erforderlich ist.
  • RESTART: Wenn die Aktualisierung es erfordert, startet das System die Instanz neu.

Attribute, deren Aktualisierung RESTART erfordert:

  • disks –Bootlaufwerke
    • disks.deviceName – Alle Laufwerke
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkPerformanceConfig
  • performanceMonitoringUnit
  • reservationAffinity
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

Attribute, deren Aktualisierung nur REFRESH erfordert:

  • canIpForward
  • deletionProtection
  • description
  • disks – Nicht-Bootlaufwerksattribute, mit Ausnahme von deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

Instanzattribute aktualisieren

Führen Sie die folgenden Schritte aus, um Ihre Instanz zu aktualisieren:

  1. Exportieren Sie die vorhandenen Instanzkonfigurationsattribute.
  2. Ändern Sie die Attribute der Instanzkonfiguration.
  3. Führen Sie eine Testanfrage aus, indem Sie die umfangreichste Aktion NO_EFFECT angeben. In der Antwort sind ungültige Felder in der Instanzkonfiguration sowie die Aktion angegeben, die zum Anwenden der Änderungen erforderlich ist.
  4. Wenn die Konfiguration akzeptabel ist, fordern Sie eine Instanzaktualisierung an und geben Sie die umfangreichste Aktion an, die für Ihr Instanzupdate akzeptabel ist.

Der Aktualisierungsvorgang wird nur dann gestartet, wenn Ihre Anfrage die folgenden Anforderungen erfüllt:

  • Das Instanzattribut fingerprint in Ihrer Anfrage muss mit dem fingerprint der Instanz übereinstimmen, die Sie aktualisieren möchten. Dadurch wird verhindert, dass Aktualisierungsanfragen durch andere gleichzeitige für dieselbe Instanz überschrieben werden.
  • Die Attribute in Ihrer Aktualisierungsanfrage müssen gültig sein.
  • Die angeforderten Ressourcen müssen verfügbar sein.
  • Wenn für die Attribute in Ihrer Anfrage die Instanz neu gestartet werden muss, muss in der Anfrage RESTART als zulässige Aktion angegeben sein.

Wenn die Anforderungen erfüllt sind, startet das System den Instanzaktualisierungsvorgang. Andernfalls nimmt das System keine Änderungen an der vorhandenen Instanz oder der zugehörigen Konfiguration vor.

Sie können Aktualisierungen entweder mit der gcloud CLI oder der Compute Engine API initiieren.

gcloud

  1. Verwenden Sie den Befehl instances export, um die vorhandenen Instanzattribute zu exportieren:

    gcloud compute instances export INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --destination=FILE_PATH

    Ersetzen Sie dabei Folgendes:

    • INSTANCE_NAME ist der Name der Instanz, die Sie exportieren möchten.
    • PROJECT_ID ist die Projekt-ID für diese Anfrage.
    • ZONE ist die Zone für diese Instanz.
    • FILE_PATH ist der Ausgabepfad, unter dem Sie die Instanzkonfigurationsdatei auf Ihrer lokalen Workstation speichern möchten.

  2. Verwenden Sie einen Texteditor, um ein oder mehrere Attribute in der exportierten Instanzkonfigurationsdatei zu ändern. Weitere Informationen zu den Attributen, die Sie aktualisieren können, finden Sie in der Liste der aktualisierbaren Attribute. Ändern Sie zum Beispiel das Attribut machineType, um den Maschinentyp der Instanz zu ändern:

    ⋮
machineType: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE
⋮

    Ersetzen Sie dabei Folgendes:

    • PROJECT_ID ist die Projekt-ID für diese Anfrage.
    • ZONE ist die Zone für diese Instanz.
    • MACHINE_TYPE ist der Maschinentyp der Instanz. Beispiel: n1-standard-2.

  3. Führen Sie mit dem Befehl instances update-from-file eine Testaktualisierung der Zielinstanz aus. Geben Sie das Flag --most-disruptive-allowed-action=NO_EFFECT an. In der Antwort werden falsch konfigurierte Attribute angegeben und es wird festgelegt, ob die Aktion RESTART oder REFRESH erforderlich ist, um die Aktualisierung anzuwenden.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action NO_EFFECT

    Ersetzen Sie dabei Folgendes:

    • INSTANCE_NAME ist der Name der Instanz, die Sie exportieren möchten.
    • PROJECT_ID ist die Projekt-ID für diese Anfrage.
    • ZONE ist die Zone für diese Instanz.
    • FILE_PATH ist der Pfad zur geänderten Instanzkonfigurationsdatei auf Ihrer lokalen Workstation.

  4. Aktualisieren Sie die Zielinstanz mit dem Befehl instances update-from-file. Wenn Sie ein Attribut aktualisieren, für das die Instanz neu gestartet werden muss, fügen Sie das Flag --most-disruptive-allowed-action=RESTART ein. Wenn die Attribute keinen Neustart erfordern, geben Sie das Flag --most-disruptive-allowed-action=REFRESH an. Weitere Informationen zu den Attributen, die einen Neustart erfordern, finden Sie in der Liste der aktualisierbaren Attribute.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action ALLOWED_ACTION

    Ersetzen Sie dabei Folgendes:

    • INSTANCE_NAME ist der Name der Instanz, die Sie exportieren möchten.
    • PROJECT_ID ist die Projekt-ID für diese Anfrage.
    • ZONE ist die Zone für diese Instanz.
    • FILE_PATH ist der Pfad zur geänderten Instanzkonfigurationsdatei auf Ihrer lokalen Workstation.
    • ALLOWED_ACTION definiert, wie umfangreich die Aktualisierung sein kann. Geben Sie RESTART an, um einen vollständigen Neustart der Instanz zu ermöglichen. Geben Sie REFRESH an, um die Instanz nur dann zu aktualisieren, wenn die geänderten Attribute keinen Neustart der Instanz erfordern.

Wenn die Aktualisierungsanfrage gültig ist und die erforderlichen Ressourcen verfügbar sind, beginnt die Instanzaktualisierung. Sie können den Status dieses Vorgangs durch Aufrufen der Audit-Logs überwachen. Wenn das Update einen Neustart erfordert und Ihr Befehl ein RESTART zulässt, wird die Instanz neu gestartet, um die Änderungen zu übernehmen.

REST

  1. Verwenden Sie die Methode instances.get in der Compute Engine API, um die vorhandenen Instanzattribute zu exportieren:

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

    Ersetzen Sie dabei Folgendes:

    • PROJECT_ID ist die Projekt-ID für diese Anfrage.
    • ZONE ist die Zone für diese Instanz.
    • INSTANCE_NAME ist der Name der Instanz, die Sie exportieren möchten.

    Diese Anfrage gibt eine Instanzressourcendefinition zurück.

  2. Ändern Sie in der Antwort die Attribute der Instanzressource. In der Liste der aktualisierbaren Attribute finden Sie Informationen dazu, welche Attribute aktualisiert werden können. Ändern Sie zum Beispiel das Attribut machineType, um den Maschinentyp der Instanz zu ändern: Sie können mehrere Attribute ändern.

    {
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE",
  ⋮
}

    Ersetzen Sie dabei Folgendes:

    • PROJECT_ID ist die Projekt-ID für diese Anfrage.
    • ZONE ist die Zone für diese Instanz.
    • MACHINE_TYPE ist der Maschinentyp der Instanz. Beispiel: n1-standard-2.

  3. Verwenden Sie in der Compute Engine API die Methode instances.update und geben Sie most_disruptive_allowed_action=NO_EFFECT an, um eine Testaktualisierung der Zielinstanz durchzuführen. Die Antwort identifiziert falsch konfigurierte Attribute und gibt an, ob eine RESTART- oder REFRESH-Aktion zum Anwenden der Aktualisierung erforderlich ist.

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=NO_EFFECT

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    Ersetzen Sie dabei Folgendes:

    • PROJECT_ID ist die Projekt-ID für diese Anfrage.
    • ZONE ist die Zone für diese Instanz.
    • INSTANCE_NAME ist der Name der Instanz, die Sie exportieren möchten.

  4. Verwenden Sie die Methode instances.update in der Compute Engine API, um die Zielinstanz zu aktualisieren. Wenn Sie ein Attribut aktualisieren, das einen Neustart der Instanz erfordert, fügen Sie den Abfrageparameter ?most_disruptive_allowed_action=RESTART ein, um anzugeben, dass die Instanz während der Aktualisierung neu gestartet werden kann. Wenn die Attribute keinen Neustart benötigen, geben Sie den Abfrageparameter ?most_disruptive_allowed_action=REFRESH an. Weitere Informationen zu den Attributen, die einen Neustart erfordern, finden Sie in der Liste der aktualisierbaren Attribute. Fügen Sie den vollständigen Text für die geänderte Instanzressource hinzu: Im folgenden Beispiel ändert der Text den Maschinentyp in n1-standard-2:

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=ALLOWED_ACTION

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    Ersetzen Sie dabei Folgendes:

    • PROJECT_ID ist die Projekt-ID für diese Anfrage.
    • ZONE ist die Zone für diese Instanz.
    • INSTANCE_NAME ist der Name der Instanz, die Sie exportieren möchten.
    • ALLOWED_ACTION definiert, wie umfangreich die Aktualisierung sein kann. Geben Sie RESTART an, um einen vollständigen Neustart der Instanz zu ermöglichen. Geben Sie REFRESH an, um die Instanz nur dann zu aktualisieren, wenn die geänderten Attribute keinen Neustart der Instanz erfordern.

Wenn die Aktualisierungsanfrage gültig ist und die erforderlichen Ressourcen verfügbar sind, beginnt die Instanzaktualisierung. Sie können den Status dieses Vorgangs durch Aufrufen der Audit-Logs überwachen. Wenn das Update einen Neustart erfordert und Ihr Befehl ein RESTART zulässt, wird die Instanz neu gestartet, um die Änderungen zu übernehmen.

Nächste Schritte