すべてのインスタンス構成でインスタンステンプレートプロパティをオーバーライドする

このページでは、すべてのインスタンス構成を使用して、すべての仮想マシン（VM）インスタンスのラベルとメタデータのプロパティを設定する方法について説明します。このとき、新しいインスタンステンプレートを作成せずに、マネージドインスタンスグループ（MIG）を作成します。

引き続きインスタンステンプレートを使用して、MIG でインスタンスプロパティを設定することはできます。ただし、次のような一部のシナリオでは、MIG のすべてのインスタンス構成を使用するほうが簡単です。

毎回新しいテンプレートを作成するオーバーヘッドなしに、インスタンスのメタデータまたはラベルを頻繁に更新する必要がある場合。インスタンステンプレートは変更不可です。つまり、作成後に変更することはできません。
1 つのインスタンステンプレートに基づいて複数の MIG が必要であるものの、MIG ごとにラベルまたはメタデータを構成する必要がある場合。たとえば、1 つのアプリを所有していて、開発、テスト、製品のそれぞれで異なる環境をサポートする場合などです。環境ごとに異なるすべてのインスタンス構成を使用して異なるメタデータを設定すると、単一のインスタンステンプレートを作成してすべての環境で再利用できます。
インフラストラクチャとイメージを担当するチームと、構成が必要なアプリを実行する別のチームがある場合。インフラストラクチャとイメージを担当するチームがインスタンステンプレートを使ってインフラストラクチャをプロビジョニングし、アプリを実行するチームがすべてのインスタンス構成を使ってアプリの構成を管理できます。
VM 上で動いているエージェントを、メタデータを使用して構成したいと考えており、加えて、グループのインスタンステンプレートが変更されても、VM エージェントの構成が維持されるようにしたい場合。インスタンステンプレートを使用してアプリのバージョンを制御し、すべてのインスタンス構成を使用して VM エージェントを構成します。

MIG のインスタンステンプレートとすべてのインスタンス構成の両方を使用して同じプロパティを設定した場合、MIG はすべてのインスタンスの構成の値を優先します。たとえば、 enable-guest-attributes のメタデータが MIG のインスタンステンプレートで FALSE に設定され、MIG のすべてのインスタンス構成で TRUE に設定されると、Compute Engine は TRUE をグループのすべてのインスタンスに適用します。これにより、すべてのインスタンス構成を使用して、インスタンステンプレートで定義されているプロパティをオーバーライドできます。

始める前に

このガイドの API の例を使用する場合は、API アクセスを設定します。
このガイドのコマンドラインの例を使用する場合は、Google Cloud CLI をインストールします。
マネージドインスタンスグループを作成します。

制限事項

次のインスタンステンプレートのプロパティは、すべてのインスタンス構成でのみオーバーライドできます。
- メタデータ
- ラベル
すべてのインスタンス構成でカナリア更新はできません。グループに構成を適用すると、Compute Engine は、すべての新しいインスタンスと、更新ポリシーに基づいて既存のインスタンスにプロパティを適用します。更新する既存のインスタンスをコントロールするには、選択更新を使用します。
MIG でステートフル構成を使用する場合、インスタンスごとの構成とグループのすべてのインスタンス構成で同じプロパティを同時に設定することはできません。

すべてのインスタンス構成のプロパティを設定する

gcloud CLI または Compute Engine API を使用して、MIG のすべてのインスタンス構成を作成および更新します。

gcloud

すべてのインスタンス構成を追加または更新するには、all-instances-config update コマンドを使用します。

gcloud beta compute instance-groups managed all-instances-config update INSTANCE_GROUP_NAME \
    --metadata=KEY1=VALUE1,KEY2=VALUE2 \
    --labels=KEY3=VALUE3,KEY4=VALUE4

次のように置き換えます。

INSTANCE_GROUP_NAME: MIG の名前。
KEYS と VALUES: ラベルまたはメタデータの Key-Value ペア。キーが存在しない場合、更新コマンドによって追加されます。既存のキーについては、値が更新されます。

更新した構成を、MIG 内の既存の VM に適用してください。

API

すべてのインスタンス構成を追加または更新するには、ゾーンまたはリージョンの MIG で PATCH リクエストを作成します。

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

{
  "allInstancesConfig": {
    "properties": {
      "metadata": {
        "KEY1": "VALUE1",
        ...
      },
      "labels": {
        "KEY2": "VALUE2",
        ...
      },
    }
  }
}

次のように置き換えます。

