Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

設定構件防護政策

本文說明如何建立及管理構件防護政策。如需這項服務、功能和優點的總覽，請參閱「構件防護總覽」。

事前準備

建立構件防護政策前，您必須先在 Security Command Center 中啟用構件防護，並取得必要的 Identity and Access Management (IAM) 角色和權限。

接著，您可以在Google Cloud 控制台中建立政策，或使用 Google Cloud CLI 建立政策。

啟用構件防護

按照「設定 Security Command Center 服務」中的步驟啟用構件防護。

必要角色

如要取得使用構件防護所需的權限，請要求系統管理員在專案或機構中授予您下列 Identity and Access Management (IAM) 角色：

構件掃描防護評估作業管理員 (roles/artifactscanguard.policyEvaluator)

您可以使用 Google Cloud 控制台授予這個角色，也可以執行下列 Google Cloud CLI 指令：

專案

  gcloud organizations add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
        --role="roles/artifactscanguard.policyEvaluator" \

更改下列內容：

PROJECT_ID
YOUR_SERVICE_ACCOUNT_EMAIL

為準的機構

  gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
        --member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
        --role="roles/artifactscanguard.policyEvaluator" \

更改下列內容：

ORGANIZATION_ID
YOUR_SERVICE_ACCOUNT_EMAIL

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

如要瞭解更多構件防護角色，請參閱「構件防護角色和權限」。

在 Google Cloud 控制台中建立政策

如要在 Google Cloud 控制台中建立構件防護政策，請按照下列步驟操作：

在 Google Cloud 控制台，依序前往「Security」>「Rules」，然後點選「Create artifact guard policy」或「Create policy」。
輸入政策的政策 ID 和說明，然後按一下「繼續」。
選取政策範圍和動作：
- CI/CD 平台
  - 選取連接器：要與這項政策建立關聯的連接器。系統會評估與所選連接器相關聯的每個 CI/CD 建構版本是否符合這項政策。
  提示： 如果尚未建立連接器，請按一下「管理連接器」開啟「CI/CD 整合」頁面。建立 CI/CD 環境的連接器後，請返回「建立政策」頁面，然後點按「重新整理」，重新整理連接器選項。
  - 政策動作：選取違反政策時要採取的動作。
    - 封鎖違反政策的建構作業
    - 允許有警告的建構作業：CI/CD 掃描器政策評估結果會顯示在已連結的建構管道中。
- 註冊資料庫
  - 容器分析：這僅適用於機構，不適用於專案。新增要套用這項政策的 Google Cloud 專案。
  - Artifact Registry 存放區：選取要套用這項政策的存放區。這些必須是有效的 Artifact Registry 存放區。如果留空，這項政策將套用至所有存放區。
  - 政策動作：選取違反政策時要採取的動作。
    - 僅稽核：系統會評估政策，並記錄任何違規事項以供稽核，但不會封鎖資源。如要查看任何違規事項，您必須使用 ListArtifactPoliciesEvaluations 和 GetArtifactPoliciesEvaluation 呼叫 API。
    - 准入控制：如果系統在評估政策時發現違規情況，就會禁止資源繼續執行作業。
      - 將二進位授權政策設為模擬測試模式：詳情請參閱「啟用模擬測試模式」。
      - 二進位授權專案：這僅適用於機構，不適用於專案。新增要套用准入控制項的 Google Cloud 專案。
      - GKE 叢集：如果留空，則准入控制會套用至所有 GKE 叢集。
      - 覆寫二進位授權政策：必須選取這個核取方塊，才能更新許可控管的二進位授權政策。
- 執行階段
  - 執行階段專案：這僅適用於機構，不適用於專案。新增含有 GKE 叢集的執行階段專案。
  - GKE 叢集：選取要套用這項政策的 GKE 叢集。如果留空，政策就會套用至所選專案中的所有 GKE 叢集。
定義政策規則。政策規則是一組條件，可決定環境中允許哪些安全漏洞和套件。政策規則包含下列項目：
- 嚴重性門檻：設定安全漏洞的最低嚴重性等級，以便納入政策評估。安全漏洞必須符合或超過這個門檻，才會納入報告。
  
  舉例來說，如果將規則設為「中」，評估結果就會包含所有「中」、「高」和「嚴重」的安全性弱點。
