使用代理程式政策 (Beta 版)

您可以使用 Google Cloud CLI 中的 gcloud beta compute instances ops-agents policies 指令群組或 agent-policy Terraform 模組，建立及管理代理程式政策。代理程式政策會使用 VM 管理員 Compute Engine 中的工具套件，管理 OS 政策，這類政策可自動部署及維護軟體設定，例如 Google Cloud 可觀測性代理程式：作業套件代理程式、舊版 Monitoring 代理程式和舊版 Logging 代理程式。

建立代理程式政策

本節說明如何使用 Google Cloud SDK 管理代理程式政策。如要瞭解如何使用 Terraform，請參閱「Terraform 整合」。

如要使用 Google Cloud CLI 建立代理程式政策，請完成下列步驟：

  1. 如果您尚未安裝 Google Cloud CLI，請先安裝。

    本文所述的服務機器人政策會使用 beta 指令群組。

  2. 如果您尚未安裝 gcloud CLI 的 beta 元件，請先安裝：

    gcloud components install beta

    如要檢查是否已安裝 beta 元件，請執行以下指令：

    gcloud components list

    如果您先前已安裝 beta 元件，請確認您使用的是最新版本：

    gcloud components update

  3. 請下載並使用以下指令碼，啟用 API 並設定使用 Google Cloud CLI 的適當權限：set-permissions.sh。

    如要瞭解指令碼，請參閱「set-permissions.sh 指令碼」。

  4. 使用 gcloud beta compute instances ops-agents policies create 指令建立政策。如需指令語法，請參閱 gcloud beta compute instances ops-agents policies create 說明文件。

    如需指令格式設定的範例，請參閱 Google Cloud CLI 說明文件中的「範例」一節。

    如要進一步瞭解指令群組中的其他指令和可用的選項，請參閱 gcloud beta compute instances ops-agents policies 說明文件。

使用代理程式政策的最佳做法

為了在推出期間控制對實際運作系統的影響，建議您使用執行個體標籤和區域，篩選政策適用的執行個體。

如果您要為作業套件代理程式建立政策，請確認 VM 未安裝舊版 Logging 代理程式或 Monitoring 代理程式。在同一個 VM 上執行作業套件代理程式和舊版代理程式，可能會導致重複的記錄擷取或指標擷取衝突。如有需要，請先解除安裝 Monitoring 代理程式，再解除安裝 Logging 代理程式，然後再建立安裝 Ops Agent 的政策。

以下是名為 my_project 專案中 Debian 11 VM 的分階段推出計畫範例：

第 1 階段：建立名為 ops-agents-policy-safe-rollout 的政策，在標記為 env=test 和 app=myproduct 的所有 VM 上安裝作業套件代理程式。

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=ops-agent,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=debian,version=11 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

如要進一步瞭解如何指定作業系統，請參閱 gcloud beta compute instances ops-agents policies create。

第 2 階段：更新該政策，將目標 VM 設為位於單一區域中，且標記為 env=prod 和 app=myproduct 的 VM。

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c \

階段 3：更新政策，清除區域篩選器，以便在全球推出

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --clear-zones

在 OS 設定推出前適用於 VM 的政策

您可能需要在 OS 設定之前的手動安裝及設定 OS 設定代理程式。如要瞭解如何手動安裝及驗證 OS 設定代理程式，請參閱 VM Manager 驗證檢查清單。

排解 Beta 版代理程式政策問題

本節提供資訊，協助您解決 Ops Agent、舊版監控代理程式和舊版記錄代理程式的 Beta 版代理程式政策問題。

ops-agents policy 指令失敗

當 gcloud beta compute instances ops-agents policies 指令失敗時，回應會顯示驗證錯誤。按照錯誤訊息建議修正指令引數和標記，即可修正錯誤。

除了驗證錯誤之外，您可能會看到指出下列情況的錯誤：

以下各節將詳細說明這些條件。

身分與存取權管理權限不足

如果 gcloud beta compute instances ops-agents policies 指令因權限錯誤而失敗，請確認您已按照「建立代理程式政策」一文所述，執行 set-permissions.sh 指令碼來設定 OS Config 政策角色：

如要進一步瞭解 set-permissions.sh 指令碼，請參閱「set-permissions.sh 指令碼」。

未啟用 OS Config API

錯誤訊息示例如下：

API [osconfig.googleapis.com] not enabled on project PROJECT_ID.
Would you like to enable and retry (this will take a few minutes)?
(y/N)?

您可以輸入 y 來啟用 API，也可以執行 建立代理程式政策中所述的 set-permissions.sh 指令碼，授予所有必要權限。如果您在錯誤訊息提示中輸入 y，則仍需執行 set-permissions.sh 指令碼，才能設定所需權限。

如要確認專案已啟用 OS Config API，請執行下列指令：

gcloud services list --project PROJECT_ID | grep osconfig.googleapis.com

預期的輸出內容如下：

osconfig.googleapis.com    Cloud OS Config API

政策已存在

錯誤訊息示例如下：

ALREADY_EXISTS: Requested entity already exists

這項錯誤表示此政策已存在，且名稱、專案 ID 和區域都相同。您可以使用 gcloud beta compute instances ops-agents policies describe 指令確認這項資訊。

政策不存在

錯誤訊息示例如下：

NOT_FOUND: Requested entity was not found

這項錯誤可能表示政策從未建立、政策已遭刪除，或是指定的政策 ID 不正確。請確認 gcloud beta compute instances ops-agents policies describe、update 或 delete 指令中使用的 POLICY_ID 對應至現有政策。如要取得代理程式政策清單，請使用 gcloud beta compute instances ops-agents policies list 指令。