PROJECT_ID: MIG が存在するプロジェクト。
REGION: MIG が配置されているリージョン。ゾーン MIG の場合は、regions/REGION を zones/ZONE に置き換えます。
INSTANCE_GROUP_NAME: MIG の名前。
KEYS と VALUES: ラベルまたはメタデータの Key-Value ペア。キーが存在しない場合は、リクエストによって追加されます。既存のキーの場合、その値が更新されます。

更新した構成を、MIG 内の既存の VM に適用してください。

既存の VM にすべてのインスタンス構成を適用する

MIG で VM に指定した VM 構成は、グループに追加される新しい VM に自動的に適用されます。

次のいずれかの方法で、更新された VM 構成（更新されたすべてのインスタンス構成を含む）をグループ内の既存の VM に適用します。

自動（先行型）: MIG でグループ内のすべての既存の VM またはそのサブセットに新しい構成を自動的に適用する場合は、この方法を使用します。VM の実行を中断するレベルは、構成した更新ポリシーによって異なります。この方法を使用すると、新しいインスタンステンプレートをカナリア更新できます。この方法を使用するには、MIG の更新タイプを「先行型」に設定します。
選択型（追従型）: 更新を手動で適用する場合、またはグループ内の既存のすべての VM を一度に更新する場合は、この方法を使用します。一部またはすべての VM を最新の構成に更新します。この方法を使用するには、MIG の更新タイプを「追従型」に設定します。
VM の再作成: MIG で VM を再作成すると、MIG はその VM にまだ適用されていない更新された構成を適用します。詳細については、MIG 内の VM の再作成をご覧ください。

自動（先行型）

変更を行うたびに、更新されたすべてのインスタンス構成を既存のすべての VM に自動的に適用するには、グループの更新ポリシータイプを「先行型」に設定します。詳細については、自動（先行型）更新タイプをご覧ください。

オプションの maxUnavailable、MaxSurge、minReadySec 設定を使用することで、構成の先行型ロールアウトの速度を制御できます。

先行型の更新は、一度設定するだけで使用できます。その後、MIG は今後のすべての VM 構成の変更（つまり、グループのすべてのインスタンス構成、インスタンステンプレート、インスタンスごとの構成の変更）を、グループの更新ポリシーの設定に従ってグループ内のすべての VM に自動的に適用します。

構成の更新を自動的に適用するには、gcloud CLI または Compute Engine API を使用します。

gcloud

ベータ版の update コマンドを使用すると、自動（先行型）での更新を構成できます。

gcloud beta compute instance-groups managed update INSTANCE_GROUP_NAME \
    --update-policy-type=proactive \
    --update-policy-max-unavailable=MAX_UNAVAILABLE \
    --update-policy-max-surge=MAX_SURGE \
    --update-policy-min-ready=MIN_READY \
    --update-policy-minimal-action=MINIMAL_ACTION \
    --update-policy-replacement-method=REPLACEMENT_METHOD

次のように置き換えます。

INSTANCE_GROUP_NAME: MIG の名前。
MAX_UNAVAILABLE（省略可）: 更新中に利用できなくなるインスタンスの最大数。たとえば、update-minimal-action フラグを restart に設定すると、このフラグは一度に再起動される VM の数を制限します。固定数（5 など）か、マネージドインスタンスグループのサイズの割合（10% など）を指定できます。
MAX_SURGE（省略可）: 更新中に作成できる追加のインスタンスの最大数。固定数（5 など）か、マネージドインスタンスグループのサイズの割合（10% など）を指定できます。
MIN_READY（省略可）: 再起動または置換された VM が使用可能と見なされるまでの最小時間。たとえば、10 秒間は 10s です。時刻の形式については、gcloud topic datetimes をご覧ください。
MINIMAL_ACTION（省略可）: 構成の更新中に各インスタンスで実行するアクション。
- refresh: 実行中のインスタンスを再起動せずに新しい構成を適用します。
- restart: 更新中に VM を再起動します。これは、アプリが再起動中にのみメタデータを読み取る場合に便利です。
- replace: VM を削除し、新しい構成を適用する新しい VM を作成します。
REPLACEMENT_METHOD（省略可）: インスタンスの置換に使用するアクションを指定します。
- recreate: 古いインスタンスが削除されるのを待ってから、古いインスタンスと同じ名前の新しいインスタンスを作成します。
- substitute: 古いインスタンスを削除しながら、新しい名前でインスタンスを作成します。

API

自動（先行型）での更新を構成するには、ゾーンまたはリージョンの MIG に対して PATCH リクエストを行います。

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

{
  "updatePolicy": {
    "type": "PROACTIVE",
    "maxUnavailable": {
      "percent": MAX_UNAVAILABLE
    },
    "maxSurge": {
      "percent": MAX_SURGE
    },
    "minimalAction": MINIMAL_ACTION,
    "replacementMethod": REPLACEMENT_METHOD
  }
}

