使用区域端点配置数据本地性

本页介绍了 Artifact Analysis 的全球和区域服务端点,以及如何使用这些端点。

服务端点是指定 API 服务的网络地址的基本网址。Artifact Analysis 具有全球和区域性端点。

  • 全球端点:默认情况下,Artifact Analysis 会将 API 请求发送到全球端点 containeranalysis.googleapis.com。全球端点无法保证传输中的数据会保留在特定位置,并且可以从任何受支持的区域检索 Artifact Analysis 数据。您的数据可能会在存储区域以外的区域进行处理。

  • 区域性端点:一种服务端点,可强制执行区域限制,确保在指定区域存储、传输和处理数据。只有在受影响的资源存在于端点指定的位置时,区域端点才允许请求继续。区域端点采用以下格式:

    containeranalysis.region.rep.googleapis.com

    在以下情况下,请考虑使用区域端点:

    • 需要访问您数据的应用与数据存储区域的地理位置相距较远。

    • 您将数据存储在多个位置,并希望优化延迟时间、可靠性和可用性。

    • 您需要遵守数据存放区域政策或法规,这些政策或法规要求您在数据存储位置处理数据。

证明和 build 来源数据存储在全局端点中。 漏洞扫描结果和 SBOM 数据存储在区域性端点和多区域性端点中。

支持区域级端点的位置

您可以针对 Artifact Analysis 支持的大多数区域使用区域性端点。

对于多区域和某些区域,Artifact Analysis 仅支持全球端点。

如需查看支持的区域以及每个区域支持的服务端点列表,请参阅元数据存储位置

Google Cloud CLI 命令

使用 gcloud CLI 时,您可以通过以下两种方式向区域级端点发送请求:

  • 使用 --location 标志。
  • 设置要用于 Artifact Analysis 命令的默认区域端点。

使用 --location 标志

您可以将 --location 标志与以下任一命令搭配使用,以将请求定向到相应的服务端点:

如需通过区域级端点成功处理请求,指定的位置必须满足以下要求:

如果您省略 --location 标志或指定不支持区域端点的位置,则该命令会使用全球端点。

例如,以下命令会列出存储在 us-east1 中的映像的漏洞:

gcloud artifacts vulnerabilities list --location=us-east1 us-east1-docker.pkg.dev/my-project/my-repo/my-image@sha256:49765698074d6d7baa82f

为命令设置默认端点

默认情况下,gcloud CLI 命令使用全球端点。您可以为 Artifact Analysis 命令设置默认的区域端点,这样您就不需要在各个命令中指定位置。

确保您使用的是 gcloud CLI 402.0.0 或更高版本。

在使用下面的命令数据之前,请先进行以下替换:

  • LOCATION:存储元数据的区域

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com

Windows (PowerShell)

gcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com

Windows (cmd.exe)

gcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com

为 API 方法使用区域端点

指定区域端点,而不是全球端点。例如,以下示例列出了指定区域中的事件。

在使用任何请求数据之前,请先进行以下替换:

  • LOCATION:存储元数据的区域
  • PROJECT_ID:您的 Google Cloud 项目的项目 ID。

HTTP 方法和网址:

GET https://containeranalysis.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/occurrences

如需发送您的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

occurrences: [
  {
    name: "projects/my-project/locations/us-east1/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f"
    resource_uri: "https://us-east1-docker.pkg.dev/my-project/my-repo/my-image@sha256:b487c4da45ce363eef69d9c066fa26f6666e4f3c9c414d98d1e27bfcc949e544"
    note_name: "projects/goog-vulnz/locations/us-east1/notes/CVE-2018-1272"
    kind: VULNERABILITY
    ...
  }

在过渡到区域元数据存储之前,事件和备注的标识符中不包含位置名称。由于较新的扫描结果将元数据存储在区域中,因此使用全局端点或区域端点的 API 请求都会返回包含位置标识符的结果。

过渡之前的出现标识符如下例所示:

name: "projects/my-project/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f"

存储在 us-east1 中的同一事件如下所示:

name: "projects/my-project/locations/us-east1/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f"

限制全球 API 端点用量

为了帮助强制使用区域端点,请使用 constraints/gcp.restrictEndpointUsage 组织政策限制条件来阻止对全球 API 端点的请求。如需了解详情,请参阅限制端点使用

后续步骤