本頁面由 Cloud Translation API 翻譯而成。

使用代理程式政策

代理程式政策可自動安裝及維護符合使用者指定條件的一組 Compute Engine VM，並在這些 VM 上安裝 Google Cloud 可觀測性代理程式。您可以為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 代理程式、舊版 Monitoring 代理程式和舊版 Logging 代理程式。

支援的作業系統

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

作業系統	作業套件代理程式 (正式版和 Beta 版^†政策)	記錄代理程式 (僅限 Beta 版^† 政策)	監控代理程式 (僅限 Beta 版^† 政策)
CentOS 8
Rocky Linux 8
RHEL 6
RHEL 7： rhel-7、rhel-7-6-sap-ha、rhel-7-7-sap-ha、rhel-7-9-sap-ha			^‡
RHEL 8： rhel-8、rhel-8-4-sap-ha、rhel-8-6-sap-ha、rhel-8-8-sap-ha			^‡
Debian 9 (Stretch)
Debian 11 (Bullseye)
以 Debian 11 (Bullseye) 為基礎的深度學習 VM 映像檔
Ubuntu LTS 18.04 (Bionic Beaver)： ubuntu-1804-lts、ubuntu-minimal-1804-lts
Ubuntu LTS 20.04 (Focal Fossa)： ubuntu-2004-lts、ubuntu-minimal-2004-lts
Ubuntu LTS 22.04 (Jammy Jellyfish)： buntu-2204-lts、ubuntu-minimal-2204-lts
SLES 12： sles-12、sles-12-sp5-sap
SLES 15： sles-15、sles-15-sp2-sap、sles-15-sp3-sap、 sles-15-sp4-sap、sles-15-sp5-sap、sles-15-sp6-sap
OpenSUSE Leap 15： opensuse-leap (opensuse-leap-15-3-, opensuse-leap-15-4-)
Windows Server： 2016、2019、2022、Core 2016、Core 2019、Core 2022

^† 在 Beta 版代理程式政策中，代理程式欄會對應至指定給 gcloud beta compute instances ops-agents policies create 呼叫的代理程式類型：

作業套件代理程式會對應至代理程式類型 ops-agent。
記錄代理程式會對應至代理程式類型 logging。
監控代理程式會對應至代理程式類型 metrics。

^‡ Monitoring 代理程式不支援 rhel-7-9-sap-ha、rhel-8-2-sap-ha 或 rhel-8-4-sap-ha。

建立代理程式政策

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

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

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

本文所述的代理程式政策使用 beta 指令群組。
如果尚未安裝，請安裝 gcloud CLI 的 beta 元件：
```
gcloud components install beta
```
如要檢查是否已安裝 beta 元件，請執行下列指令：
```
gcloud components list
```
如果您先前已安裝 beta 元件，請確認您使用的是最新版本：
```
gcloud components update
```
下載並使用下列指令碼啟用 API，並設定使用 Google Cloud CLI 的適當權限：set-permissions.sh。

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

注意： set-permissions.sh 指令碼適用於 Linux。如果您使用的電腦搭載其他作業系統，請從 Cloud Shell 執行指令碼。
使用 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 Config 推出前 VM 的政策

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

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

本節提供相關資訊，協助您解決作業套件代理程式、舊版監控代理程式和舊版記錄代理程式的 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 的完整存取權。
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 代理程式，這項政策可能不會生效。

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 設定代理程式是否已安裝，請執行下列步驟：

使用遠端桌面協定或類似工具連線至執行個體，並登入 Windows。
開啟 PowerShell 終端機，然後執行下列 PowerShell 指令。您不需要管理員權限。
```
Get-Service google_osconfig_agent
```

輸出範例如下：

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

如果未安裝 OS Config 代理程式，您可能使用的作業系統不支援 VM 管理工具。如要瞭解各 Compute Engine 作業系統支援哪些 VM 管理器功能，請參閱 Compute Engine 的作業系統詳細資料文件。

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

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

如要確認 OS 設定代理程式套用政策時是否發生錯誤，可以查看 OS 設定代理程式的記錄。您可以透過記錄檢視器，或使用 SSH 或遠端桌面協定檢查個別 Compute Engine 執行個體，完成這項作業。

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

resource.type="gce_instance"
logId(OSConfigAgent)

如要查看 OS 設定代理程式記錄，請執行下列操作：

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

使用遠端桌面協定或類似工具連線至執行個體，並登入 Windows。
開啟「事件檢視器」應用程式，然後依序選取「Windows 記錄」 >「應用程式」，並搜尋 Source 等於 OSConfigAgent 的記錄。

如果無法連線至 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'

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

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

啟用 OS 設定代理程式的偵錯層級記錄

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

您可以設定 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。
將「記錄寫入者」(roles/logging.logWriter)和「監控指標寫入者」(roles/monitoring.metricWriter) Identity and Access Management 角色授予 Compute Engine 預設服務帳戶，讓代理程式能將記錄和指標寫入 Logging 和 Cloud Monitoring API。
為專案啟用 OS 設定中繼資料，讓每個 VM 上的 OS 設定代理程式都能運作。
將下列其中一個 IAM 角色授予非擁有者使用者、使用者或服務帳戶，以便建立及管理政策。專案擁有者有權建立及管理政策；其他使用者或服務帳戶必須獲得下列其中一個角色：
- GuestPolicy 管理員 (roles/osconfig.guestPolicyAdmin)：提供 GuestPolicy 的完整存取權。
- 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 目錄中找到範例政策。

使用代理程式政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

支援的作業系統

建立代理程式政策

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

OS Config 推出前 VM 的政策

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

ops-agents policy 指令失敗

IAM 權限不足

OS Config API 未啟用

已有相同政策

政策不存在

政策已建立，但似乎沒有作用

Linux

Windows

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

CentOS、RHEL、SLES、SUSE

Debian、Ubuntu

Windows

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

啟用 OS 設定代理程式的偵錯層級記錄

輔助指令碼

set-permissions.sh 指令碼

diagnose.sh 指令碼

整合 Terraform

使用代理程式政策

`ops-agents policy` 指令失敗

CentOS、RHEL、
SLES、SUSE

`set-permissions.sh` 指令碼

`diagnose.sh` 指令碼