使用代理程式政策

代理程式政策可自動安裝及維護 Google Cloud Observability 代理程式，適用於符合使用者指定條件的 Compute Engine VM 機群。您可以為 專案Google Cloud 建立政策，控管與該 專案Google Cloud 相關聯的現有和新 VM，確保這些 VM 上的所有 Google Cloud Observability 代理程式都能正確 安裝、解除安裝及選擇性 自動升級 。

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

支援的作業系統

您可以對執行下列作業系統的 Compute Engine VM 執行個體套用代理程式政策：

建立代理程式政策

本節說明如何使用 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 說明文件。

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

為控管推出期間對正式環境系統的影響，建議您使用執行個體標籤和區域，篩選套用政策的執行個體。

以下範例說明如何為名為 my_project 的專案中的 Debian 11 VM 制定分階段推出計畫：

第 1 階段：建立名為 ops-agents-policy-safe-rollout 的政策，在所有標籤為 env=test 和 app=myproduct 的 VM 上安裝舊版 Logging 代理程式和 Monitoring 代理程式。

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=logging,version=current-major,package-state=installed,enable-autoupgrade=true;type=metrics,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 階段：更新政策，將目標設為單一可用區中具有 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 的政策

如果 VM 早於 OS 設定推出，您可能需要手動安裝及設定 OS 設定代理程式。如要瞭解如何手動安裝及驗證 OS Config 代理程式，請參閱 VM 管理員驗證檢查清單。

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

本節提供相關資訊，協助您解決 Ops Agent、舊版 Monitoring 代理程式和舊版 Logging 代理程式的 Beta 版代理程式政策問題。

ops-agents policy 指令失敗

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

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

• IAM 權限不足
• 未啟用 OS Config API
• 指定的政策不存在

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

IAM 權限不足

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

• GuestPolicy 管理員 (roles/osconfig.guestPolicyAdmin)： 提供訪客政策的完整存取權。
• GuestPolicy 編輯者 (roles/osconfig.guestPolicyEditor)： 允許使用者取得、更新及列出房客政策。
• GuestPolicy 檢視者 (roles/osconfig.guestPolicyViewer)： 提供唯讀存取權，可取得及列出客體政策。

如要進一步瞭解 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 執行個體，以管理 Logging 和 Monitoring 代理程式的套件。如果未安裝基礎 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

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

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

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

已安裝 OS 設定代理程式，但未安裝 Monitoring 代理程式

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

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

resource.type="gce_instance"
logId(OSConfigAgent)

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

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

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

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

如要確認 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'

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

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

• 排解 Ops Agent 問題
• 排解舊版 Logging 代理程式問題
• 排解舊版 Monitoring 代理程式的問題

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

回報問題時，啟用 OS Config 代理程式的偵錯層級記錄功能可能會有幫助。

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

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

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 指令碼
• diagnose.sh 指令碼

set-permissions.sh 指令碼

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

• 為專案啟用 Cloud Logging API、Cloud Monitoring API 和 OS Config API。

• 將 Identity and Access Management 角色 「記錄檔寫入者」(roles/logging.logWriter) 和「監控指標寫入者」(roles/monitoring.metricWriter) 授予 Compute Engine 預設服務帳戶，讓代理程式能將記錄檔和指標寫入 Logging 和 Cloud Monitoring API。

• 為專案啟用 OS 設定中繼資料，讓每個 VM 上的 OS 設定代理程式保持啟用狀態。

• 將下列其中一個 IAM 角色授予非擁有者使用者、使用者或服務帳戶，以便建立及管理政策。專案擁有者有權建立及管理政策，其他使用者或服務帳戶則必須獲派下列其中一個角色：

  • GuestPolicy 管理員 (roles/osconfig.guestPolicyAdmin)： 提供訪客政策的完整存取權。
  • GuestPolicy 編輯者 (roles/osconfig.guestPolicyEditor)： 允許使用者取得、更新及列出房客政策。
  • GuestPolicy 檢視者 (roles/osconfig.guestPolicyViewer)： 提供唯讀存取權，可取得及列出客體政策。

  執行指令碼時，您只需要指定角色名稱的 guestPolicy* 部分。指令碼會提供名稱的 roles/osconfig. 部分。

下列範例顯示指令碼的一些常見叫用方式。 詳情請參閱指令碼本身的註解。

如要啟用 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 目錄中找到範例政策。