政策已建立，但似乎沒有任何影響

OS Config 代理程式會部署至每個 Compute Engine 執行個體，以便管理記錄和監控代理程式的套件。如果未安裝基礎 OS Config 代理程式，這項政策可能不會生效。

Linux

如要確認是否已安裝 OS Config 代理程式，請執行下列指令：

gcloud compute ssh instance-id \
    --project project-id \
    -- sudo systemctl status google-osconfig-agent

輸出內容範例如下：

    google-osconfig-agent.service - Google OSConfig Agent
    Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset:
    Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago
    Main PID: 369 (google_osconfig)
     Tasks: 8 (limit: 4374)
    Memory: 102.7M
    CGroup: /system.slice/google-osconfig-agent.service
            └─369 /usr/bin/google_osconfig_agent

Windows

如要確認是否已安裝 OS 設定代理程式，請執行下列步驟：

  1. 使用遠端桌面協定或類似工具連線至執行個體，然後登入 Windows。

  2. 開啟 PowerShell 終端機，然後執行下列 PowerShell 指令。您不需要管理員權限。

    Get-Service google_osconfig_agent

輸出內容範例如下：

    Status   Name               DisplayName
    ------   ----               -----------
    Running  google_osconfig_a… Google OSConfig Agent

如果未安裝 OS Config 代理程式，則表示您使用的作業系統不支援 VM Manager。Compute Engine 作業系統詳細資料文件會指出每個 Compute Engine 作業系統支援哪些 VM Manager 功能。

如果作業系統支援 VM 管理員，您可以手動安裝 OS 設定代理程式。

已安裝 OS 設定代理程式，但未安裝作業套件代理程式

如要確認 OS 設定代理程式套用政策時是否有任何錯誤，您可以查看 OS 設定代理程式的記錄。您可以使用 Logs Explorer 或 SSH/RDP 檢查個別 Compute Engine 執行個體。

如要在記錄檔探索工具中查看 OS 設定代理程式記錄，請使用下列篩選器：

resource.type="gce_instance"
logId(OSConfigAgent)

如要查看 OS Config 代理程式記錄，請按照下列步驟操作：

CentOS、RHEL、
SLES、SUSE

執行下列指令：

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/messages \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Debian、Ubuntu

執行下列指令：

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/syslog \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Windows

  1. 使用遠端桌面協定或類似工具連線至執行個體，然後登入 Windows。

  2. 開啟「事件檢視器」應用程式，然後依序選取「Windows 記錄」 >「應用程式」，並搜尋 Source 等於 OSConfigAgent 的記錄。

如果連線至 OS Config 服務時發生錯誤，請務必按照「建立代理程式政策」一文所述，執行 set-permissions.sh 指令碼，設定 OS Config 中繼資料。

如要確認 OS Config 中繼資料已啟用，您可以執行下列指令：

gcloud compute project-info describe \
    --project PROJECT_ID \
    | grep "enable-osconfig\|enable-guest-attributes" -A 1

預期的輸出內容如下：

- key: enable-guest-attributes
  value: 'TRUE'
- key: enable-osconfig
  value: 'TRUE'

已安裝可觀察性代理程式，但無法正常運作

如要瞭解如何偵錯特定代理程式，請參閱下列文件：

為 OS Config 代理程式啟用偵錯層級記錄

回報問題時，在 OS 設定代理程式中啟用偵錯層級記錄功能可能會很有幫助。

您可以設定 osconfig-log-level: debug 中繼資料，為 OS Config 代理程式啟用偵錯層級記錄功能。收集到的記錄包含更多資訊，有助於調查。

如要為整個專案啟用偵錯層級記錄功能，請執行下列指令：

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

如要為單一 VM 啟用偵錯層級記錄功能，請執行下列指令：

gcloud compute instances add-metadata INSTANCE_ID \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

輔助指令碼

本節將進一步說明本文所述的輔助指令碼：

set-permissions.sh 指令碼

下載 set-permissions.sh 指令碼後，您可以根據提供的引數，使用指令碼執行下列動作：

下列範例說明瞭指令碼的常見叫用方式。詳情請參閱指令碼本身的註解。

如要啟用 API，請為預設服務帳戶授予必要角色，並為專案啟用 OS Config 中繼資料，請執行下列指令碼：

bash set-permissions.sh --project=PROJECT_ID

如要將 OS Config 角色之一授予在專案中沒有擁有者 (roles/owner) 角色的使用者，請執行下列指令碼：

bash set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

如要額外將其中一個 OS Config 角色授予非預設服務帳戶，請按照下列方式執行指令碼：

bash set-permissions.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

diagnose.sh 指令碼

在提供專案 ID、Compute Engine 執行個體 ID 和代理程式政策 ID 後，diagnose.sh 指令碼會自動收集必要資訊，協助診斷政策問題：

  • OS 設定代理程式版本
  • 基礎 OS Config 訪客政策
  • 適用於此 Compute Engine 執行個體的政策
  • 這個 Compute Engine 執行個體所拉取的代理程式套件存放區

如要叫用指令碼，請執行下列指令：

bash diagnose.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID

Terraform 整合

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

Terraform 對代理程式政策的支援功能是建立在 Google Cloud CLI 指令之上。如要使用 Terraform 建立代理程式政策，請按照 Terraform 模組 agent-policy 指示操作。您也可以在 examples 目錄中找到政策範例。