您可以使用 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
-
安裝 Google Cloud CLI。 安裝完成後,執行下列指令初始化 Google Cloud CLI:
gcloud init
如果您使用外部識別資訊提供者 (IdP),請先 使用聯合身分登入 gcloud CLI。
- 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
更新執行個體屬性
請按照下列步驟更新執行個體:
- 匯出現有執行個體設定屬性。
- 修改執行個體設定的屬性。
- 指定
NO_EFFECT
為干擾程度最高的動作,然後執行測試要求。 回應會指出例項設定中的無效欄位,以及套用變更時需要執行的動作。 - 如果設定可接受,請要求更新執行個體,並指定執行個體更新作業可接受的最大干擾動作。
只有在要求符合下列規定時,系統才會啟動更新程序:
- 要求中的執行個體
fingerprint
屬性,必須與您要更新的執行個體fingerprint
相同。這樣可避免對同一執行個體提出同步更新要求,導致彼此覆寫。 - 更新要求中的屬性必須有效。
- 您要求的資源必須可用。
- 如果要求中的屬性需要重新啟動執行個體,要求就必須將
RESTART
指定為允許的動作。
如果符合需求,系統就會啟動執行個體更新程序。否則,系統不會對現有執行個體或其設定進行任何變更。
您可以使用 gcloud CLI 或 Compute Engine API 啟動更新。
gcloud
使用
instances export
指令匯出現有執行個體屬性:gcloud compute instances export INSTANCE_NAME \ --project PROJECT_ID \ --zone ZONE \ --destination=FILE_PATH
更改下列內容:
INSTANCE_NAME
:要匯出的執行個體名稱。PROJECT_ID
:這項要求的專案 ID。ZONE
:這個執行個體的區域。FILE_PATH
:您要在本機工作站儲存執行個體設定檔的輸出路徑。
使用文字編輯器修改匯出的執行個體設定檔中的一或多個屬性。如要瞭解可更新的屬性,請參閱本文中的可更新屬性清單。 舉例來說,如要變更執行個體的機器類型,請變更
machineType
屬性:... machineType: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE ...
更改下列內容:
使用
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
:本機工作站上修改後執行個體設定檔的路徑。
使用
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
使用 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
:要匯出的執行個體名稱。
這項要求會傳回執行個體資源定義。
在回應中修改執行個體資源屬性。如要瞭解可更新的屬性,請參閱本文中的可更新屬性清單。舉例來說,如要變更執行個體的機器類型,請變更
machineType
屬性。您可以變更多個屬性。{ ... "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE", ... }
更改下列內容:
使用 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
:要匯出的執行個體名稱。
使用 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
,執行個體就會重新啟動以套用變更。後續步驟
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2025-07-29 (世界標準時間)。
-