- 安全漏洞計數門檻：設定套用其他政策篩選器後，允許的安全漏洞數量上限。只有在這些特定篩選後漏洞的數量超過限制時，才會違反政策。
  
  舉例來說，如果您將嚴重性門檻設為「高」，排除無法修正的安全漏洞，並將計數門檻設為五，如果建構版本包含超過五個可修正且評為「高」或「嚴重」的安全漏洞，就會建構失敗。
- 安全漏洞狀態：指定是否只納入有修正方式的安全漏洞。您可以選擇優先修復所有安全漏洞，或只修復可修復的安全漏洞。
- 例外狀況和限制：您可以在這些部分建立特定允許或封鎖項目，覆寫一般政策。
  - 豁免的 CVE：指定在特定時間內，您環境中可接受的 CVE。這有助於實作暫時的變通方法。您可以為這些例外狀況設定到期日。上述日期過後，系統將不再允許這項安全漏洞，且會導致政策違規。
  - 受限的 CVE：指定一律要封鎖的 CVE，不論嚴重程度評分為何。這項功能特別適合用來標示對特定應用程式或基礎架構造成獨特風險的安全性漏洞。
  - 允許的套件：列出視為安全的套件。可以定義套件版本，否則系統會允許所有版本。
  - 受限套件：列出要限制的套件。受限套件會導致政策失敗。可定義套件版本，否則所有版本都會受到限制。
點選「建立」。

「規則」頁面的表格會列出可用的構件防護政策。

使用 Google Cloud CLI 建立政策

本節將說明可用的構件防護 gcloud CLI 指令和使用方式。

Google Cloud CLI 必要條件

確認 gcloud CLI 版本為 559.0.0 以上。
將專案設為設定專案。

如要執行這項操作，請執行下列 gcloud CLI 指令：

   gcloud components update --version=559.0.0
   gcloud config set project PROJECT_ID

Google Cloud CLI 指令

create

gcloud alpha scc artifact-guard policies create \
    (POLICY --location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)) \
    --policy-file-path=PATH_TO_FILE

POLICY：政策的完整 ID，格式如下：
- {organizations/ORGANIZATION_ID/locations/LOCATION/policies/POLICY_ID}
- {projects/PROJECT_NUMBER/locations/LOCATION/policies/POLICY_ID}
- {policy_id -location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)}
PATH_TO_FILE：包含政策定義的 YAML 文件本機路徑。如要瞭解 YAML 檔案結構的詳細資料，請參閱本文的「YAML 檔案」一節。

get

gcloud alpha scc artifact-guard policies describe \
    (POLICY --location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER))

POLICY：政策的完整 ID，格式如下：
- {organizations/ORGANIZATION_ID/locations/LOCATION/policies/POLICY_ID}
- {projects/PROJECT_NUMBER/locations/LOCATION/policies/POLICY_ID}
- {policy_id -location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)}

list

gcloud alpha scc artifact-guard policies list PARENT

PARENT：機構或專案。父項資源可接受的格式包括：
- {organizations/ORGANIZATION_ID/locations/LOCATION}
- {projects/PROJECT_NUMBER/locations/LOCATION}

刪除

gcloud alpha scc artifact-guard policies delete \
    (POLICY --location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)) \
    [--etag=ETAG]

POLICY：政策的完整 ID，格式如下：
- {organizations/ORGANIZATION_ID/locations/LOCATION/policies/POLICY_ID}
- {projects/PROJECT_NUMBER/locations/LOCATION/policies/POLICY_ID}
- {policy_id -location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)}
etag：選用。用於並行控制。只有在資源的 ETag 相符時，要求才會繼續進行。

update

gcloud alpha scc artifact-guard policies update \
    (POLICY --location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)) \
    --policy-file-path=PATH_TO_FILE [--allow-missing] \
    [--update-mask=UPDATE_MASK]

POLICY：政策的完整 ID，格式如下：
- {organizations/ORGANIZATION_ID/locations/LOCATION/policies/POLICY_ID}
- {projects/PROJECT_NUMBER/locations/LOCATION/policies/POLICY_ID}
- {policy_id -location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)}
PATH_TO_FILE：YAML 文件的本機路徑，其中包含要更新的欄位定義。
allow_missing：選用布林值。如果 true 不存在，則會建立新政策。
update-mask：以逗號分隔的欄位清單，列出要更新的欄位。空白字串或「*」表示要完整更新政策。更新遮罩的有效欄位包括：
- display_name
- description
- scope
- enablement_state
- vulnerability_policy
- annotations

YAML 檔案

