在 MIG 中設定有狀態中繼資料

執行個體中繼資料可用於設定應用程式的屬性，以及透過中繼資料伺服器與應用程式通訊。舉例來說，您可以使用中繼資料設定虛擬機器 (VM) 執行個體的 ID、環境變數、叢集架構相關資訊，或是 VM 負責的資料範圍。

在代管執行個體群組 (MIG) 中設定有狀態的中繼資料，即可確保在代管執行個體自動修復、更新和重新建立事件發生時，保留執行個體專屬的中繼資料。

如要為 MIG 中的 VM 執行個體個別設定有狀態的中繼資料，請在每個執行個體的設定中設定，然後套用設定。您可以在建立執行個體時，或針對現有代管執行個體設定個別執行個體設定。套用依據執行個體設定後，MIG 會將有狀態中繼資料儲存在代管執行個體的「保留的設定狀態」(preservedStateFromConfig) 欄位中。

注意： 如果 MIG 的執行個體範本和個別執行個體設定定義的中繼資料具有相同鍵和不同值，系統會使用個別執行個體設定中的值，套用至相關聯的 VM。

事前準備

• 請參閱使用有狀態 MIG 的時機，以及有狀態 MIG 的運作方式。
• 如果尚未設定驗證，請先完成設定。 驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，請選取下列其中一個選項，向 Compute Engine 進行驗證：

  選取這個頁面上的分頁，瞭解如何使用範例：

  gcloud

  1. 安裝 Google Cloud CLI。 完成後，執行下列指令來初始化 Google Cloud CLI：

     gcloud init

     若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

     注意：如果您已經安裝 gcloud CLI，請務必執行 gcloud components update，確認您安裝的是最新版本。
• 設定預設地區和區域。

Terraform

如要在本機開發環境中使用本頁的 Terraform 範例，請安裝並初始化 gcloud CLI，然後使用您的使用者憑證設定應用程式預設憑證。

1. 安裝 Google Cloud CLI。

2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證：

   gcloud auth application-default login

   如果您使用 Cloud Shell，則不需要執行這項操作。

   如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

詳情請參閱 這篇文章，瞭解如何設定本機開發環境的驗證機制。

REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

限制

具有有狀態設定的 MIG (即有狀態 MIG) 具有下列限制：

• 如果 MIG 具有有狀態的設定，則無法使用自動調度資源功能。
• 如要使用自動輪替更新，請將替換方法設為 RECREATE。
• 對於有狀態的地區 MIG，您必須停用主動式重新分配功能 (將重新分配類型設為 NONE)，才能防止系統自動跨區域重新分配，進而刪除有狀態的執行個體。

• 如果您使用所有執行個體通用的設定來覆寫執行個體範本屬性，就無法在任何個別執行個體設定中指定這些屬性，同時在群組的所有執行個體通用設定中指定這些屬性。

• 永久刪除執行個體 (手動或透過調整大小) 時，MIG 不會保留執行個體的有狀態中繼資料。

在建立執行個體時設定有狀態中繼資料

在 MIG 中手動建立執行個體時，請設定有狀態中繼資料。這項功能有助於將獨立 VM 上的具狀態應用程式遷移至具狀態代管執行個體群組：MIG，以及建立具狀態執行個體。

在 MIG 中手動建立執行個體並提供有狀態的中繼資料時，MIG 會執行下列工作：

1. 使用提供的執行個體名稱，從執行個體範本建立代管執行個體。
2. 使用提供的有狀態中繼資料建立個別執行個體設定，並在執行個體上設定該中繼資料。
3. 將有狀態中繼資料儲存在相關聯受管理執行個體的設定 (preservedStateFromConfig) 中保留的狀態。

gcloud

如要建立具有自訂名稱的受管理執行個體，並在該 VM 上設定有狀態中繼資料，請使用 gcloud compute instance-groups managed create-instance 指令搭配 --stateful-metadata 旗標。

gcloud compute instance-groups managed create-instance NAME \
  --instance INSTANCE_NAME \
  --stateful-metadata KEY=VALUE[,KEY=VALUE,...]

更改下列內容：

• NAME：要在其中建立執行個體的 MIG 名稱
• INSTANCE_NAME：要建立的執行個體名稱
• KEY 和 VALUE：有狀態的中繼資料鍵值組合，可為執行個體個別設定，並加進執行個體範本中定義的中繼資料
  • 您在此設定的鍵值會優先於執行個體範本中的任何衝突鍵值

範例

