Google Cloud CLI または Compute Engine API から単一のリクエストを使用して、複数のインスタンス プロパティを更新できます。また、必要に応じてインスタンスを再起動することもできます。update メソッドは、更新されたインスタンス プロパティを検証するロジックを処理し、更新を正常に完了するために必要なリソースが使用可能であることを確認します。リクエストに無効なプロパティが含まれているか、リクエストされたリソースが利用できない場合、リクエストはエラーを返し、インスタンスは変更されません。これにより、インスタンスを部分的な更新から保護します。また、インスタンスの停止を防ぎ、再起動に必要なリソースにアクセスできるようにします。
始める前に
-
まだ設定していない場合は、認証を設定します。認証とは、Google Cloud サービスと API にアクセスするために ID を確認するプロセスです。ローカル開発環境からコードまたはサンプルを実行するには、次のように Compute Engine に対する認証を行います。
このページのサンプルをどのように使うかに応じて、タブを選択してください。
コンソール
Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- デフォルトのリージョンとゾーンを設定します。
REST
このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
-
制限事項
- gcloud CLI または Compute Engine API を使用したインスタンス更新リクエストは、
PATCH
セマンティクスをサポートしていません。更新リクエストのインスタンス リソースには、インスタンスのすべてのプロパティを含める必要があります。更新リクエストでインスタンス構成に含まれていないプロパティは、インスタンスから削除されます。 - 特定のプロパティのリストのみ更新できます。
- インスタンスを単一テナンシーに変更することはできません。その逆もできません。
- ある予約から別の予約にインスタンスを変更することはできますが、更新プロセスでインスタンスの接続または切断を行うことはできません。
- インスタンスにローカル SSD が接続されている場合、インスタンスの再起動を必要とするプロパティは更新できません。インスタンスを削除して再作成する必要があります。VM を削除する前に、重要なデータをローカル SSD から永続ディスクまたは別の VM への移行を確実に行ってください。
- ベータ版の Compute Engine API でのみ利用可能なリソースをインスタンスで使用する場合は、正しいバージョンの
instances.update
メソッドを使用して、そのプロパティを更新する必要があります。たとえば、ベータ版の Compute Engine API を使用してインスタンスを作成し、ベータ版 API のみが認識できるリソースを使用してインスタンスを構成する場合は、ベータ版のinstances.update
メソッドも使用して、これらのリソースを更新する必要があります。instances.update
メソッドの v1 バージョンは、インスタンスが使用しているベータ版リソースを認識しないため、これらのベータ版リソースは更新処理中にインスタンス構成から削除されます。これは、アルファ版 API のリソースでも同様です。
権限
インスタンスを更新するには、compute.instances.update
権限が必要です。この権限は、既存のいくつかの Identity and Access Management(IAM)のロールに含まれています。また、インスタンスで変更するリソースの使用権限も必要です。たとえば、インスタンスにディスクを追加するには、次の権限が必要です。
- 更新するインスタンスに対する
compute.instances.update
権限。 - 既存のディスクに対する
compute.disks.use
権限、または新しいディスクを作成するプロジェクトに対するcompute.disks.create
権限。
ベスト プラクティス
インスタンスの更新インターフェースが最適に機能するように、次のベスト プラクティスを使用してください。
- 可能であれば、インスタンスの作成、設定、更新には、同じバージョンの Compute Engine API を使用してください。これにより、1 つの API バージョンでのみ使用可能なインスタンス リソースを更新または変更できるようになります。
instances.update
メソッドでマネージド インスタンス グループ(MIG)のインスタンスを更新することも可能ですが、グループのインスタンス テンプレートを変更し、更新されたテンプレートを MIG にロールアウトすることをおすすめします。
更新できるプロパティ
update メソッドですべてのインスタンス プロパティを変更できるわけではありません。一部のプロパティではインスタンスの再起動が必要になります。インスタンスが誤って再起動しないようにするには、インスタンスで許可するアクションをリクエストで定義する必要があります。リクエストでは、次のいずれかのアクションを指定できます。
NO_EFFECT
: リクエストが有効で、リソースが使用可能であるかどうかを確認します。ただし、更新は行いません。これは、実際の更新を始める前にコマンドをテストする場合に使用します。REFRESH
: 変更するインスタンス プロパティでインスタンスの再起動が不要な場合にのみ、更新リクエストを実行します。リクエストが有効であっても再起動が必要な場合、リクエストはINFEASIBLE
エラーを返します。RESTART
: 更新でインスタンスの再起動が必要な場合、インスタンスを再起動します。
更新で RESTART
が必要なプロパティ:
reservationAffinity
disks
- ブートディスクdisks.deviceName
- すべてのディスク
displayDevice
enableNestedVirtualization
guestAccelerators
machineType
minCpuPlatform
networkPerformanceConfig
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
メソッドを使用し、most_disruptive_allowed_action=NO_EFFECT
を指定してターゲット インスタンスの更新をテストします。レスポンスで、誤った構成のプロパティが返されます。更新を適用するためにRESTART
またはREFRESH
アクションが必要かどうかも示されます。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", ⋮ }
次のように置き換えます。
PROJECT_ID
: このリクエストのプロジェクト ID。ZONE
: このインスタンスのゾーン。INSTANCE_NAME
: エクスポートするインスタンスの名前。
Compute Engine API の
instances.update
メソッドを使用して、ターゲット インスタンスを更新します。インスタンスの再起動が必要なプロパティを更新する場合は、?most_disruptive_allowed_action=RESTART
クエリ パラメータを指定して、更新中にインスタンスを再起動できることを示します。プロパティで再起動が不要な場合は、?most_disruptive_allowed_action=REFRESH
クエリ パラメータを指定します。再起動が必要なプロパティについては、更新可能なプロパティ リストをご覧ください。変更したインスタンス リソースの本文全体を含めます。次の例では、本文でマシンタイプを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", ⋮ }
次のように置き換えます。
PROJECT_ID
: このリクエストのプロジェクト ID。ZONE
: このインスタンスのゾーン。INSTANCE_NAME
: エクスポートするインスタンスの名前。ALLOWED_ACTION
: 更新で許容する中断方法を定義します。インスタンスの完全な再起動を許可するには、RESTART
を指定します。プロパティの変更でインスタンスの再起動が不要な場合にのみインスタンスを更新するには、REFRESH
を指定します。
更新リクエストが有効で、必要なリソースが利用可能である場合、インスタンスの更新プロセスが開始します。監査ログを表示すると、このオペレーションのステータスをモニタリングできます。更新で再起動が必要とされ、コマンドで RESTART
が許可されている場合、インスタンスを再起動して変更を適用します。