更新執行個體屬性

您可以使用 Google Cloud CLI 或 Compute Engine API 中的單一要求來更新多個執行個體的屬性，並視需要重新啟動執行個體。更新方法會處理驗證更新的執行個體屬性，並確保可使用必要資源來順利完成更新的邏輯。如果要求包含無效的屬性，或是要求的資源無法使用，要求會傳回錯誤，且不會對您的執行個體進行任何變更。這可防止部分更新，並防止執行個體遭到停止，無法存取資源來重新啟動。

事前準備

  • 如果尚未設定，請先設定驗證機制。驗證是指驗證身分，以便存取 Google Cloud 服務和 API 的程序。如要在本機開發環境中執行程式碼或範例，您可以選取下列任一選項，向 Compute Engine 進行驗證：

    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. After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

限制

  • 透過 gcloud CLI 或 Compute Engine API 提出的執行個體更新要求不支援 PATCH 語意。更新要求中的例項資源必須包含例項的所有屬性。更新要求中的實例設定缺少的屬性，會視為從實例中刪除。
  • 您只能更新特定的房源清單。
  • 不支援將執行個體變更為單一租戶模式，或從單一租戶模式變更。
  • 您可以將執行個體從一個保留項目變更為另一個保留項目，但無法透過更新程序將執行個體連結或取消連結至保留項目。
  • 如果執行個體已連接本機 SSD 磁碟，您就無法更新需要在執行個體執行期間重新啟動執行個體的屬性。您可以刪除再重新建立執行個體，或是停止執行個體、更新屬性，然後重新啟動。
  • 如果執行個體使用僅在 Compute Engine API 測試版中提供的資源，您必須使用正確版本的 instances.update 方法來更新這些屬性。舉例來說，如果您使用 Beta 版 Compute Engine API 建立執行個體，並使用只有 Beta 版 API 可辨識的資源設定執行個體，則必須使用 Beta 版 instances.update 方法來更新這些資源。instances.update 方法的 v1 版本無法辨識執行個體使用的 Beta 版資源，因此會在更新程序中從執行個體設定中刪除這些 Beta 版資源。這項行為也適用於 alpha API 中的資源。

權限

您必須具備 compute.instances.update 權限才能更新執行個體。這項權限包含在多個現有的身分與存取權管理 (IAM) 角色中。您也必須具備在執行個體上使用所需資源的權限。舉例來說，如要將磁碟新增至執行個體，您必須具備下列權限：

  • 您要更新的執行個體上的 compute.instances.update 權限。
  • compute.disks.use 現有磁碟的權限，或是compute.disks.create 要建立新磁碟的專案。

最佳做法

為確保您能有效使用執行個體更新介面，請採用下列最佳做法：

  • 請盡可能使用相同版本的 Compute Engine API 來建立、設定及更新執行個體。這樣一來，如果某項例項資源僅適用於單一 API 版本，您就能更新及修改該資源。
  • 雖然您可以使用 instances.update 方法更新代管執行個體群組 (MIG) 中的執行個體，但在大多數情況下，建議您改為變更群組的執行個體範本，並將更新內容推送至 MIG。

可更新的屬性

您只能透過 update 方法變更特定一組例項屬性。部分資源的更新需要重新啟動執行個體。為避免執行個體意外重新啟動，您的要求必須定義可在執行個體上執行的動作。您可以要求執行下列任一動作：

  • NO_EFFECT：更新要求會檢查要求是否有效，以及資源是否可用，但不會執行更新。使用這個動作可測試指令，而無須啟動任何實際更新。
  • REFRESH：只有在修改的執行個體屬性不需要重新啟動執行個體時，更新要求才會執行。如果要求有效但需要重新啟動，則要求會傳回 INFEASIBLE 錯誤。
  • RESTART：如果更新需要重新啟動執行個體，系統會重新啟動執行個體。

下列資源必須重新啟動 (RESTART) 才能更新：

  • disks：開機磁碟，包括所有磁碟 (disks.deviceName)
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkPerformanceConfig
  • performanceMonitoringUnit
  • reservationAffinity：您只能更新執行個體如何使用預留空間 (reservationAffinity.consumeReservationType)，方法如下：
    • 從使用任何相符的保留項目 (ANY_RESERVATION) 到不使用保留項目 (NO_RESERVATION)
    • 從不使用保留項目 (NO_RESERVATION) 到使用任何相符的保留項目 (ANY_RESERVATION)
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

下列資源只需要重新整理 (REFRESH) 即可更新：

  • canIpForward
  • deletionProtection
  • description
  • disks：非開機磁碟屬性 (不含 deviceName)
  • labels
  • metadata
  • nodeAffinities
  • tags

更新執行個體屬性

請按照下列步驟更新執行個體：

  1. 匯出現有執行個體設定屬性。
  2. 修改執行個體設定的屬性。
  3. 將 NO_EFFECT 指定為最具干擾性的動作，執行測試要求。這項回應會指出例項設定中的無效欄位，並指出套用變更所需的動作。
  4. 如果設定可接受，請要求執行個體更新，並指定執行個體更新可接受的最大干擾動作。

只有在您的要求符合下列規定時，系統才會開始更新程序：

  • 要求中的執行個體 fingerprint 屬性必須與要更新的執行個體 fingerprint 相符。這可避免同一個執行個體上的同時更新要求互相覆寫。
  • 更新要求中的屬性必須有效。
  • 您要求的資源必須可用。
  • 如果要求中的屬性需要重新啟動執行個體，則要求必須將 RESTART 指定為允許的動作。