構件防護政策定義的 YAML 檔案必須遵循下列範本：

  displayName: <Human readable display name for the policy>
  description: <Description of the policy>

  vulnerabilityPolicy: # (at least one of these rules must be defined)
    exemptedCves:
      - id: <cve-id-1>
        gracePeriodExpirationTime: <optional-grace-period-expiration-time>
      - id: <cve-id-2>
        gracePeriodExpirationTime: <optional-grace-period-expiration-time>

    maxAllowedSeverity: <The maximum severity allowed in the detected
    vulnerabilities. The severity values can be LOW, MEDIUM, HIGH, CRITICAL>

    maximumAllowedVulnerabilities: <The maximum number of vulnerabilities that
    can be detected>

    excludeUnfixable: <Whether to exclude the vulnerabilities without an
    available fix from the purview of the policy evaluation>

    restrictedCves:
      - <restricted-cve-id-1>
      - <restricted-cve-id-2>

    allowedPackages:
      - name: <allowed_package_name_1>
        version: <optional_version_of_allowed_package_1. If unspecified, all the
        versions of the package are allowed>
      - name: <allowed_package_name_2>
        version: <optional_version_of_allowed_package_2>

    restrictedPackages:
      - name: <restricted_package_name_1>
        version: <optional_version_of_restricted_package_1. If unspecified, all
        the versions of the package are restricted>
      - name: <restricted_package_name_2>
        version: <optional_version_of_restricted_package_2>

  scope:
    pipeline:
      connectorIds:
        - <connector_id_1>
        - <connector_id_2>
      enforcementAction: <action to take in case the policy evaluation fails.
      The supported values are AUDIT_ONLY or BLOCK_BUILD>

    registry:
      projectIds:
        - <project_id_1>
      garRepositoryNamePatterns:
        - <repository_name_pattern_1>
      imageNamePatterns:
        - <image_name_pattern_1>
      enforcementAction: <AUDIT_ONLY or ADMISSION_CONTROL>
      admissionControl:
        deploymentProjectIds:
          - <project_id_1>
        gkeClusterNames:
          - <cluster_name_1>
        dryRun: <bool>
        overrideBinauthzPolicy: <bool>

    runtime:
        deploymentProjectIds:
          - <project_id_1>
        gkeClusterNames:
          - <cluster_name_1>
        dryRun: <bool>
        overrideBinauthzPolicy: <bool>
        enforcementAction: <AUDIT_ONLY or BLOCK_DEPLOYMENT>

  enablementState: <The enablement state of the policy. The supported values are
  ACTIVE, INACTIVE>

以下是構件防護政策檔案範例：

  displayName: 'A sample policy'
  description: Vulnerability Policy
  vulnerabilityPolicy:
    exemptedCves:
      - id: CVE-2022-40897
        gracePeriodExpirationTime: '2026-09-10T18:58:08Z'
      - id: CVE-2024-6345
    maxAllowedSeverity: MEDIUM
    maximumAllowedVulnerabilities: 5
    excludeUnfixable: true
    restrictedCves:
      - CVE-2013-4392
      - CVE-2024-4143
    allowedPackages:
      - name: systemd
        version: '257.7'
      - name: util-linux
    restrictedPackages:
      - name: ncurses
        version: 6.5+20250216
      - name: setuptools
  scope:
    pipeline:
      connectorIds:
        - organizations/123/locations/global/connectors/demoConnector
      enforcementAction: BLOCK_BUILD
    registry:
      projectIds:
        - projects/my-registry-project-id
        - projects/another-registry-project
      garRepositoryNamePatterns:
        - us-west1-docker.pkg.dev/my-registry-project-id/my-repo
        - gcr.io/team-a/internal-artifacts
      imageNamePatterns:
        - my-repo/service-a:.*
        - my-repo/service-b:v1\..*
      enforcementAction: ADMISSION_CONTROL
      admissionControl:
        deploymentProjectIds:
          - projects/my-deployment-project
        gkeClusterNames:
          - //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-a
          - //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-b
        dryRun: true
        overrideBinauthzPolicy: true
    runtime:
      deploymentProjectIds:
        - projects/my-deployment-project
      gkeClusterNames:
        - //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-a
        - //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-b
      dryRun: false
      overrideBinauthzPolicy: false
      enforcementAction: BLOCK_DEPLOYMENT
  enablementState: ACTIVE

效能和限制