次のように置き換えます。

PROJECT_ID: MIG が存在するプロジェクト。
REGION: MIG が配置されているリージョン。ゾーン MIG の場合は、regions/REGION を zones/ZONE に置き換えます。
INSTANCE_GROUP_NAME: MIG の名前。
MAX_UNAVAILABLE（省略可）: 更新中に利用できなくなるインスタンスの最大数。たとえば、update-minimal-action フラグを RESTART に設定すると、このフラグは一度に再起動される VM の数を制限します。これは割合（たとえば、80% には "percent": 80 を指定）または固定数を指定できます。固定数を指定するには、"percent": MAX_UNAVAILABLE を "fixed": MAX_UNAVAILABLE に置き換えます。
MAX_SURGE（省略可）: 更新中に作成できる追加のインスタンスの最大数。割合または固定数を指定できます。
MINIMAL_ACTION（省略可）: 構成の更新中に各インスタンスで実行するアクション。
- REFRESH: 実行中のインスタンスを再起動せずに新しい構成を適用します。
- RESTART: 更新中に VM を再起動します。これは、アプリが再起動中にのみメタデータを読み取る場合に便利です。
- REPLACE: VM を削除し、新しい構成を適用する新しい VM を作成します。
REPLACEMENT_METHOD（省略可）: インスタンスの置換に使用するアクションを指定します。
- RECREATE: 古いインスタンスが削除されるのを待ってから、古いインスタンスと同じ名前の新しいインスタンスを作成します。
- SUBSTITUTE: 古いインスタンスを削除しながら、新しい名前でインスタンスを作成します。

オプションのフラグを省略すると、グループはグループの更新ポリシーの値を使用します。gcloud CLI または Compute Engine API を使用して更新ポリシーを確認できます。

選択型（追従型）

新しい構成を適用するタイミングと VM を制御するには、グループの更新ポリシータイプを「追従型」に設定します。詳細については、選択型（追従型）更新タイプをご覧ください。

構成の更新を選択して適用する場合、グループのすべてのインスタンス構成、インスタンステンプレート、インスタンスごとの構成に対する変更は、既存の VM に自動的には適用されません。既存の VM を更新するには、更新された構成を明示的に既存の VM に適用する必要があります。

MIG で VM 構成の更新を選択的に VM に適用するには、gcloud CLI または Compute Engine API を使用します。

gcloud

ベータ版の update コマンドを使用すると、選択型（追従型）更新を構成できます。

gcloud beta compute instance-groups managed update INSTANCE_GROUP_NAME \
    --update-policy-type=opportunistic

グループの更新タイプを opportunistic に設定した場合、既存の VM に新しい構成を適用する場合は、更新を開始する必要があります。

特定の VM に構成を適用する

選択したインスタンスを更新するには、次のコマンドを使用します。

gcloud compute instance-groups managed update-instances INSTANCE_GROUP_NAME \
    --instances INSTANCE_NAMES \
    --minimal-action=MINIMAL_ACTION \
    --most-disruptive-allowed-action=MOST_DISRUPTIVE_ALLOWED_ACTION

すべての VM に構成を適用する

既存のすべてのインスタンスを更新するには、次のコマンドを使用します。

gcloud compute instance-groups managed update-instances INSTANCE_GROUP_NAME \
    --all-instances \
    --minimal-action=MINIMAL_ACTION \
    --most-disruptive-allowed-action=MOST_DISRUPTIVE_ALLOWED_ACTION

次のように置き換えます。

INSTANCE_GROUP_NAME: MIG の名前。
INSTANCE_NAMES: テンプレートを適用するインスタンスのリスト
MINIMAL_ACTION（省略可）: 構成の更新中に各インスタンスで実行するアクション。
- refresh（デフォルト）: 実行中のインスタンスを再起動せずに新しい構成を適用します。
- restart: 更新中に VM を再起動します。これは、アプリが再起動中にのみメタデータを読み取る場合に便利です。
- replace: VM を削除し、新しい構成を適用する新しい VM を作成します。
MOST_DISRUPTIVE_ALLOWED_ACTION（省略可）: 各インスタンスに対して、最大でこの操作を行います。構成の更新で、ここで指定したアクションよりも大がかりなアクションが必要な場合、更新は失敗し、変更は行われません。
- none: アクションなし
- refresh: 可能であれば、インスタンスを停止せずに新しい構成を適用します。たとえば、メタデータまたは追加ディスクにのみ影響する変更を適用するには、refresh を使用します。
- restart: 可能であれば、インスタンスを置き換えずに新しい構成を適用します。たとえば、マシンタイプを変更するには、インスタンスを停止して再起動するだけで十分です。
- replace: --replacement-method フラグに従って古いインスタンスを置き換えます。

