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

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

インスタンスから Dynamic Network Interface を追加または削除するには（プレビュー）、インスタンスのプロパティを更新する代わりに、次の操作を行います。

始める前に

  • まだ設定していない場合は、認証を設定します。認証とは、 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. 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.

        3. REST

        このページの REST API サンプルをローカル開発環境で使用するには、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.

        詳細については、 Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

制限事項

  • gcloud CLI または Compute Engine API を使用したインスタンス更新リクエストは、PATCH セマンティクスをサポートしていません。更新リクエストのインスタンス リソースには、インスタンスのすべてのプロパティを含める必要があります。更新リクエストでインスタンス構成に含まれていないプロパティは、インスタンスから削除されます。
  • 特定のプロパティのリストのみ更新できます。
  • インスタンスを単一テナンシーに変更することはできません。その逆もできません。
  • ある予約から別の予約にインスタンスを変更することはできますが、更新プロセスでインスタンスの接続または切断を行うことはできません。
  • インスタンスにローカル SSD ディスクがアタッチされている場合、インスタンスの実行中にインスタンスの再起動を必要とするプロパティは更新できません。インスタンスを削除して再作成するか、インスタンスを停止し、プロパティを更新してから再起動します。
  • ベータ版の 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 権限。

ベスト プラクティス

インスタンスの更新インターフェースが最適に機能するように、次のベスト プラクティスを使用してください。

更新できるプロパティ

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 が許可されている場合、インスタンスを再起動して変更を適用します。

次のステップ