每個父項資源的政策上限：父項資源 (機構或專案) 最多可定義 1,000 項政策。包括在構件防護中設定的所有類型安全性政策。
每個父項資源的漏洞政策數量上限：在整體政策限制內，以安全漏洞發現項目為重點的政策數量設有限制。上層資源 (機構或專案) 最多可有 500 項以安全漏洞為目標的政策。
每個管道的政策數量上限：針對整合構件防護政策的每個 CI/CD 管道，最多可設定 100 項政策，在建構時強制執行。
每週每項政策最多可更新次數：每項政策每週最多可更新 100 次。
每項政策的管道連結器數量上限：每項政策最多可與 100 個管道連結器建立關聯。
每項政策可豁免和限制的 CVE 數量上限：每項政策最多可豁免和限制 100 個 CVE。
每項政策允許和限制的套件數量上限：每項政策最多可允許和限制 100 個套件。

如需其他限制，請參閱「疑難排解」。

疑難排解

本節概述構件防護政策欄位，以及常見錯誤和解決方法。

政策驗證

建立或更新政策時，構件防護會驗證政策定義。如果驗證失敗，構件防護機制會拒絕要求，並提供詳細的錯誤訊息。

一般政策欄位

名稱	說明	必要	限制	範例值
父項	定義政策的適用範圍。	是	系統僅支援 `global` 位置的政策。	`organizations/123/locations/global` `projects/123/locations/global`
政策 ID	政策的專屬 ID。	是	最多 100 個半形字元。開頭須為英文字母，結尾須為英數字元，且只能包含英文字母、數字、連字號或底線。	`my-policy-1`
顯示名稱	使用者可理解的政策名稱。	否	最多 63 個半形字元。建議使用不重複的值。	`My vulnerability policy`
說明	政策說明。	否	最多 2048 個字元。	`Checks for critical vulnerabilities.`
政策類型	定義的政策類型。	是	系統僅支援 `vulnerability_policy`。	`vulnerability_policy`
啟用狀態	政策的啟用狀態。	是	必須是 `ACTIVE` 或 `INACTIVE`。	`ACTIVE`

安全漏洞政策

名稱	說明	多值	限制	範例值
maximumAllowedVulnerabilities	政策違規前允許的安全漏洞數量上限。	否	如要設定，必須為非負數。	`10`
maxAllowedSeverity	政策允許的最高嚴重程度。	否	必須是 `LOW`、`MEDIUM`、`HIGH` 或 `CRITICAL`。
exemptedCves	不受這項政策限制的 CVE 清單。	是	最多 100 個項目。每個 ID 都必須採用 `CVE-YYYY-NNNN` 格式。如果提供寬限期到期時間，必須是有效時間戳記。無法與「`restrictedCves`」重疊。	`- id: CVE-2024-12345` `gracePeriodExpirationTime: 2027-01-01T00:00:00Z` `- id: CVE-2025-4000`
restrictedCves	這項政策明確禁止的 CVE 清單。	是	最多 100 個項目。每個 ID 都必須採用 `CVE-YYYY-NNNN` 格式。不得與「`exemptedCves`」重疊。	`- CVE-2024-54321` `- CVE-2025-5001`
allowedPackages	允許的套件清單，可能會覆寫其他規則。	是	最多 100 個項目。套件名稱不得留空。不得與「`restrictedPackages`」發生衝突。	`- name: nginx` `version: 1.0` `- name: python` `version: 3.12.4`
restrictedPackages	明確禁止的套件清單。	是	最多 100 個項目。套件名稱不得留空。不得與「`allowedPackages`」發生衝突。	`- name: npm` `version: 9.0.0`
excludeUnfixable	是否要排除沒有可用修正程式的安全漏洞。	否	布林值。預設值為 `false`。	`true`
exemptionDaysPostDisclosure	揭露日期後，可豁免安全漏洞的天數。	否	如要設定，必須為非負數。預設值為 `0`。	`30`

政策範圍

管道範圍

名稱	說明	必要	限制	範例值
connectorIds	政策在 CI/CD 管道掃描期間適用的連接器 ID 清單。	是	最少 1 個項目，最多 100 個項目。貴機構或專案必須完成 CI/CD 掃描的導入程序。每個 ID 都必須採用正確格式、屬於您的機構或專案，且指向現有連接器。	`organizations/123/locations/global/connectors/connector-1` `projects/123/locations/global/connectors/connector-1`
enforcementAction	違反政策時採取的動作。	是	必須是 `AUDIT_ONLY` 或 `BLOCK_BUILD`。	`BLOCK_BUILD`

