Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

VM 管理員疑難排解

本文說明如何排解 VM Manager 的問題。

如要進一步瞭解 VM Manager，請參閱「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 進行驗證」一節。

總覽

如要排解問題，請先確認 VM Manager 設定正確。如果設定正確，但仍有問題，可以查看記錄。查看記錄時，您可以找出 VM 或 VM Manager 工作流程中的問題 (例如指令或指令碼中的錯誤)，並加以隔離及解決。

您可以從記錄中收集下列資訊：

VM 記錄的任何錯誤訊息或警告。這些記錄可協助您找出 VM 層級的錯誤，或 VM 上執行的其他服務所發生的錯誤。如要查看這些記錄，請參閱「檢查 Cloud Logging」。
OS Config 代理程式記錄的詳細偵錯資訊。這些記錄可協助您找出 VM Manager 執行的任何作業問題。如要檢查 OS Config 代理程式的偵錯記錄檔，請參閱「檢查偵錯記錄」。

找出問題或錯誤後，您也可以查看常見錯誤一節，瞭解可能的修正方式，或參閱管理整個組織修補程式部署作業的解決方法。

檢查 Cloud Logging

您可以使用各項功能的 Google Cloud 控制台快速連結查看記錄。

OS 修補程式

前往 Google Cloud 控制台「Patch」(修補) 頁面的「Jobs run」(工作執行作業) 分頁。
前往「Jobs run」(工作執行作業)
按一下要偵錯的修補工作名稱。
前往「Updated VM instances」(更新後的 VM 執行個體) 專區。
在特定 VM 的「記錄」下方，點選「查看」。

OS 政策

OS 政策支援這項程序。如為訪客政策 (Beta 版)，請使用偵錯記錄檔選項，詳情請參閱下一節。

前往 Google Cloud 控制台，然後前往「OS policies」(OS 政策) 頁面的「VM instances」(VM 執行個體) 分頁。
前往 VM 執行個體
按一下要偵錯的 VM 名稱。
前往「政策」部分。
在「記錄」下方，按一下「查看」。

OS 政策自動調度管理工具

在 Google Cloud 控制台中，前往「OS policies」(OS 政策) 頁面的「OS policy orchestrators」(OS 政策自動調度管理工具) 分頁。
前往「OS policy orchestrators」(OS 政策自動調度管理工具) 頁面
按一下要偵錯的 OS 政策自動化調度管理工具名稱。
前往「Logs」(記錄) 專區，驗證記錄項目。

檢查偵錯記錄檔

您可以為 OS Config 代理程式啟用偵錯功能，並查看偵錯記錄檔，找出任何 VM Manager 功能的問題。

啟用 OS Config 代理程式的偵錯記錄檔功能

如要啟用偵錯記錄檔，請在 VM 執行個體或專案設定 osconfig-log-level=debug 中繼資料。

如要在 VM 啟用偵錯記錄檔功能，請完成下列步驟：

控制台

前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面。

前往 VM 執行個體
按一下要設定中繼資料值的 VM 名稱。
在「Instance details」(執行個體詳細資料) 頁面中，按一下「Edit」(編輯) 即可編輯設定。
在「Custom metadata」(自訂中繼資料) 下新增下列中繼資料項目：

鍵：osconfig-log-level
值：debug
按一下「Save」(儲存)，將變更套用至 VM。

gcloud

使用 instances add-metadata 指令，並加上 --metadata=osconfig-log-level=debug 旗標。

gcloud compute instances add-metadata VM_NAME \
    --metadata=osconfig-log-level=debug

將 VM_NAME 替換為 VM 名稱。

REST

如需設定執行個體中繼資料的操作說明，請按照 API 操作說明設定執行個體中繼資料。

中繼資料屬性必須包含下列鍵/值組合：

鍵：osconfig-log-level
值：debug

查看偵錯記錄檔

啟用偵錯記錄檔功能後，OS Config 代理程式會將記錄項目寫入 Cloud Logging 和序列埠控制台。

