建立擴充功能政策，安裝 VM 擴充功能

本文說明如何建立 VM 擴充功能政策，以便在 Compute Engine 虛擬機器 (VM) 叢集上自動安裝及管理擴充功能。定義政策後，您可以確保符合指定條件 (例如 VM 標籤) 的 VM 都會安裝並維護特定擴充功能。

事前準備

執行下列指令，安裝 Beta 版元件：
```
     gcloud components install beta
   
```
查看 VM 擴充功能管理工具的基本概念。
查看 VM 擴充功能管理工具配額。
如果尚未啟用，請在 Google Cloud 專案中啟用 Compute Engine API。
啟用 Compute Engine API
確認 VM 執行客體代理程式 20241209.01 以上版本。
如要查看 VM 擴充功能管理工具事件的偵錯記錄檔，請設定訪客代理程式的記錄設定。
如果尚未設定驗證，請先完成設定。驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，請選取下列其中一個選項，向 Compute Engine 進行驗證：
選取這個頁面上的分頁，瞭解如何使用範例：
控制台

使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，無須設定驗證。
gcloud
1. 安裝 Google Cloud CLI。完成後，執行下列指令來初始化 Google Cloud CLI：
  gcloud init
  若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
  
  注意：如果您已經安裝 gcloud CLI，請務必執行 gcloud components update，確認您安裝的是最新版本。
設定預設地區和區域。

REST

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

安裝 Google Cloud CLI。

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

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

必要的 IAM 角色