如果符合上述條件，系統就會啟動執行個體更新程序。否則，系統不會對現有執行個體或其設定進行任何變更。

您可以使用 gcloud CLI 或 Compute Engine API 啟動更新。

gcloud

  1. 使用 instances export 指令匯出現有的執行個體屬性：

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

    更改下列內容：

    • INSTANCE_NAME：要匯出的執行個體名稱。
    • PROJECT_ID：這項要求的專案 ID。
    • ZONE：這個例項的區域。
    • FILE_PATH：您要在本機工作站上儲存執行個體設定檔的輸出路徑。

  2. 使用文字編輯器修改匯出的執行個體設定檔中的一或多個屬性。如要瞭解可更新的屬性，請參閱本文件中的可更新屬性清單。舉例來說，如要變更執行個體的機器類型，請變更 machineType 屬性：

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

    更改下列內容：

    • PROJECT_ID：這項要求的專案 ID。
    • ZONE：這個例項的區域。
    • MACHINE_TYPE：執行個體的機器類型，例如 n1-standard-2。

  3. 使用 instances update-from-file 指令，針對目標執行個體執行測試更新。指定 --most-disruptive-allowed-action=NO_EFFECT 標記。回應會指出哪些屬性設定錯誤，並指出套用更新時是否需要 RESTART 或 REFRESH 動作。

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

    更改下列內容：

    • INSTANCE_NAME：要匯出的執行個體名稱。
    • PROJECT_ID：這項要求的專案 ID。
    • ZONE：這個例項的區域。
    • FILE_PATH：本機工作站上經過修改的執行個體設定檔路徑。

  4. 使用 instances update-from-file 指令更新目標執行個體。如果您要更新的屬性需要重新啟動執行個體，請加入 --most-disruptive-allowed-action=RESTART 標記。如果屬性不需要重新啟動，請指定 --most-disruptive-allowed-action=REFRESH 旗標。如要瞭解哪些資源需要重新啟動，請參閱本文的可更新資源清單。

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

    更改下列內容：

    • INSTANCE_NAME：要匯出的執行個體名稱。
    • PROJECT_ID：這項要求的專案 ID。
    • ZONE：這個例項的區域。
    • FILE_PATH：本機工作站上經過修改的執行個體設定檔路徑。
    • ALLOWED_ACTION：定義更新可能造成的干擾程度。指定 RESTART 可讓執行個體完全重新啟動。只有在修改的屬性不需要重新啟動執行個體時，才指定 REFRESH 來更新執行個體。

如果更新要求有效且可用資源充足，系統就會開始執行例項更新程序。您可以查看稽核記錄，監控這項作業的狀態。如果更新需要重新啟動，且指令允許 RESTART，執行個體就會重新啟動以套用變更。

REST

  1. 使用 Compute Engine API 中的 instances.get 方法匯出現有的執行個體屬性：

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

    更改下列內容：

    • PROJECT_ID：這項要求的專案 ID。
    • ZONE：這個例項的區域。
    • INSTANCE_NAME：要匯出的執行個體名稱。

    這項要求會傳回執行個體資源定義。

  2. 在回應中修改執行個體資源屬性。如要瞭解哪些資源可更新，請參閱本文件中的可更新資源清單。舉例來說，如要變更執行個體的機器類型，請變更 machineType 屬性。您可以變更多個屬性。

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

    更改下列內容：

    • PROJECT_ID：這項要求的專案 ID。
    • ZONE：這個例項的區域。
    • MACHINE_TYPE：執行個體的機器類型，例如 n1-standard-2。

  3. 請使用 Compute Engine API 中的 instances.update 方法，並指定 mostDisruptiveAllowedAction=NO_EFFECT 查詢參數，以便針對目標執行個體執行測試更新。回應會指出設定錯誤的屬性，並指出是否需要執行 RESTART 或 REFRESH 動作才能套用更新。

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

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

    更改下列內容：

    • PROJECT_ID：這項要求的專案 ID。
    • ZONE：這個例項的區域。
    • INSTANCE_NAME：要匯出的執行個體名稱。

  4. 使用 Compute Engine API 中的 instances.update 方法更新目標執行個體。如果您要更新需要重新啟動執行個體的屬性，請加入 mostDisruptiveAllowedAction=RESTART 查詢參數，表示可在更新期間重新啟動執行個體。如果屬性不需要重新啟動，請指定 mostDisruptiveAllowedAction=REFRESH 查詢參數。如要瞭解哪些屬性需要重新啟動，請參閱本文中的可更新的屬性清單。請附上您修改的執行個體資源完整主體。在以下範例中，主體會將機器類型變更為 n1-standard-2：

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

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

    更改下列內容：

    • PROJECT_ID：這項要求的專案 ID。
    • ZONE：這個例項的區域。
    • INSTANCE_NAME：要匯出的執行個體名稱。
    • ALLOWED_ACTION：定義更新可能造成的干擾程度。指定 RESTART 可讓執行個體完全重新啟動。只有在修改的屬性不需要重新啟動執行個體時，才指定 REFRESH 來更新執行個體。

如果更新要求有效且可用資源充足，系統就會開始執行例項更新程序。您可以查看稽核記錄，監控這項作業的狀態。如果更新需要重新啟動，且指令允許 RESTART，執行個體就會重新啟動以套用變更。

後續步驟