部署工作，將 Cloud Storage 中的記錄檔匯入 Cloud Logging

Last reviewed 2025-02-19 UTC

本文說明如何部署「將記錄從 Cloud Storage 匯入 Cloud Logging」一文所述的參考架構。

這些操作說明適用於工程師和開發人員，包括開發運作、網站可靠性工程師 (SRE) 和安全調查人員，他們想要設定及執行記錄匯入作業。本文也假設您熟悉如何執行 Cloud Run 匯入作業，以及如何使用 Cloud Storage 和 Cloud Logging。

架構

下圖顯示此參考架構中使用的 Google Cloud 服務：

詳情請參閱「將記錄從 Cloud Storage 匯入 Cloud Logging」。

目標

• 建立及設定 Cloud Run 匯入工作
• 建立服務帳戶來執行工作

費用

在本文件中，您會使用下列 Google Cloud計費元件：

• Cloud Logging
• Cloud Run
• Cloud Storage

您可以使用 Pricing Calculator，根據預測用量估算費用。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

事前準備

1. 請確認您要匯入的記錄先前已匯出至 Cloud Storage，也就是說，這些記錄已按照預期的匯出格式整理。

2. 在 Google Cloud 控制台中啟用 Cloud Shell。

   啟用 Cloud Shell

3. 建立或選取 Google Cloud 專案。

   選取或建立專案所需的角色

   • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
   • 建立專案：如要建立專案，您需要專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

   • 建立 Google Cloud 專案：

     gcloud projects create PROJECT_ID

     將 PROJECT_ID 替換為要建立的專案名稱。 Google Cloud

   • 選取您建立的 Google Cloud 專案：

     gcloud config set project PROJECT_ID

     將 PROJECT_ID 替換為 Google Cloud 專案名稱。

   將 PROJECT_ID 替換為目的地專案 ID。

   注意： 建議您為匯入的記錄建立新的指定專案。 如果使用現有專案，匯入的記錄可能會轉送至不當的目的地，導致產生額外費用或意外匯出。為確保記錄不會轉送至不想要的目的地，請檢查所有接收器 (包括 _Required 和 _Default) 的篩選器。確認接收器並非繼承自組織或資料夾。

4. 請確認您已為 Google Cloud 專案啟用計費功能。

5. 如果尚未啟用 Cloud Run 和 Identity and Access Management (IAM) API，請啟用：

   啟用 API 時所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   gcloud services enable run.googleapis.com iam.googleapis.com

必要的角色

如要取得部署這項解決方案所需的權限，請要求管理員授予您下列 IAM 角色：

• 如要授予記錄檔 bucket 的記錄寫入者角色：目的地專案的專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
• 如要授予儲存空間 bucket 的「Storage 物件檢視者」角色： 儲存空間 bucket 所在專案的「Storage 管理員」 (roles/storage.admin)
• 如要建立服務帳戶：目的地專案的建立服務帳戶 (roles/iam.serviceAccountCreator)
• 如要在專案中啟用服務： 目標專案的服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)
• 如要升級記錄檔 bucket 並刪除匯入的記錄，您必須具備下列實體的「記錄管理員 」角色 (roles/logging.admin)：目的地專案
• 如要建立、執行及修改匯入工作，請在目的地專案中點選「Cloud Run Developer」 (roles/run.developer)。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

升級記錄檔 bucket 來使用 Observability Analytics

建議您使用預設記錄檔 bucket，並升級該 bucket 以使用記錄檔分析工具。不過，如果預設 bucket 不符合需求，您可以在正式環境中使用自己的記錄檔 bucket。如果您決定使用自己的值區，則必須將擷取的記錄檔，從來源專案傳送至這個記錄檔值區。詳情請參閱「設定記錄檔儲存空間」和「建立接收器」。

升級 bucket 後，您可以使用 SQL 查詢及分析記錄檔。 升級 bucket 或使用 Observability Analytics 不會產生額外費用。

注意： bucket 升級後即無法降級。如要進一步瞭解設定和限制，請參閱「升級 bucket 以使用 Observability Analytics」。

如要升級目標專案中的預設記錄檔 bucket，請按照下列步驟操作：

• 升級預設記錄檔 bucket，以便使用 Observability Analytics：

  gcloud logging buckets update BUCKET_ID --location=LOCATION --enable-analytics
  

  更改下列內容：

  • BUCKET_ID：記錄 bucket 的名稱 (例如 _Default)
  • LOCATION：支援的地區 (例如 global)

建立 Cloud Run 匯入工作

建立作業時，您可以使用為這個參考架構提供的預先建構容器映像檔。如要修改實作項目來變更 30 天的保留期限，或有其他需求，可以自行建立自訂映像檔。