在 VM 上啟用偵錯記錄檔後，OS Config 代理程式約需十分鐘，才會開始將偵錯訊息寫入 Cloud Logging。如要縮短等待時間，可以重新啟動代理程式或 VM。如要進一步瞭解 Cloud Logging，請參閱「查看 Cloud Logging 記錄檔」。

如要查看偵錯記錄檔，可以使用下列選項：

Cloud Logging：使用 Google Cloud 控制台或 Google Cloud CLI
序列埠控制台

控制台

前往Google Cloud 控制台的「Logging」>「Logs Explorer」頁面：

前往 Logs Explorer
如有需要，請在頁面頂端選取現有的 Google Cloud 專案，或建立新專案。
在「資源」下拉式選單中，選取「VM 執行個體」。系統會顯示可用 VM (instance_id) 的清單。
按一下要查看的 VM。
按一下「新增」。
在「Log name」(記錄檔名稱) 下拉式選單中，選取「OSConfigAgent」。
按一下「新增」。

查詢應如下所示：

resource.type="gce_instance" resource.labels.instance_id="INSTANCE_ID"
logName="projects/PROJECT_ID/logs/OSConfigAgent"

點選「執行查詢」。

gcloud

執行 gcloud logging read 指令。

 gcloud logging read "resource.type=gce_instance AND logName=projects/PROJECT_ID/logs/OSConfigAgent"

將 PROJECT_ID 替換為專案 ID。

序列埠

如要查看序列埠控制台的偵錯記錄檔資訊，請參閱「查看序列埠輸出內容」。

常見錯誤

驗證問題

如要使用 VM 管理員，您必須具備下列條件：

附加的服務帳戶。VM 管理員會使用這個服務帳戶，簽署傳送至 API 服務的要求。
確認附加的服務帳戶具備 roles/logging.logWriter 角色，可將記錄寫入 Logging API。
Google Cloud OS 設定服務代理。VM 管理員會在啟動修補工作時建立這個服務代理，並授予 Cloud OS Config 服務代理角色。如要建立 OS 政策，則不必設定這個服務代理。

如果您使用 VM 管理員，但未連結服務帳戶或 Google Cloud OS Config 服務代理，則在處理修補工作時可能會看到下列錯誤：

Service account permissions are missing. Verify that the service account has the correct permissions and try again.

OSConfigAgent Error main.go:88: error getting token from metadata: metadata: GCE metadata "instance/service-accounts/default/identity?audience=osconfig.googleapis.com&format=full" not defined

message: "Error running OPERATION_NAME: error calling OPERATION_NAME: code: "PermissionDenied", message: "The caller does not have permission", details: []"

驗證問題也可能導致 VM 執行個體無法顯示在修補資訊主頁上。

如要解決這些問題，請嘗試下列一或所有方法：

確認所有 VM 都有附加的服務帳戶。
確認 Google Cloud OS 設定服務代理已設定 Cloud OS 設定服務代理角色 (roles/osconfig.serviceAgent)。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-osconfig.iam.gserviceaccount.com' \
  --role='roles/osconfig.serviceAgent'
