更新執行個體屬性

---

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

如要從執行個體新增或移除動態網路介面 (搶先版)，請使用下列程序，而非更新執行個體屬性：

• 從執行個體刪除動態 NIC
• 在執行個體中新增動態 NIC

事前準備

• 如果尚未設定驗證，請先完成設定。 「驗證」是指驗證身分的程序，確認您有權存取 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. 安裝 Google Cloud CLI。 安裝完成後，執行下列指令初始化 Google Cloud CLI：

     gcloud init

     如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

     注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。
  2. Set a default region and zone.

  REST

  如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

  安裝 Google Cloud CLI。 安裝完成後，執行下列指令初始化 Google Cloud CLI：

  gcloud init

  如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  詳情請參閱 Google Cloud 驗證說明文件中的「Authenticate for using REST」。

限制

• 透過 gcloud CLI 或 Compute Engine API 提出的執行個體更新要求，不支援 PATCH 語意。更新要求中的例項資源必須包含例項的所有屬性。更新要求中缺少例項設定的屬性，會視為從例項中刪除。
• 你只能更新特定屬性清單。
• 不支援將執行個體變更為單一租戶，或從單一租戶變更為其他租戶。
• 您可以將執行個體從一個預訂項目變更為另一個，但無法使用更新程序將執行個體附加或卸離預訂項目。
• 如果執行個體已連結本機 SSD 磁碟，則執行個體執行時，您無法更新需要重新啟動執行個體的屬性。您可以刪除執行個體並重新建立，也可以停止執行個體、更新屬性，然後重新啟動。
• 如果執行個體使用的資源僅適用於 Beta 版 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。

可更新的屬性

您只能透過更新方法變更特定執行個體屬性。更新部分屬性時，需要重新啟動執行個體。 為避免執行個體意外重新啟動，您的要求必須定義允許對執行個體執行的動作。您的要求可以指定下列其中一項動作：

• 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。
   提示：為避免發生 "ERROR: (gcloud.compute.instances.update-from-file) Cannot parse YAML: [Expected type for field value, found True (type )]" 等錯誤，請在匯出的執行個體設定檔中，為 yes 或 no 的任何標籤值加上引號 (' ')。這表示值為字串，而非布林值。

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，執行個體就會重新啟動以套用變更。

後續步驟

• 檢查執行個體的狀態。
• 瞭解如何在特定區域中預留資源。