您需要部署節點叢集 example-cluster，該叢集可以透過 active 或 standby 兩種模式運作。您可以使用中繼資料，為叢集中的每個 VM 個別設定模式，例如：mode:active。您也可以使用 logging 中繼資料鍵，為每個節點設定詳細程度不同的記錄，這個鍵可以設為 basic 或 elaborate。節點上的應用程式會使用執行個體中繼資料中的值進行設定。

如要建立具有詳細記錄的有效節點 node-12，請執行下列指令：

gcloud compute instance-groups managed create-instance example-cluster \
  --instance node-12 \
  --stateful-metadata mode=active,logging=elaborate

這項指令會在 example-cluster MIG 中建立 VM node-12，並為新執行個體設定兩個中繼資料鍵值組合 mode:active 和 logging:elaborate。

Terraform

如要建立具有自訂名稱的代管執行個體，並在該 VM 上設定具狀態中繼資料，請使用 google_compute_per_instance_config 資源。

下列範例使用區域 MIG。如果還沒有可用區 MIG，請建立可用區 MIG，並將 VM 限制在單一可用區。

resource "google_compute_per_instance_config" "default" {
  instance_group_manager = google_compute_instance_group_manager.default.name
  zone                   = google_compute_instance_group_manager.default.zone
  name                   = "node-12"
  preserved_state {
    metadata = {
      mode    = "active"
      logging = "elaborate"
    }
  }
}

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

REST

如要在 MIG 中建立一或多個具有自訂 VM 名稱的代管執行個體，並在這些 VM 上個別設定有狀態中繼資料，請使用下列其中一種方法：

• 如果是區域 MIG，請使用 instanceGroupManagers.createInstances 方法。
• 如果是區域 MIG，請使用 regionInstanceGroupManagers.createInstances 方法。

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/createInstances
{
  "instances": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY" : "VALUE",
          ...
        }
      }
    },
    ...
  ]
}

更改下列內容：

• PROJECT_ID：要求的專案 ID
• ZONE：MIG 所在的可用區 (適用於可用區 MIG)
  • 如果是區域 MIG，請將 zones/ZONE 替換為 regions/REGION，並指定 MIG 的區域
• NAME：要在其中建立執行個體的 MIG 名稱
• INSTANCE_NAME：要建立的執行個體名稱
• KEY 和 VALUE：有狀態的中繼資料鍵值組合，可為執行個體個別設定，並加進執行個體範本中定義的中繼資料
  • 您在此設定的鍵值會優先於執行個體範本中的任何衝突鍵值

範例

您需要部署節點叢集 example-cluster，該叢集可以透過 active 或 standby 兩種模式運作。您可以使用中繼資料，為叢集中的每個 VM 個別設定模式，例如：mode:active。您也可以使用 logging 中繼資料鍵，為每個節點設定詳細程度不同的記錄，這個鍵可以設為 basic 或 elaborate。節點上的應用程式會使用執行個體中繼資料中的值進行設定。

如要建立具有詳細記錄功能的有效節點 node-12，請執行下列方法：

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/createInstances

{
  "instances": [
    {
      "name": "node-12",
      "preservedState" : {
        "metadata": {
          "mode":"active",
          "logging":"elaborate"
        }
      }
    }
  ]
}

這個方法會在 example-cluster MIG 中建立 VM (node-12)，並為新執行個體設定兩個中繼資料鍵值組合 (mode:active 和 logging:elaborate)。

為現有 VM 執行個體個別設定、修改及移除有狀態的中繼資料

如要為 MIG 中的現有執行個體設定、修改或移除具狀態中繼資料，請在相關聯的每個執行個體設定中設定中繼資料，然後更新執行個體來套用設定。

gcloud

如要為 MIG 中的 VM 執行個體個別設定有狀態中繼資料，請在相關的執行個體專屬設定中設定或移除有狀態中繼資料。如果您同時將設定套用至執行個體 (--update-instance)，可以選擇讓執行個體繼續執行、重新啟動或重新建立。如果您未套用設定 (--no-update-instance)，變更不會生效，直到您重新建立或更新執行個體為止。

如果特定執行個體沒有執行個體專屬設定，請使用 gcloud compute instance-groups managed instance-configs create 指令搭配下列其中一個旗標：

gcloud compute instance-groups managed instance-configs create NAME \
  --instance INSTANCE_NAME \
  --stateful-metadata KEY=VALUE[,KEY=VALUE,...] \
  [--no-update-instance | --update-instance] \
  [--instance-update-minimal-action MINIMAL_ACTION]