```
更改下列內容：
- PROJECT_ID：專案 ID
- PROJECT_NUMBER：您的專案編號

排除修補程式更新套件時發生錯誤

在修補工作中排除套件時，如果您為套件名稱指定萬用字元或特殊字元，OS 修補管理可能會忽略清單並更新所有套件。

如要解決這個問題，請將 OS 設定代理程式更新至 20220829.00 版，並使用正斜線 (/) 包住套件名稱。

在以下範例中，OS 修補程式管理服務會排除套件名稱前置字串為 google- 的 yum 套件。

      gcloud compute os-config patch-jobs execute --instance-filter-all 

        --yum-excludes=/google-.*/

管理整個組織修補程式部署作業的解決方法

修補程式部署作業和修補工作的範圍限於個別 Google Cloud 專案，而 OS 政策則可透過政策自動化調度管理工具，在整個組織或資料夾中自動調度管理。

如要大規模管理修補程式部署作業，您可以透過 Bash 指令碼使用 Cloud Asset Inventory 和 Google Cloud CLI，疊代機構中的所有專案。這段指令碼可讓您完成下列工作：

在多項專案中啟用 VM Manager
建立跨專案修補程式部署作業
將各專案的修補工作結果匯出為 CSV 檔案

必要權限和組織 ID

執行本節中的指令碼前，請確認您具備必要的 Identity and Access Management (IAM) 權限和組織 ID：

組織層級：如要使用 Cloud Asset Inventory 列出組織中的所有專案，您的使用者帳戶或服務帳戶必須具備組織的 cloudasset.assets.searchAllResources 權限 (包含在 Cloud Asset 檢視者角色 roles/cloudasset.viewer 中)。
目標專案層級：視您在組織中執行的工作而定，您的使用者帳戶或服務帳戶必須具備各目標專案的下列權限 (例如從組織層級角色繫結繼承)：
- 如要啟用 OS Config API 並設定專案中繼資料，請執行下列操作：serviceusage.services.enable (服務使用情形管理員，roles/serviceusage.serviceUsageAdmin) 和compute.projects.setCommonInstanceMetadata (Compute 執行個體管理員 (v1)，roles/compute.instanceAdmin.v1)。
- 如要建立修補程式部署作業：osconfig.patchDeployments.create (OS 設定修補程式部署作業管理員，roles/osconfig.patchDeploymentAdmin)。
- 如要列出修補工作及查看 VM 執行個體詳細資料：osconfig.patchJobs.list 和 osconfig.patchJobs.get (OS Config 修補工作檢視者，roles/osconfig.patchJobViewer)。

如要找出組織 ID，請對組織中的任何專案執行 gcloud projects get-ancestors 指令：

gcloud projects get-ancestors PROJECT_ID

將 PROJECT_ID 替換為組織中的專案 ID。輸出內容會列出專案的上層資料夾和 organization ID。

在多項專案啟用 VM Manager

如要在組織或資料夾中，為所有現有和未來的專案啟用 VM Manager，Google 建議使用階層式服務啟用和組織政策或 Terraform。

或者，如要啟用 OS Config API (osconfig.googleapis.com)，並使用 Bash 指令碼在組織中所有現有專案設定 enable-osconfig=TRUE 專案中繼資料，請執行下列指令：

for project in $(gcloud asset search-all-resources \
    --scope=organizations/ORGANIZATION_ID \
    --asset-types=cloudresourcemanager.googleapis.com/Project \
    --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
  gcloud services enable osconfig.googleapis.com --project="$project"
  gcloud compute project-info add-metadata --project="$project" \
      --metadata=enable-osconfig=TRUE
done

請將 ORGANIZATION_ID 替換成組織 ID。

跨專案建立修補程式部署作業

如要在組織的所有專案中套用標準化修補程式部署排程，請建立修補程式部署設定檔，並套用至各項專案：

建立 JSON 或 YAML 範本檔案，並命名為 patch_deployment_template.json，用於定義目標執行個體篩選器、修補設定和排程。如要進一步瞭解支援的設定欄位，請參閱「建立修補程式部署作業」和 PatchDeployment 資源參考資料。

舉例來說，下列 patch_deployment_template.json 檔案會為專案中的所有 VM 執行個體，排定每週二晚上 7:30 (America/Los_Angeles 時區) 執行的週期性修補工作：
```
{
  "instanceFilter": {
    "all": true
  },
  "patchConfig": {
    "rebootConfig": "DEFAULT"
  },
  "recurringSchedule": {
    "frequency": "WEEKLY",
    "weekly": {
      "dayOfWeek": "TUESDAY"
    },
    "timeOfDay": {
      "hours": 19,
      "minutes": 30
    },
    "timeZone": {
      "id": "America/Los_Angeles"
    }
  }
}
```

執行下列迴圈，使用 gcloud compute os-config patch-deployments create 指令在組織中的每個專案建立修補程式部署作業：

for project in $(gcloud asset search-all-resources \
    --scope=organizations/ORGANIZATION_ID \
    --asset-types=cloudresourcemanager.googleapis.com/Project \
    --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
  gcloud compute os-config patch-deployments create patch-"$project" \
      --project="$project" \
      --file=patch_deployment_template.json
done

請將 ORGANIZATION_ID 替換成組織 ID。

將各項專案的修補工作結果匯出為 CSV 檔案

如要稽核修補工作結果，可以使用 gcloud compute os-config patch-jobs list-instance-details 指令，將失敗或成功的修補工作 VM 執行個體詳細資料匯出至 CSV 檔案。

單一修補工作：如要匯出特定修補工作中失敗或成功的 VM 執行個體，請執行下列指令：

匯出失敗的 VM 執行個體：

gcloud compute os-config patch-jobs list-instance-details PATCH_JOB_ID \
    --project=PROJECT_ID \
    --filter="state:(FAILED OR TIMED_OUT OR NO_AGENT_DETECTED)" \
    --format="csv(name.basename():label=INSTANCE_NAME,zone:label=ZONE,state:label=STATE,failureReason:label=FAILURE_REASON)" > failed_patches.csv

匯出成功的 VM 執行個體：

gcloud compute os-config patch-jobs list-instance-details PATCH_JOB_ID \
    --project=PROJECT_ID \
    --filter="state=SUCCEEDED" \
    --format="csv(name.basename():label=INSTANCE_NAME,zone:label=ZONE,state:label=STATE,attemptCount:label=ATTEMPT_COUNT)" > succeeded_patches.csv

更改下列內容：

PATCH_JOB_ID：修補工作的 ID
PROJECT_ID：專案 ID

組織中的所有專案：如要疊代組織中的所有專案，並將修補工作失敗和成功的 VM 執行個體匯出至 CSV 檔案，請執行下列指令碼：

echo "PROJECT_ID,PATCH_JOB_ID,INSTANCE_NAME,ZONE,STATE,FAILURE_REASON" > failed_patches.csv
echo "PROJECT_ID,PATCH_JOB_ID,INSTANCE_NAME,ZONE,STATE,ATTEMPT_COUNT" > succeeded_patches.csv

for project in $(gcloud asset search-all-resources \
    --scope=organizations/ORGANIZATION_ID \
    --asset-types=cloudresourcemanager.googleapis.com/Project \
    --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
  for job in $(gcloud compute os-config patch-jobs list \
      --project="$project" \
      --format="value(name.basename())"); do
    gcloud compute os-config patch-jobs list-instance-details "$job" \
        --project="$project" \
        --filter="state:(FAILED OR TIMED_OUT OR NO_AGENT_DETECTED)" \
        --format="csv[no-heading](name.basename(),zone,state,failureReason)" | \
        sed "s/^/${project},${job},/" >> failed_patches.csv
    gcloud compute os-config patch-jobs list-instance-details "$job" \
        --project="$project" \
        --filter="state=SUCCEEDED" \
        --format="csv[no-heading](name.basename(),zone,state,attemptCount)" | \
        sed "s/^/${project},${job},/" >> succeeded_patches.csv
  done
done

請將 ORGANIZATION_ID 替換成組織 ID。

根據預設，gcloud compute os-config patch-jobs list 指令會傳回每個專案最多 10 項修補工作。如要僅匯出各專案中最新修補工作的結果，請在 gcloud compute os-config patch-jobs list 指令中加入 --sort-by="~update_time" --limit=1。

如要在Google Cloud 控制台或 BigQuery 中查看組織層級的修補程式法規遵循和安全漏洞報告，請參閱「查看組織或資料夾中 VM 的修補程式摘要」和「查看組織的安全漏洞報告」。

VM 管理員疑難排解 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

控制台

gcloud

REST

總覽

檢查 Cloud Logging

OS 修補程式

OS 政策

OS 政策自動調度管理工具

檢查偵錯記錄檔

啟用 OS Config 代理程式的偵錯記錄檔功能

控制台

gcloud

REST

查看偵錯記錄檔

控制台

gcloud

序列埠

常見錯誤

驗證問題

排除修補程式更新套件時發生錯誤

管理整個組織修補程式部署作業的解決方法

必要權限和組織 ID

在多項專案啟用 VM Manager

跨專案建立修補程式部署作業

將各項專案的修補工作結果匯出為 CSV 檔案

後續步驟

VM 管理員疑難排解