登錄範圍

名稱	說明	必要	限制	範例值
projectIds	政策適用的專案 ID 清單。	否	至少 1 項。每個 ID 都必須是有效的 Google Cloud 專案 ID。	`projects/123, projects/456`
garRepositoryNamePatterns	Artifact Registry 存放區名稱模式清單。 Google Cloud	否	最多 100 個項目。必須是有效的 Google Cloud Artifact Registry 存放區模式。	`us-west1-docker.pkg.dev/my-project/my-repo, gcr.io/team-a/*`
imageNamePatterns	完整符合資格的圖片名稱的規則運算式模式。	否	最多 100 個項目。必須是有效的規則運算式。	`'my-repo/service-a:.', 'my-repo/service-b:v1..'`
enforcementAction	違反政策時採取的動作。	是	必須是 `AUDIT_ONLY` 或 `ADMISSION_CONTROL`。	`ADMISSION_CONTROL`
admissionControl	准入控制的設定詳細資料。	否	如果 `enforcementAction` 為 `ADMISSION_CONTROL`，則必須提供此欄位。

執行階段範圍

透過執行階段範圍，構件防護機制可主動監控 GKE 環境中執行的容器映像檔。將政策套用至這個範圍後，系統會自動使用政策中繼資料，強化在指定專案或叢集中部署的映像檔，並提供 Security Command Center 弱點發現項目。

名稱	說明	必要	限制	範例值
projectIds	已部署 GKE 叢集並啟用安全漏洞評估功能的專案 ID 清單。	是	必須在機構層級選取。	`projects/my-gke-deployment-123`
gkeClusterNames	需要評估政策的特定 GKE 叢集。	否	可在機構或專案層級選取。	`projects/prod-env/locations/us-central1/clusters/main-cluster`

如果受監控的 GKE 叢集中執行的容器映像檔違反政策，系統會將 ArtifactGuardPolicies 中繼資料新增至 Security Command Center 漏洞發現訊息，如下所示：

// Added to the SCC 'message Finding'
ArtifactGuardPolicies artifact_guard_policies = X;

message ArtifactGuardPolicies {
  string resource_id = 1;     // e.g., //us-docker.pkg.dev/google-samples/containers/gke/security/...
  repeated Policy failing_policies = 2;
}

message Policy {
  enum Type {
    TYPE_UNSPECIFIED = 0;
    VULNERABILITY = 1;
  }
  Type type = 1;
  string policy_id = 2;     // e.g., organizations/3392779/locations/global/policies/prod-policy
  string failure_reason = 3;     // e.g., severity=HIGH AND max_vuln_count=2
}

違規處置

如果是 BLOCK_BUILD 和 BLOCK_DEPLOYMENT 動作，政策評估會傳回建議的違規處置。不過，您必須使用這項建議，在管道設定中設定實際的強制執行作業。

刪除政策

有效政策無法刪除，否則會導致FAILED_PRECONDITION錯誤。如要刪除政策，請先將政策狀態設為 Inactive。

常見錯誤

下表列出一些常見錯誤和解決方法。