如果特定執行個體已有執行個體專屬設定，請使用 gcloud compute instance-groups managed instance-configs update 指令，並搭配：

• 設定或修改中繼資料的 --stateful-metadata 旗標，或
• --remove-stateful-metadata 旗標，用於移除執行個體專屬的有狀態中繼資料。

gcloud compute instance-groups managed instance-configs update NAME \
  --instance INSTANCE_NAME \
  [--stateful-metadata KEY=VALUE[,KEY=VALUE,...]] \
  [--remove-stateful-metadata KEY[,KEY,...]] \
  [--no-update-instance | --update-instance] \
  [--instance-update-minimal-action MINIMAL_ACTION]

更改下列內容：

• NAME：代管執行個體群組的名稱。
• INSTANCE_NAME：要設定有狀態中繼資料的執行個體名稱。
• KEY=VALUE：有狀態中繼資料鍵值組合，除了執行個體範本中定義的中繼資料，還可為執行個體個別設定。您在此設定的鍵值會優先於執行個體範本中的任何衝突鍵值。
• KEY：要從個別執行個體設定中移除的執行個體專屬有狀態中繼資料鍵。
  • 如果執行個體範本未定義鍵的值，系統會在套用變更時，從執行個體中完全移除鍵/值組合。
  • 如果執行個體範本定義了鍵的值，則套用變更時，系統會將執行個體範本的值設定在執行個體上。

• MINIMAL_ACTION：將個別執行個體設定更新套用至執行個體時，至少要執行指定動作。只有在使用 --update-instance 旗標時，才能設定 MINIMAL_ACTION。這個值必須是下列其中之一：

  • none：不執行任何動作。
  • refresh：套用可套用的更新，不必停止執行個體。
  • restart：停止執行個體，然後重新啟動。
  • replace：重新建立執行個體。

  如果省略這個值，系統會使用更新作業所需的干擾程度最低動作。

範例

您有一個節點叢集 example-cluster，可透過 active 或 standby 兩種模式運作。您可以使用中繼資料，為叢集中的每個 VM 個別設定模式，例如：mode:active。您也可以使用可設為 basic 或 elaborate 的 logging 中繼資料鍵，為每個節點設定詳細記錄的程度。每個節點上的應用程式都會取用執行個體中繼資料中的值。

執行個體範本會定義 mode:active 和 logging:basic 中繼資料，做為所有執行個體的預設值。您已在叢集中的 node-12 VM 的每個執行個體設定中設定 logging:elaborate。現在，您想將 node-12 切換為待機模式，並將這個 VM 的記錄切換為 basic。

如要將 node-12 執行個體切換為待命狀態，並將記錄功能切換為基本模式，請執行下列指令：

gcloud compute instance-groups managed instance-configs update example-cluster \
  --instance node-12 \
  --stateful-metadata mode=standby \
  --remove-stateful-metadata logging

這項指令會執行以下作業：

1. 在與 example-cluster MIG 中的 VM 相關聯的個別執行個體設定中，設定 mode:standby 中繼資料 node-12。
2. 從 node-12 執行個體的每個執行個體設定中移除 logging:elaborate 中繼資料。
3. 將個別執行個體設定變更套用至 node-12 VM：
   • 根據設定，設定 mode:standby 中繼資料。
   • 從執行個體範本設定 logging:basic 中繼資料，因為 logging 鍵的值不再由每個執行個體的設定定義。
4. 由於省略了 --no-update-instance 旗標，變更預設會立即套用至 VM。
5. 由於省略了 --instance-update-minimal-action 旗標，且系統預設會選擇對更新影響最小的動作，因此 VM 在更新期間會持續執行，在本例中為 refresh。

REST

如要為 MIG 中現有的 VM 執行個體個別設定有狀態的中繼資料，請在相關聯的每個執行個體設定中設定或移除中繼資料。然後更新執行個體，套用設定。

如果指定執行個體尚未有執行個體專屬設定，請使用有狀態中繼資料的 instanceGroupManagers.updatePerInstanceConfigs 方法：

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/updatePerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY": "VALUE",
          ...
        }
      },
      "fingerprint: "FINGERPRINT"
    },
    ...
  ]
}

注意： 您可以使用 updatePerInstanceConfigs 方法更新現有的執行個體設定。在這種情況下，這個方法會以您指定的值，完全取代指定執行個體的設定。使用 patchPerInstanceConfigs 方法更新現有的執行個體設定較為安全，因為修補作業會保留省略的設定，並防止有狀態項目遭到意外刪除，或值重設為預設值。