如要取得建立擴充功能政策所需的權限，請要求系統管理員授予您「VM 擴充功能政策管理員」(roles/compute.vmExtensionPolicyAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 compute.vmExtensionPolicies.create 權限，可建立擴充功能政策。

您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

如要進一步瞭解 Compute Engine 中的身分與存取權管理角色和權限，請參閱「Compute Engine 角色和權限」。

政策優先順序和衝突解決

如有多項政策適用於同一個 VM，VM 擴充功能管理工具會依據政策優先順序解決衝突。

如果兩項政策對同一項擴充功能有衝突，系統會優先採用優先順序較高的政策。優先順序值介於 0 到 65535 之間，數字越小代表優先順序越高。預設優先順序為 1000。如果多項政策的優先順序相同，VM 擴充功能管理工具會將最近更新的政策套用至 VM。如果較低優先順序的政策仍適用於 VM，刪除政策不會移除擴充功能。

建立全域 VM 擴充功能政策

您可以建立全域 VM 擴充功能政策，根據推出計畫在專案內多個可用區的 VM 上安裝擴充功能。全域 VM 擴充功能政策不會直接套用至 VM，而是會在政策推出時，由 VM 擴充功能管理工具根據推出計畫，在每個可用區中建立政策。這些政策隨後會管理各自區域內 VM 的擴充功能安裝作業。

您可以使用 gcloud 或 globalVmExtensionPolicies.insert 方法建立全域擴充功能政策。

關於推出計畫

全域 VM 擴充功能政策會使用推出計畫，管理不同位置的擴充功能部署作業。您可以採用預先定義的推出計畫，也可以建立自訂推出計畫。

預先定義的推出計畫

slow_rollout：在五天內推出政策。預設的發布計畫為緩慢發布。
fast_rollout：立即將政策發布至所有區域。

自訂推出計畫

您可以使用 rolloutPlans.insert 方法建立自訂推出計畫。舉例來說，下列 JSON 會定義名為 test-rollout-plan 的推出計畫，該計畫以兩個區域為目標：

{
  "name": "test-rollout-plan",
  "waves": [
    {
      "selectors": [
        {
          "locationSelector": {
            "includedLocations": [
              "us-central1-a",
              "us-west1-a"
            ]
          }
        }
      ],
      "validation": {
        "type": "time",
        "timeBasedValidationMetadata": {
          "waitDuration": "0s"
        }
      },
      "orchestrationOptions": {
        "maxConcurrentResourcesPerLocation": "10",
        "maxConcurrentLocations": "10"
      }
    }
  ]
}

然後，您可以在建立全域政策時使用這項自訂推出計畫，如範例 2 所示。

建立全域政策

請使用下列其中一種方法建立全域 VM 擴充功能政策。

gcloud

使用 gcloud beta compute global-vm-extension-policies create 指令建立全域 VM 擴充功能政策：

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR

更改下列內容：

POLICY_NAME：VM 擴充功能政策的名稱。
DESCRIPTION：政策的選填說明。
EXTENSION_NAME_1、EXTENSION_NAME_2：以半形逗號分隔的清單，列出要新增至政策的擴充功能。您必須至少指定一個擴充功能。擴充功能的有效值如下：
- ops-agent
- google-cloud-sap-extension
- google-cloud-workload-extension
EXTENSION_NAME_1=VERSION_1、EXTENSION_NAME_2=VERSION_2：以半形逗號分隔的鍵/值組合清單，其中鍵為擴充功能名稱，值為擴充功能版本。如果未指定擴充功能版本，VM 擴充功能管理工具會使用最新版本，並在推出新版本時自動升級。

注意： 對於 ops-agent，VM 擴充功能管理工具支援安裝 2.58.0 以上版本。google-cloud-sap-extension和 google-cloud-workload-extension 僅支援最新版本。
EXTENSION_NAME_1=CONFIG_FILE_PATH_1、EXTENSION_NAME_2=CONFIG_FILE_PATH_2：以半形逗號分隔的鍵/值配對清單，其中鍵是擴充功能名稱，值是該擴充功能的設定檔路徑。這個檔案位於您執行 gcloud 指令的 VM，而不是安裝擴充功能的 VM。

或者，如要以內嵌字串形式提供設定，請使用 --config 旗標，而非 --config-from-file，例如 EXTENSION_NAME_1="CONFIG_1"。您可以使用 --config-from-file 或 --config，但不能在同一個指令中同時使用兩者。
KEY_1=VALUE_1：以半形逗號分隔的鍵/值組合清單，定義選擇器的納入標籤。VM 必須具備選取器中的所有指定標籤，才能成為目標。如果您多次指定 --inclusion-labels，政策會以符合任何所提供選取器的 VM 為目標 (邏輯 OR)。如果省略這個標記，政策會以專案中所有可用區的所有 VM 為目標。
PRIORITY：定義政策優先順序的整數。數字越大，表示優先順序越高。預設值為 1000。如果多項政策的優先順序相同，系統會將最近更新的政策套用至 VM。
ROLLOUT_PLAN：指定 slow_rollout 或 fast_rollout。如要使用自訂推出計畫，請使用 --rollout-custom-plan 標記，而非 --rollout-predefined-plan，並指定計畫名稱，例如：
```
--rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME
```
更改下列內容：
- PROJECT_NUMBER：定義推出計畫的專案。
- ROLLOUT_PLAN_NAME：您定義的自訂推出計畫名稱。如未指定任何發布計畫旗標，系統會使用 slow_rollout。
ROLLOUT_CONFLICT_BEHAVIOR：指定系統偵測到區域和全域政策之間發生衝突時的行為。可能的值包括：
- "" (空字串)：全域政策不會覆寫名稱相同的衝突區域政策。這是預設行為。
- overwrite：全域政策會覆寫任何同名的區域政策，然後全域政策會管理區域中的政策推出作業。
詳情請參閱 --rollout-conflict-behavior 旗標。

範例 1

下列指令會建立名為 global-test-extension-policy 的政策，為專案 test-project 安裝 ops-agent 擴充功能。--config-from-file 標記會指定包含 Ops Agent YAML 設定的本機檔案路徑，--rollout-predefined-plan 則會指定 slow_rollout 方案。

gcloud beta compute global-vm-extension-policies create global-test-extension-policy \
    --project=test-project \
    --extensions=ops-agent \
    --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
    --rollout-predefined-plan=slow_rollout

示例 2

下列指令會建立名為 global-test-extension-policy-2 的政策，在標籤為 env=prod 的 VM 上，為專案 test-project 安裝 ops-agent 擴充功能。政策優先順序設為 500，而 --config-from-file 標記會指定本機檔案的路徑，其中包含 Ops Agent 的 YAML 設定。--rollout-custom-plan 標記用於指定自訂推出計畫。

 gcloud beta compute global-vm-extension-policies create global-test-extension-policy-2 \
    --project=test-project \
    --extensions=ops-agent \
    --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
    --priority=500 \
    --inclusion-labels=env=prod \
    --rollout-custom-plan=projects/12345678/locations/global/rolloutPlans/test-rollout-plan

REST

如要建立全域 VM 擴充功能政策，請對 globalVmExtensionPolicies.insert 方法發出 POST 要求。

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/vmExtensionPolicies

{
  "name": "POLICY_NAME",
  "description": "DESCRIPTION",
  "extensionPolicies": {
     "EXTENSION_NAME_1": {
       "stringConfig": "EXTENSION_NAME_1_CONFIG",
       "pinnedVersion": "EXTENSION_NAME_1_VERSION"
    },
     "EXTENSION_NAME_2": {
       "stringConfig": "EXTENSION_NAME_2_CONFIG",
       "pinnedVersion": "EXTENSION_NAME_2_VERSION"
    }
  },
  "instanceSelectors": [
    {
      "labelSelector": {
         "inclusionLabels": {
           "KEY_1": "VALUE_1"
         }
      }
    }
  ],
  "priority": "PRIORITY",
  "rolloutOperation": {
    "rolloutInput": {
      "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
      "name": "projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
    }
  }
}

更改下列內容：

PROJECT_ID：您的專案 ID。
POLICY_NAME：VM 擴充功能政策的名稱。
DESCRIPTION：政策的選填說明。
EXTENSION_NAME_1、EXTENSION_NAME_2：要新增至政策的擴充功能名稱。您必須至少指定一個擴充功能。擴充功能的有效值如下：
- ops-agent
- google-cloud-sap-extension
- google-cloud-workload-extension
EXTENSION_NAME_1_CONFIG、EXTENSION_NAME_2_CONFIG：擴充功能的設定，以內嵌字串形式提供。
EXTENSION_NAME_1_VERSION、EXTENSION_NAME_2_VERSION：擴充功能版本。如果未指定擴充功能版本，VM 擴充功能管理工具會使用最新可用版本，並在推出新版本時自動升級。

注意： 對於 ops-agent，VM 擴充功能管理工具支援安裝 2.58.0 以上版本。google-cloud-sap-extension和 google-cloud-workload-extension 僅支援最新版本。
KEY_1：VALUE_1：定義選取器包含標籤的鍵/值組合。VM 必須具備選取器中的所有指定標籤，才能成為目標。如果指定多個 instanceSelectors，政策會以符合任一所提供選取器的 VM 為目標 (邏輯 OR)。如果省略 instanceSelectors，政策會以專案中所有可用區的所有 VM 為目標。
PRIORITY：定義政策優先順序的整數。數字越大，表示優先順序越高。預設值為 1000。如果多項政策的優先順序相同，系統會將最近更新的政策套用至 VM。
ROLLOUT_CONFLICT_BEHAVIOR：指定系統偵測到區域和全域政策之間發生衝突時的行為。可能的值包括：
- "" (空字串)：全域政策不會覆寫名稱相同的衝突區域政策。這是預設行為。
- overwrite：全域政策會覆寫任何同名的區域政策，然後全域政策會管理區域中的政策推出作業。
  
  詳情請參閱 --rollout-conflict-behavior 旗標。
PROJECT_NUMBER：定義自訂推出計畫的專案。
ROLLOUT_PLAN_NAME：您定義的自訂推出計畫名稱。如要使用預先定義的推出計畫，請將 name 欄位替換為 predefinedRolloutPlan，並指定下列其中一個值：
- SLOW_ROLLOUT：在五天內推出政策。如未指定任何計畫，系統會預設採用這個發布計畫。
- FAST_ROLLOUT：立即將政策推出至所有區域。

範例

以下範例會建立名為 global-test-extension-policy 的政策，在標籤為 env=prod 的 VM 上，為專案 12345678 安裝 ops-agent 擴充功能。政策優先順序設為 500，並使用發布計畫 test-rollout-plan。

POST https://compute.googleapis.com/compute/beta/projects/12345678/global/vmExtensionPolicies

{
  "name": "global-test-extension-policy",
  "description": "Test extension policy for Ops Agent",
  "extensionPolicies": {
     "ops-agent": {
       "stringConfig": "logging:
        receivers:
          systemd_logs:
            type: systemd_journald
        service:
          pipelines:
            systemd_pipeline:
              receivers: [systemd_logs]",
       "pinnedVersion": "2.58.0"
        },
  "instanceSelectors": [
    {
      "labelSelector": {
         "inclusionLabels": {
         "env": "prod"
         }
      }
    }
  ],
  "priority": "500",
  "rolloutOperation": {
    "rolloutInput": {
      "name": "projects/12345678/locations/global/rolloutPlans/test-rollout-plan"
    }
  }
}

建立可用區 VM 擴充功能政策

請使用下列任一方法建立區域 VM 擴充功能政策。這項區域政策會定義要在特定區域的哪些 VM 上安裝哪些擴充功能。

控制台

前往 Google Cloud 控制台的「VM extension policies」(VM 擴充功能政策) 頁面。
前往 VM 擴充功能政策
按一下「建立擴充功能政策」。
在「Name」(名稱) 欄位中，輸入政策名稱。
選用：在「Description」(說明) 欄位中輸入政策的說明。
在「優先順序」欄位中，指定優先順序編號，以解決政策之間的衝突。數字越小越優先。預設值為 1000。
在「Zone」(可用區) 清單中，選取要套用這項政策的可用區。
在「擴充功能」部分，按一下「新增擴充功能」，然後針對要安裝在目標 VM 上的每個擴充功能執行下列操作：
1. 從「擴充功能」清單中選取擴充功能。請參閱「支援的擴充功能」。
2. 從「版本」清單中指定擴充功能版本號碼。如要選取最新版本，請留空。
  - Ops Agent 可指定 2.58.0 以上版本。
  - 如果是 SAP 擴充功能和 Compute 擴充功能工作負載，請將欄位留空，選取最新版本。
3. 選用：在「設定檔內容」欄位中，輸入擴充功能的設定參數。
在「Target VM instances」(目標 VM 執行個體) 區段中，選取要套用政策的 VM。如要選取具有特定標籤的 VM，請按一下「新增標籤」，然後新增鍵/值組合。
點選「建立」。

gcloud

如要建立區域 VM 擴充功能政策，並將政策推出至特定可用區的 VM，請使用 gcloud beta compute zone-vm-extension-policies create 指令：

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
    --zone=ZONE \
    --description="DESCRIPTION" \
    --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
    --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
    --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
    --inclusion-labels=KEY_1=VALUE_1 \
    --priority=PRIORITY

更改下列內容：

POLICY_NAME：VM 擴充功能政策的名稱。
ZONE：這項政策適用的可用區。
DESCRIPTION：政策的選填說明。
EXTENSION_NAME_1、EXTENSION_NAME_2：以半形逗號分隔的清單，列出要新增至政策的擴充功能。您必須至少指定一個擴充功能。擴充功能的有效值如下：
- ops-agent
- google-cloud-sap-extension
- google-cloud-workload-extension
EXTENSION_NAME_1=VERSION_1、EXTENSION_NAME_2=VERSION_2：以半形逗號分隔的鍵/值組合清單，其中鍵為擴充功能名稱，值為擴充功能版本。如果未指定擴充功能版本，VM 擴充功能管理工具會使用最新版本，並在推出新版本時自動升級。

注意： 對於 ops-agent，VM 擴充功能管理工具支援安裝 2.58.0 以上版本。google-cloud-sap-extension和 google-cloud-workload-extension 僅支援最新版本。
EXTENSION_NAME_1=CONFIG_FILE_PATH_1、EXTENSION_NAME_2=CONFIG_FILE_PATH_2：以半形逗號分隔的鍵/值配對清單，其中鍵是擴充功能名稱，值是該擴充功能的設定檔路徑。這個路徑位於執行 gcloud 指令的 VM 上，而非安裝擴充功能的 VM。

或者，如要以內嵌字串形式提供設定，請使用 --config 旗標而非 --config-from-file，例如 EXTENSION_NAME_1="CONFIG_1"。您可以使用 --config-from-file 或 --config，但不能在同一個指令中同時使用兩者。
KEY_1=VALUE_1：以半形逗號分隔的鍵/值組合清單，定義選擇器的納入標籤。VM 必須具備選取器中的所有指定標籤，才能成為目標。如果您多次指定 --inclusion-labels，政策會以符合任何所提供選取器的 VM 為目標 (邏輯 OR)。如果省略這個標記，政策會以指定可用區中的所有 VM 為目標。
PRIORITY：介於 0 到 65535 之間的整數，用於定義政策的優先順序。數字越小越優先。預設值為 1000。

如果區域中已有指定名稱的政策，這項指令就會失敗。

範例 1

下列指令會建立名為 test-extension-policy 的政策，在專案 test-project 的可用區 us-central1-f 中安裝 ops-agent 擴充功能。--config-from-file 旗標會指定本機檔案的路徑，該檔案包含 Ops Agent 的 YAML 設定。

gcloud beta compute zone-vm-extension-policies create test-extension-policy  \
    --project=test-project \
    --zone=us-central1-f \
    --extensions=ops-agent \
    --config-from-file=ops-agent="/usr/ops-agent-config.yaml"

示例 2

下列指令會建立名為 test-extension-policy-2 的政策，在可用區 us-central1-f 中為專案 test-project 安裝 ops-agent 擴充功能，適用於標籤為 env=prod 的 VM。政策優先順序設為 500，而 --config-from-file 標記會指定本機檔案的路徑，其中包含 Ops Agent 的 YAML 設定。

 gcloud beta compute zone-vm-extension-policies create test-extension-policy-2  \
    --project=test-project \
    --zone=us-central1-f \
    --extensions=ops-agent \
    --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
    --priority=500 \
    --inclusion-labels=env=prod

REST

如要建立區域 VM 擴充功能政策，請對 zoneVmExtensionPolicies.insert 方法發出 POST 要求。這個方法會定義要安裝的擴充功能，以及特定可用區中的哪些 VM 要安裝這些擴充功能。

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/vmExtensionPolicies

{
  "name": "POLICY_NAME",
  "description": "DESCRIPTION",
  "extensionPolicies": {
     "EXTENSION_NAME_1": {
       "stringConfig": "EXTENSION_NAME_1_CONFIG"
       "pinnedVersion": "EXTENSION_NAME_1_VERSION"
    },
     "EXTENSION_NAME_2": {
       "stringConfig": "EXTENSION_NAME_2_CONFIG"
       "pinnedVersion": "EXTENSION_NAME_2_VERSION"
    },
  "instanceSelectors": [
    {
      "labelSelector": {
         "inclusionLabels": {
         "KEY_1": "VALUE_1"
         }
      }
    }
  ],
  "priority": "PRIORITY"
}
}

更改下列內容：

PROJECT_ID：您的專案 ID。
ZONE：這項政策適用的可用區。
POLICY_NAME：VM 擴充功能政策的名稱。
DESCRIPTION：政策的選填說明。
EXTENSION_NAME_1、EXTENSION_NAME_2：要新增至政策的擴充功能名稱。您必須至少指定一個擴充功能。擴充功能的有效值如下：
- ops-agent
- google-cloud-sap-extension
- google-cloud-workload-extension
EXTENSION_NAME_1_VERSION、EXTENSION_NAME_2_VERSION：擴充功能版本。如果未指定擴充功能版本，VM 擴充功能管理工具會使用最新可用版本，並在推出新版本時自動升級。

注意： 對於 ops-agent，VM 擴充功能管理工具支援安裝 2.58.0 以上版本。google-cloud-sap-extension和 google-cloud-workload-extension 僅支援最新版本。
EXTENSION_NAME_1_CONFIG、EXTENSION_NAME_2_CONFIG：擴充功能的設定，以內嵌字串形式提供。
KEY_1：VALUE_1：定義選取器包含標籤的鍵/值組合。VM 必須具備選取器中的所有指定標籤，才能成為目標。如果指定多個 instanceSelectors，政策會以符合任一所提供選取器的 VM 為目標 (邏輯 OR)。如果省略 instanceSelectors，政策會以指定可用區中的所有 VM 為目標。
PRIORITY：介於 0 到 65535 之間的整數，用於定義政策的優先順序。數字越小越優先。預設值為 1000。

範例

以下範例會建立名為 test-extension-policy 的政策，在 my-project 的 us-central1-f 區域中安裝 ops-agent 擴充功能。

POST https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-f/vmExtensionPolicies

{
  "name": "test-extension-policy",
  "description": "Test extension policy for Ops Agent",
  "extensionPolicies": {
     "ops-agent": {
       "stringConfig": "logging:
        receivers:
          systemd_logs:
            type: systemd_journald
        service:
          pipelines:
            systemd_pipeline:
              receivers: [systemd_logs]",
       "pinnedVersion": "2.58.0"
        },
  "instanceSelectors": [
    {
      "labelSelector": {
         "inclusionLabels": {
         "env": "test"
         }
      }
    }
  ],
  "priority": "500"
}
}

後續步驟

瞭解如何管理 VM 擴充功能。

建立擴充功能政策，安裝 VM 擴充功能 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

控制台

gcloud

REST

必要的 IAM 角色

政策優先順序和衝突解決

建立全域 VM 擴充功能政策

關於推出計畫

建立全域政策

gcloud

REST

建立可用區 VM 擴充功能政策

控制台

gcloud

REST

後續步驟

建立擴充功能政策，安裝 VM 擴充功能