錯誤訊息提示	原因	解決方法
必須提供父項	要求中缺少父項欄位。	請使用下列其中一種格式提供有效父項： `organizations/{org_id}/locations/global` `parents/{project_number}/locations/global` 。
必須提供政策定義	要求中缺少政策物件。	在要求中提供有效的政策物件。
顯示名稱的長度上限為...	顯示名稱超過 63 個半形字元。	請將顯示名稱長度縮短至 63 個半形字元以內。
說明長度上限為...	說明超過 2,048 個字元。	請將說明長度縮短至 2048 個半形字元以內。
必須提供政策類型	要求中缺少政策類型 (例如 `vulnerabilityPolicy`)。	在政策中新增 `vulnerabilityPolicy` 或其他政策類型。
啟用狀態無效	使用了無效或已淘汰的啟用狀態。	使用 `ACTIVE` 或 `INACTIVE`。
必須指定範圍	未定義任何範圍 (管道、登錄或執行階段)。	在政策中新增至少一個有效範圍。
CVE 名稱的格式必須為...	`exemptedCves` 或 `restrictedCves` 中的 CVE ID 無效。	確認所有 CVE ID 均採用 `CVE-YYYY-NNNN` 格式。
CVE ... cannot be exempted and restricted	`exemptedCves` 和 `restrictedCves` 中都有相同的 CVE ID。	請從其中一份清單中移除 CVE。
套件名稱不得留空	`allowedPackages` 或 `restrictedPackages` 中的套件名稱空白。	為所有套件提供名稱。
package ... cannot be allowed and restricted	`allowedPackages` 和 `restrictedPackages` 中列出相同的套件。	請從其中一份清單中移除此套件。
必須提供連接器 ID	Pipeline 範圍缺少「`connectorIds`」欄位。	至少提供一個連接器 ID。
連接器 ID 的格式須為...	連接器 ID 格式有誤。	請確認 ID 採用下列其中一種格式： `organizations/{org_id}/locations/global/connectors/{connector_id}` 。 `projects/{project_number}/locations/{location}/connectors/{connector_id}`
連接器 ID ... 不存在	指定的連接器 ID 不存在。	確認連接器是否存在，或從清單中移除。
GAR 存放區名稱模式必須...	在登錄範圍中提供的存放區模式無效。	確認模式符合有效的 Google Cloud Artifact Registry 存放區格式。
專案 ID 必須是有效的 GCP 專案 ID...	在登錄或執行階段範圍中提供的專案 ID 無效。	提供有效的 Google Cloud 專案 ID。
應指定強制執行動作	Pipeline 或 Runtime 範圍缺少 `enforcementAction`。	設定強制執行動作 (例如 `AUDIT_ONLY, BLOCK_BUILD` (僅限管道) 或 `BLOCK_DEPLOYMENT` (僅限執行階段))。
每個機構的政策數量超出上限...	貴機構的政策數量已達上限 (1000 項)。	請先刪除未使用的政策，再建立新政策。
number of vulnerability policies ... exceeds the limit...	您已達到安全漏洞政策數量上限 (500 項)。	請先刪除未使用的安全漏洞政策，再建立新政策。
每個管道的政策數量超出上限...	連接器與超過 100 項政策相關聯。	減少與連接器相關聯的政策數量。
政策修訂次數超過上限...	您在 7 天內更新政策超過 100 次。	等待或降低更新頻率。

常見營運問題

除了政策內容驗證失敗，底層的Google Cloud 控制層也可能發生問題。這些問題可能會影響 API 要求、長時間執行的作業和資源狀態，通常會以特定錯誤碼或異常行為的形式呈現。

問題	症狀	如何排解問題
並行修改	`UpdatePolicy` 或 `DeletePolicy` 失敗，並傳回 `ABORTED` 錯誤代碼和 `"Provided etag is out of date"` 訊息。	疑難排解：如果要求中的 `etag` 與政策的目前伺服器版本不符，表示另一個要求已進行修改，就會發生這種情況。解決方法：請重新閱讀政策，取得最新的 etag，然後使用新的 etag 重試要求。
要求已驗證，但未執行	`CreatePolicy`、`UpdatePolicy` 或 `DeletePolicy` 要求成功傳回，但您發現資源沒有任何變更。	疑難排解：如果要求中設定了 `validate_only: true`，通常就會發生這種情況。這個旗標會指示服務執行所有驗證，但不提交任何變更。解決方法：將 `validate_only` 設為 `false`，或在要求中省略該欄位。
更新會建立新政策	如果政策不存在，`UpdatePolicy` 要求會建立政策，而不是傳回「找不到」錯誤。	疑難排解：如果 `allow_missing: true` 包含在 `UpdatePolicyRequest` 中，這是預期行為。解決方法：如要更新現有政策，請將 `allow_missing` 設為 `false`，或省略該欄位。
權限遭拒或 API 未啟用	要求失敗，並顯示 `PERMISSION_DENIED` 或 `"Artifact Guard API has not been used in the project before or it is disabled."` 等錯誤訊息	疑難排解：API 可能已停用，或呼叫者可能沒有足夠的權限。解決方法：在 Google Cloud 專案中，啟用 Artifact Guard API (`artifactscanguard.googleapis.com`)。確認執行作業的使用者或服務帳戶具備必要的 IAM 角色。
作業逾時	傳回長時間執行的作業 (LRO) 的要求完成時間過長，或因 `DEADLINE_EXCEEDED` 而失敗。	疑難排解：這可能表示後端服務暫時變慢或發生問題。解決方式：輪詢 LRO 狀態。如果失敗或逾時，請稍候片刻再試一次。如果問題仍未解決，請查看Google Cloud 狀態資訊主頁是否有任何進行中的事件，或與 Google Cloud 支援團隊聯絡。