インスタンスプロパティを更新する

Google Cloud CLI または Compute Engine API から単一のリクエストを使用して、複数のインスタンスプロパティを更新できます。また、必要に応じてインスタンスを再起動することもできます。update メソッドは、更新されたインスタンスプロパティを検証するロジックを処理し、更新を正常に完了するために必要なリソースが使用可能であることを確認します。リクエストに無効なプロパティが含まれているか、リクエストされたリソースが利用できない場合、リクエストはエラーを返し、インスタンスは変更されません。これにより、インスタンスを部分的な更新から保護します。また、インスタンスの停止を防ぎ、再起動に必要なリソースにアクセスできるようにします。

始める前に

まだ設定していない場合は、認証を設定します。認証とは、Google Cloud サービスと API にアクセスするために ID を確認するプロセスです。ローカル開発環境からコードまたはサンプルを実行するには、次のように 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. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

制限事項

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 が必要なプロパティ:

disks - ブートディスク
- disks.deviceName - すべてのディスク
displayDevice
enableNestedVirtualization
guestAccelerators
machineType
minCpuPlatform
networkPerformanceConfig
performanceMonitoringUnit
reservationAffinity
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
⋮
```
次のように置き換えます。
- PROJECT_ID: このリクエストのプロジェクト ID。
- ZONE: このインスタンスのゾーン。
- MACHINE_TYPE: インスタンスのマシンタイプ。例: n1-standard-2
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",
  ⋮
}
```
次のように置き換えます。
- PROJECT_ID: このリクエストのプロジェクト ID。
- ZONE: このインスタンスのゾーン。
- MACHINE_TYPE: インスタンスのマシンタイプ。例: n1-standard-2
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 を指定します。

次のステップ

インスタンスのステータスを確認する。
特定のゾーン内のリソースを予約する方法を学習する。

インスタンス プロパティを更新する

始める前に

Console

gcloud

REST

制限事項

権限

ベスト プラクティス

更新できるプロパティ

インスタンス プロパティの更新

gcloud

REST

次のステップ

インスタンスプロパティを更新する

ベストプラクティス

インスタンスプロパティの更新