API

選択型（追従型）更新を構成するには、ゾーンまたはリージョンの MIG に対して PATCH リクエストを行います。

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

{
  "updatePolicy": {
    "type": "OPPORTUNISTIC"
}

グループの更新タイプを OPPORTUNISTIC に設定した場合、既存の VM に新しい構成を適用する場合は、更新を開始する必要があります。

特定の VM に構成を適用する

特定のインスタンスを更新するには、次のリクエストを使用します。

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/applyUpdatesToInstances

{
  "instances": [
    "zones/ZONE/instances/INSTANCE_NAME_1",
    "zones/ZONE/instances/INSTANCE_NAME_2"
  ],
  "minimalAction": MINIMAL_ACTION,
  "mostDisruptiveAllowedAction": MOST_DISRUPTIVE_ALLOWED_ACTION
}

すべての VM に構成を適用する

既存のインスタンスをすべて更新するには、次のリクエストを使用します。

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/applyUpdatesToInstances

{
  "allInstances": true,
  "minimalAction": MINIMAL_ACTION,
  "mostDisruptiveAllowedAction": MOST_DISRUPTIVE_ALLOWED_ACTION
}

次のように置き換えます。

PROJECT_ID: MIG が存在するプロジェクト。
REGION: MIG が配置されているリージョン。ゾーン MIG の場合は、regions/REGION を zones/ZONE に置き換えます。
INSTANCE_GROUP_NAME: MIG の名前。
MINIMAL_ACTION（省略可）: 構成の更新中に各インスタンスで実行するアクション。
- REFRESH: 実行中のインスタンスを再起動せずに新しい構成を適用します。
- RESTART: 更新中に VM を再起動します。これは、アプリが再起動中にのみメタデータを読み取る場合に便利です。
- REPLACE: VM を削除し、新しい構成を適用する新しい VM を作成します。
MOST_DISRUPTIVE_ALLOWED_ACTION（省略可）: 各インスタンスに対して、最大でこの操作を行います。構成の更新で、ここで指定したアクションよりも大がかりなアクションが必要な場合、更新は失敗し、変更は行われません。
- NONE: アクションなし
- REFRESH: 可能であれば、インスタンスを停止せずに新しい構成を適用します。たとえば、メタデータまたは追加ディスクにのみ影響する変更を適用するには、REFRESH を使用します。
- RESTART: 可能であれば、インスタンスを置き換えずに新しい構成を適用します。たとえば、マシンタイプを変更するには、インスタンスを停止して再起動するだけで十分です。
- REPLACE: グループの updatePolicy.replacementMethod フィールドに従って古いインスタンスを置き換えます。

更新されたすべてのインスタンス構成が適用されているかどうかを確認する

gcloud CLI または Compute Engine API を使用して、最新のすべてのインスタンス構成がグループ内のすべての VM に適用されているかどうかを確認できます。

gcloud

ベータ版の describe コマンドを使用し、--format フラグを指定して status.allInstancesConfig.effective 値を検索します。

gcloud beta compute instance-groups managed describe INSTANCE_GROUP_NAME \
    --format="(status.allInstancesConfig)"

出力例:

status:
  allInstancesConfig:
    currentRevision: 2022-12-02T10:30:15.012345Z
    effective: true

effective 値が true に設定されている場合、すべての VM には最新の構成が適用されます。currentRevision 値は、グループのすべてのインスタンス構成に加えられた最新の変更のタイムスタンプを示します。

effective 値が false に設定されている場合、最新の構成はまだすべての VM に適用されていません。

各 VM のステータスを確認するには、MIG のすべての VM を一覧表示するまたは、ベータ版　describe-instance コマンドで各 VM を個別に確認します。

gcloud beta compute instance-groups managed describe-instance INSTANCE_GROUP_NAME \
    --instance INSTANCE_NAME

出力例:

allInstancesConfig:
  revision: 2022-12-02T10:30:15.012345Z
currentAction: NONE
id: '8393021473297481188'
instance: .../projects/PROJECT/zones/ZONE/instances/INSTANCE_NAME
instanceStatus: RUNNING
name: INSTANCE_NAME
version:
  instanceTemplate: .../projects/PROJECT/global/instanceTemplates/INSTANCE_TEMPLATE

最新の構成が適用された VM を確認するには、各 VM の revision タイムスタンプを MIG の currentRevision タイムスタンプと比較します。

API

ゾーンまたはリージョンの MIG に対して GET リクエストを行い、status.allInstancesConfig.effective フラグの値を確認します。

GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

レスポンスの例:

{
  ...
  "status": {
    "isStable": "true",
    "versionTarget": {
      "isReached": "true"
    },
    "allInstancesConfig": {
      "currentRevision": "2022-12-02T10:30:15.012345Z",
      "effective": "true"
    },
  ...
  },
  ...
}

effective フィールドが true に設定されている場合、すべての VM に最新の構成が適用されます。currentRevision フィールドは、グループのすべてのインスタンス構成に加えられた最新の変更のタイムスタンプを示します。

effective フィールドが false に設定されている場合、最新の構成はまだすべての VM に適用されていません。

各インスタンスのステータスを確認するには、ゾーンまたはリージョンの MIG のマネージドインスタンスを一覧表示します。

GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/listManagedInstances

出力例:

{
  "managedInstances": [
    ...
    {
      "instance": ".../zones/ZONE/instances/INSTANCE_NAME",
      "instanceStatus": "RUNNING",
      "currentAction": "NONE",
      "allInstancesConfig": {
        "revision": "2022-12-02T10:30:15.012345Z"
      },
      "version": {
        "name": "V1",
        "instanceTemplate": ".../projects/.../instanceTemplates/INSTANCE_TEMPLATE"
      }
    },
    {
      ...
    }
  ]
}

最新の構成が適用された VM を確認するには、各 VM の revision タイムスタンプを MIG の currentRevision タイムスタンプと比較します。

すべてのインスタンス構成のプロパティを一覧表示する

すべてのインスタンス構成は MIG の構成の一部です。MIG の構成を確認するには、gcloud CLI または Compute Engine API を使用します。

gcloud

describe コマンドを使用し、--format フラグを指定して、グループのすべてのインスタンス構成の値を表示します。

gcloud beta compute instance-groups managed describe INSTANCE_GROUP_NAME \
    --format="(allInstancesConfig)"

グループのすべてのインスタンス構成が存在する場合は、このコマンドで返されます。

API

ゾーンまたはリージョンの MIG で GET リクエストを行い、allInstancesConfig フィールドを探します。

GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

allInstancesConfig フィールドが設定されていない場合、グループにすべてのインスタンス構成はありません。

すべてのインスタンス構成からプロパティを削除する

MIG のすべてのインスタンス構成からプロパティを削除し、MIG のインスタンステンプレートには同じプロパティが存在する場合、MIG の VM は、最新の構成が MIG 内の VM に適用されると、そのプロパティをインスタンステンプレートから再度継承します。最新の構成を既存の VM に適用する方法については、すべてのインスタンス構成を既存の VM に適用するをご覧ください。

すべてのインスタンス構成からプロパティを削除するには、gcloud CLI または Compute Engine API を使用します。

gcloud

プロパティを削除するには、ベータ版の all-instances-configuration delete コマンドを使用し、削除するプロパティのキーを 1 つ以上指定します。

gcloud beta compute instance-groups managed all-instances-config delete INSTANCE_GROUP_NAME \
    --metadata=KEY1[, KEY1]\
    --labels=KEY1[, KEY1]

更新した構成を、MIG 内の既存の VM に適用してください。

API

プロパティを削除するには、ゾーンまたはリージョンの MIG で PATCH リクエストを行い、null 値を削除する予定の各プロパティに対するキーに指定します。

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME
{
  "allInstancesConfig": {
    "properties": {
      "metadata": {
        "KEY1": null,
        ...
      },
      "labels": {
        "KEY2": null,
        ...
      }
    }
  }
}

更新した構成を、MIG 内の既存の VM に適用してください。

次のステップ

更新された構成を MIG 内の既存の VM に自動的に適用する方法を確認する。
MIG 内の既存の VM に構成の更新を選択的に適用する方法を確認する。
MIG とその VM に関する情報を表示する。

すべてのインスタンス構成でインスタンス テンプレート プロパティをオーバーライドする

始める前に

制限事項

すべてのインスタンス構成のプロパティを設定する

gcloud

API

既存の VM にすべてのインスタンス構成を適用する

自動（先行型）

gcloud

API

選択型（追従型）

gcloud

API

更新されたすべてのインスタンス構成が適用されているかどうかを確認する

gcloud

API

すべてのインスタンス構成のプロパティを一覧表示する

gcloud

API

すべてのインスタンス構成からプロパティを削除する

gcloud

API

次のステップ

すべてのインスタンス構成でインスタンステンプレートプロパティをオーバーライドする