• 在 Cloud Shell 中，使用設定和環境變數建立工作：

  gcloud run jobs create JOB_NAME \
  --image=IMAGE_URL \
  --region=REGION \
  --tasks=TASKS \
  --max-retries=0 \
  --task-timeout=60m \
  --cpu=CPU \
  --memory=MEMORY \
  --set-env-vars=END_DATE=END_DATE,LOG_ID=LOG_ID,\
  START_DATE=START_DATE,STORAGE_BUCKET_NAME=STORAGE_BUCKET_NAME,\
  PROJECT_ID=PROJECT_ID
  

  更改下列內容：

  • JOB_NAME：工作名稱。
  • IMAGE_URL：容器映像檔的參照；使用 us-docker.pkg.dev/cloud-devrel-public-resources/samples/import-logs-solution 或自訂映像檔的網址 (如果您是按照 GitHub 中的操作說明建構)。
  • REGION：您希望工作所在的區域；為避免產生額外費用，建議將工作區域與 Cloud Storage bucket 區域保持相同，或位於相同多區域。舉例來說，如果值區位於美國多區域，您可以使用 us-central1。詳情請參閱「成本最佳化」。
  • TASKS：工作必須執行的任務數量。預設值為 1。如果發生逾時，可以增加工作數量。
  • CPU：CPU 限制，可以是 1、2、4、6 或 8 個 CPU。預設值為 2。如果發生逾時情形，可以增加數量；詳情請參閱「設定 CPU 限制」。
  • MEMORY：記憶體上限。 預設值為 2Gi。如果發生逾時情形，可以增加數量；詳情請參閱「設定記憶體限制」。
  • END_DATE：日期範圍的結尾，格式為 MM/DD/YYYY。系統會匯入時間戳記早於或等於這個日期的記錄。
  • LOG_ID：要匯入的記錄檔記錄 ID。記錄 ID 是記錄項目的 logName 欄位的一部分。例如：cloudaudit.googleapis.com。
  • START_DATE：日期範圍的開始日期，格式為 MM/DD/YYYY。系統會匯入時間戳記等於或晚於這個日期的記錄。
  • STORAGE_BUCKET_NAME：儲存記錄檔的 Cloud Storage bucket 名稱 (不含 gs:// 前置字元)。

  max-retries 選項設為零，可防止失敗的工作重試，以免產生重複的記錄項目。

  如果 Cloud Run 工作因逾時而失敗，可能會導致匯入作業不完整。為避免匯入作業因逾時而中斷，請增加 tasks 值，以及 CPU 和記憶體資源。

調高這些值可能會增加費用。如要瞭解費用詳情，請參閱「成本最佳化」。

建立服務帳戶來執行 Cloud Run 工作

1. 在 Cloud Shell 中建立由使用者管理的服務帳戶：

   gcloud iam service-accounts create SA_NAME
   

   將 SA_NAME 替換為服務帳戶名稱。

2. 授予 Storage bucket 的 Storage 物件檢視者角色：

   gcloud storage buckets add-iam-policy-binding gs://STORAGE_BUCKET_NAME \
   --member=serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/storage.objectViewer
   

   更改下列內容：

   • STORAGE_BUCKET_NAME：匯入工作設定中使用的 Storage bucket 名稱。例如：my-bucket。
   • PROJECT_ID：目的地專案 ID。

3. 授予記錄檔 bucket 的記錄寫入者角色：

   gcloud projects add-iam-policy-binding PROJECT_ID \
   --member=serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/logging.logWriter
   

4. 設定 Cloud Run 工作的服務帳戶：

   gcloud run jobs update JOB_NAME \
   --region=REGION \
   --service-account SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   

   將 REGION 替換為您部署 Cloud Run 匯入工作的區域。

執行匯入工作

• 在 Cloud Shell 中執行建立的工作：

  gcloud run jobs execute JOB_NAME \
  --region=REGION
  

詳情請參閱「執行工作」和「管理工作執行作業」。

如需重新執行工作，請刪除先前匯入的記錄，以免建立重複項目。詳情請參閱本文件後續的「刪除匯入的記錄」一節。

查詢匯入的記錄時，查詢結果不會顯示重複項目。 Cloud Logging 會從查詢結果中移除重複項目 (來自相同專案的記錄項目，且插入 ID 和時間戳記相同)。詳情請參閱 Logging API 參考資料中的 insert_id 欄位。

驗證結果

如要確認工作是否已順利完成，請在 Cloud Shell 中查詢匯入結果：

  gcloud logging read 'log_id("imported_logs") AND timestamp<=END_DATE'

輸出內容會顯示匯入的記錄。如果這個專案在指定時間範圍內執行多個匯入工作，輸出內容也會顯示這些工作匯入的記錄。

如要瞭解查詢記錄項目的更多選項和詳細資料，請參閱 gcloud logging read。

刪除匯入的記錄

如需多次執行相同工作，請刪除先前匯入的記錄，避免出現重複項目並增加費用。

• 如要刪除匯入的記錄，請在 Cloud Shell 執行 logs delete 指令：

  gcloud logging logs delete imported_logs
  

請注意，刪除匯入的記錄會清除所有匯入目標專案的記錄項目，而不只是上次匯入作業的執行結果。

後續步驟

• 請參閱 GitHub 存放區中的實作程式碼。
• 瞭解如何使用 Observability Analytics 和 SQL 分析匯入的記錄。
• 如要查看更多參考架構、圖表和最佳做法，請瀏覽 Cloud Architecture Center。

貢獻者

作者：開發人員關係工程師 Leonid Yankulin

其他貢獻者：

• Summit Tuladhar | 資深軟體工程師
• Wilton Wong | 企業架構師
• Xiang Shen | 解決方案架構師