使用代理程式政策 (GA)

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

事前準備

ops-agent-policy Terraform 模組是以 Google Cloud SDK 的 gcloud compute instances ops-agents policies 指令為基礎建構而成。如要瞭解 Terraform 的運作方式，請參閱「使用 Terraform」一文。

使用 Google Cloud CLI 或 Terraform 模組建立代理程式政策前，請完成下列步驟：

1. 如果您要使用 gcloud compute instances ops-agents policies 指令，且尚未安裝 Google Cloud CLI，請先安裝。

2. 如果您要使用 Terraform 模組，請執行下列步驟：

   1. 如要瞭解如何安裝 Terraform，請參閱「安裝及設定 Terraform」一文。Cloud Shell 已安裝 Terraform。

   2. 複製 terraform-google-cloud-operations 存放區，其中包含 ops-agent-policy 模組：

      git clone https://github.com/terraform-google-modules/terraform-google-cloud-operations
      

3. 下載並執行 prepare-for-ops-agents-policies.sh 指令碼，啟用必要 API，並設定使用 Google Cloud CLI 或 Terraform 的適當權限。

   如要瞭解指令碼，請參閱「指令碼」。prepare-for-ops-agents-policies.sh

解除安裝舊版 Monitoring 代理程式和 Logging 代理程式

確認已安裝 OS 設定代理程式

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

找出作業系統資訊的值

如要將代理程式政策套用至特定作業系統或版本，您必須瞭解 OS Config 用來參照這些項目的值。

如要找出 VM 的 osShortName 和 osVersion 欄位值，請使用下列指令：

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^ShortName: "

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^Version: "

如要執行這些指令，必須在 VM 上安裝 OS 設定代理程式。

建立代理程式政策來管理作業套件代理程式

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone ZONE \
  --file path/to/policy-description-file.yaml \
  --project PROJECT_ID

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y

驗證代理程式政策的狀態

本節說明如何檢查已建立的政策狀態，以及 Ops 代理程式的安裝狀態。這項資訊也有助於排解代理程式政策問題。

Compute Engine OS 政策頁面

Compute Engine 的「OS policies」(作業系統政策) 頁面會提供管理作業套件代理程式的代理程式政策相關資訊，以及「VM instances」(VM 執行個體) 分頁中的 VM 相關資訊。例如：

• 「狀態」欄會指出政策是否已成功安裝 (「符合規定」)、安裝中 (「待處理」)、可能失敗 (「不明」) 或缺少政策 (「沒有政策」)。
• 「受監控的 VM」欄會指出作業套件代理程式是否由 OS 設定管理 (「受監控」)，或不是由 OS 設定管理 (「未受監控」)。

  如果政策狀態為「符合規定」，但 VM 顯示「未監控」，則可能是安裝作業套件代理程式時發生問題。舉例來說，您可能已安裝舊版代理程式。

前往 Google Cloud 控制台的「OS policies」(作業系統政策) 頁面：

前往「OS policies」(作業系統政策)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Compute Engine」的結果。

Compute Engine「OS policies」(作業系統政策) 分頁中的「VM instances」(VM 執行個體)，會顯示Google Cloud 專案中所有作業系統政策所管理代理程式的相關資訊。這些政策標示為「goog-ops-agent-policy」。

• goog-ops-agent-policy 指標包含多種政策：
  • 使用 gcloud compute instances ops-agents policies 指令建立的政策。
  • 如果您在建立 VM 時要求安裝作業套件代理程式，系統會為您建立政策。
  • 使用 Terraform 建立的政策，用於管理作業套件代理程式。

  如要區分政策，請使用頁面上的「作業系統政策指派」分頁，查看專案中所有政策指派的政策 ID。 Google Cloud

• 如果透過其他方式 (例如手動安裝或透過Beta 版代理程式政策) 安裝作業套件代理程式，這個「受監控的 VM」資料欄不會反映這類安裝作業。

Cloud Monitoring「VM 執行個體」頁面

Cloud Monitoring 的「VM Instances」(VM 執行個體) 頁面包含「Agent」(代理程式) 欄，其中列出每個 VM 安裝的代理程式，如果是作業套件代理程式，則會顯示安裝的代理程式是否為最新版本。

前往 Google Cloud 控制台的「VM Instances dashboard」(VM 執行個體資訊主頁) 頁面：

前往 VM 執行個體資訊主頁

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

政策設定範例

本節說明使用 Google Cloud SDK 或 Terraform 時，設定代理程式政策的範例。

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone us-central1-a \
  --file agent-policy-description.yaml \
  --project PROJECT_ID

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  all: True

agentsRule:
  packageState: removed
  version: latest