如果指定執行個體已有個別執行個體適用的設定，請使用 instanceGroupManagers.patchPerInstanceConfigs 方法

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/patchPerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY": "VALUE",
          ...
        }
      },
      "fingerprint: "FINGERPRINT"
    },
    ...
  ]
}

更改下列內容：

• PROJECT_ID：要求的專案 ID。
• ZONE：MIG 所在的可用區 (適用於可用區 MIG)。
  • 如果是區域 MIG，請將 zones/ZONE 替換為 regions/REGION，並指定 MIG 的區域。
• NAME：MIG 的名稱。
• INSTANCE_NAME：要設定具狀態中繼資料的 VM 名稱。
• KEY 和 VALUE：有狀態的中繼資料鍵值組合，可為執行個體個別設定，此外，您也可以在執行個體範本中定義中繼資料。
  • 如果執行個體範本中已存在某個鍵，為該鍵定義的具狀態中繼資料值會覆寫執行個體範本中的值。
  • 執行個體範本中的其他中繼資料項目不受影響，仍可使用。
  • 提供 null 做為值，即可從每個執行個體的設定中移除金鑰。
• FINGERPRINT：(選用)。如果指定設定已存在，則為該設定的指紋。用於樂觀鎖定。

updatePerInstanceConfigs 和 patchPerInstanceConfigs 方法會更新指定的個別執行個體設定，但不會將設定更新套用至相關聯的 VM 執行個體。更新或重新建立執行個體時，系統會將變更套用至 VM。如要將變更套用至 VM，您可以手動套用更新，或在主動或隨機模式下使用 Updater。

範例

您有一個節點叢集 example-cluster，可透過 active 或 standby 兩種模式運作。您可以使用中繼資料，為叢集中的每個 VM 個別設定模式，例如：mode:active。您也可以使用可設為 basic 或 elaborate 的 logging 中繼資料鍵，為每個節點設定詳細記錄的程度。每個節點上的應用程式都會取用執行個體中繼資料中的值。

執行個體範本會定義 mode:active 和 logging:basic 中繼資料，做為所有執行個體的預設值。您已在叢集中的 node-12 VM 的每個執行個體設定中設定 logging:elaborate。現在，您想將 node-12 切換至待機模式，並將這個執行個體的記錄切換至 basic。

如要將 node-12 VM 切換為待命狀態，並將記錄檔切換為基本記錄檔，請使用 patchPerInstanceConfigs 方法修補相關聯的個別執行個體設定：

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/patchPerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "node-12",
      "preservedState" : {
        "metadata": {
          "mode": "standby",
          "logging": null
        }
      }
    }
  ]
}

這個方法會執行下列作業：

1. 在與 VM 相關聯的個別執行個體設定中，於 example-cluster MIG 內設定 mode:standby 中繼資料 node-12。
2. 從每個執行個體的設定中移除 logging:elaborate 中繼資料，因為提供的值為 null。

設定更新尚未套用至 node-12 VM 執行個體。下次重新建立或更新執行個體時，或使用主動自動更新時，系統會套用設定更新。

如要將個別執行個體設定更新套用至 node-12 VM 執行個體，請為該執行個體呼叫 instanceGroupManagers.applyUpdatesToInstances 方法：

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/applyUpdatesToInstances

{
  "instances": ["/zones/us-east1-c/instances/node-12"],
  "minimalAction": "NONE"
}

這個方法會將更新後的個別執行個體設定套用至 node-12 VM：

1. 根據每個執行個體的設定，設定 mode:standby 中繼資料。
2. 從執行個體範本設定 logging:basic 中繼資料，因為 logging 金鑰的值不再由每個執行個體的設定定義。
3. 由於 minimalAction 設為 NONE，因此 VM 會在更新期間持續執行，MIG 也能使用更新所需的最低干擾動作。更新執行個體中繼資料需要 REFRESH 動作，這不會中斷執行中的執行個體。

意見回饋

我們想要瞭解您的用途、難題和有狀態 MIG 的相關意見。請前往以下網址，並與我們的團隊分享您的寶貴意見：[e-mail]。

後續步驟

• 進一步瞭解如何儲存及擷取執行個體中繼資料。
• 為 MIG 中的 VM 設定有狀態永久磁碟。
• 瞭解如何套用、查看及移除有狀態設定。
• 進一步瞭解MIG 和如何使用代管型執行個體。