instanceFilter:
  all: True

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  - labels:
      app: web

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  exclusionLabels:
  - labels:
      env: prod
      app: web6
  inventories:
  - osShortName: debian
    osVersion: '11'

agentsRule:
  packageState: installed
  version: 2.*.*
instanceFilter:
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

排解 GA 代理程式政策問題

本節提供相關資訊，協助您解決 Ops Agent 的 GA 代理程式政策問題。您也可以參閱「確認服務專員政策狀態」一文。

ops-agents policy 指令失敗

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

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

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

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

IAM 權限不足

如果 gcloud compute instances ops-agents policies 指令因權限錯誤而失敗，請確認您已按照「事前準備」一節的說明執行 prepare-for-ops-agents-policies.sh 指令碼，設定 OS 設定政策角色：

• OSPolicyAssignment 管理員 (roles/osconfig.osPolicyAssignmentAdmin)： 提供 OS 政策指派作業的完整存取權。

• OSPolicyAssignment 編輯者 (roles/osconfig.osPolicyAssignmentEditor)： 允許使用者取得、更新及列出 OS 政策指派項目。

• OSPolicyAssignment 檢視者 (roles/osconfig.osPolicyAssignmentViewer)： 提供唯讀存取權，可取得及列出 OS 政策指派項目。

如要進一步瞭解 prepare-for-ops-agents-policies.sh 指令碼，請參閱「prepare-for-ops-agents-policies.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，也可以執行「事前準備」一節所述的 prepare-for-ops-agents-policies.sh 指令碼，授予所有必要權限。如果在錯誤訊息的提示中輸入 y，您仍須執行 prepare-for-ops-agents-policies.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 compute instances ops-agents policies describe 指令確認這項資訊。

政策不存在

錯誤範例如下：

NOT_FOUND: Requested entity was not found

這項錯誤可能表示政策從未建立、政策已刪除，或是指定的政策 ID 不正確。請確認 gcloud compute instances ops-agents policies describe、update 或 delete 指令中使用的 POLICY_ID 對應至現有政策。如要取得代理程式政策清單，請使用 gcloud 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 作業系統支援哪些 VM 管理器功能，請參閱 Compute Engine 的作業系統詳細資料文件。

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

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

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

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

resource.type="gce_instance"
logId(OSConfigAgent)

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

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 設定服務，請務必按照「事前準備」一節所述，執行 prepare-for-ops-agents-policies.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 已安裝完畢，但無法正常運作

如要進一步瞭解如何偵錯作業套件代理程式問題，請參閱「排解作業套件代理程式問題」。

啟用 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

輔助指令碼

本節提供本文所述輔助指令碼的額外資訊：

• prepare-for-ops-agents-policies.sh 指令碼
• diagnose_policies.sh 指令碼

prepare-for-ops-agents-policies.sh 指令碼

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

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

  如果 OS Config API 尚未啟用，系統會以功能受限模式啟用該 API，這足以管理代理程式政策。詳情請參閱「定價」。

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

• 為專案啟用 OS 設定中繼資料，讓每個 VM 上的 OS 設定代理程式都能運作。

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

  • OSPolicyAssignment 管理員 (roles/osconfig.osPolicyAssignmentAdmin)： 提供 OS 政策指派作業的完整存取權。
  • OSPolicyAssignment 編輯者 (roles/osconfig.osPolicyAssignmentEditor)： 允許使用者取得、更新及列出 OS 政策指派項目。
  • OSPolicyAssignment 檢視者 (roles/osconfig.osPolicyAssignmentViewer)： 提供唯讀存取權，可取得及列出 OS 政策指派項目。

  執行指令碼時，您可以將 OSPolicyAssignment 角色指定為 admin、editor 或 viewer。指令碼會將這些值對應至 roles/osconfig.osPolicyAssignment* 角色名稱。

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

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

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID

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

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

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

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

diagnose_policies.sh 指令碼

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

• OS 設定代理程式版本
• 基礎 OS 政策指派作業
• 適用於這個 Compute Engine 執行個體的 OS 政策指派項目
• 這個 Compute Engine 執行個體的說明

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

bash diagnose_policies.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID \
  --zone=ZONE

定價

gcloud compute instances ops-agents policies 指令是透過 VM 管理員的 OS 政策指派資源實作。如「事前準備」所述，prepare-for-ops-agents-policies.sh 指令碼會在功能受限模式 (OSCONFIG_B) 下設定 VM 管理員，足以建立及管理代理程式政策。在受限模式下使用 VM 管理員不須支付任何費用。

如果您已在全功能模式 (OSCONFIG_C) 下設定 VM 管理員，則可能會產生費用。