Configure a localidade dos dados através de pontos finais regionais

Esta página descreve os pontos finais de serviço globais e regionais da análise de artefactos e como usá-los.

Um ponto final de serviço é um URL de base que especifica o endereço de rede de um serviço de API. A análise de artefactos tem pontos finais globais e regionais.

  • Ponto final global: por predefinição, a Artifact Analysis envia pedidos de API para o ponto final global, containeranalysis.googleapis.com. Os pontos finais globais não garantem que os dados em trânsito permaneçam numa localização específica e podem obter dados da Análise de artefactos de qualquer região suportada. Os seus dados podem ser processados fora da região onde são armazenados.

  • Ponto final regional: um ponto final de serviço que aplica restrições regionais, garantindo que os dados são armazenados, transmitidos e tratados numa região especificada. Um ponto final regional só permite que os pedidos prossigam se o recurso afetado existir na localização especificada pelo ponto final. Os pontos finais regionais usam o seguinte formato:

    containeranalysis.region.rep.googleapis.com.

    Considere usar pontos finais regionais nas seguintes situações:

    • A aplicação que precisa de aceder aos seus dados não está geograficamente perto da região onde os seus dados estão armazenados.

    • Está a armazenar dados em várias localizações e quer otimizar a latência, a fiabilidade e a disponibilidade.

    • Tem de agir em conformidade com as políticas ou os regulamentos de localização de dados que exigem que processe os seus dados na mesma localização onde os dados são armazenados.

As atestações e os dados de proveniência da compilação são armazenados no ponto final global. Os resultados da análise de vulnerabilidades e os dados da SBOM são armazenados em pontos finais regionais e multirregionais.

Localizações que suportam pontos finais regionais

Pode usar pontos finais regionais para a maioria das regiões suportadas pelo Artifact Analysis.

Para várias regiões e algumas regiões, a análise de artefactos só suporta o ponto final global.

Para ver uma lista das regiões suportadas e os pontos finais de serviço suportados para cada região, consulte Localizações de armazenamento de metadados.

Comandos da CLI do Google Cloud

Quando usa a CLI gcloud, existem duas formas de enviar pedidos para o ponto final regional:

  • Use a flag --location.
  • Defina o ponto final regional predefinido que quer usar para os comandos de análise de artefactos.

Use a flag --location

Pode usar a flag --location com um dos seguintes comandos para direcionar o pedido para o ponto final do serviço adequado:

Para processar com êxito o pedido com um ponto final regional, a localização especificada tem de cumprir os seguintes requisitos:

Se omitir a flag --location ou especificar uma localização que não suporte um ponto final regional, o comando usa o ponto final global.

Por exemplo, o comando seguinte lista as vulnerabilidades de uma imagem armazenada em us-east1:

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

Defina um ponto final predefinido para comandos

Por predefinição, os comandos da CLI gcloud usam o ponto final global. Pode definir um ponto final regional predefinido para os comandos de análise de artefactos, para que não tenha de especificar a localização em comandos individuais.

Certifique-se de que está a usar a CLI gcloud 402.0.0 ou mais recente.

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • LOCATION: a região onde os seus metadados estão armazenados.

Execute o seguinte comando:

Linux, macOS ou 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

Use um ponto final regional para métodos da API

Especifique o ponto final regional em vez do ponto final global. Por exemplo, o exemplo seguinte lista ocorrências na região especificada.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION: a região onde os seus metadados estão armazenados.
  • PROJECT_ID: o ID do projeto do seu projeto Google Cloud .

Método HTTP e URL: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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
    ...
  }

Antes da transição para o armazenamento de metadados regionais, as ocorrências e as notas não incluíam um nome de localização nos respetivos identificadores. À medida que as análises mais recentes armazenam metadados nas regiões, os pedidos de API que usam pontos finais globais ou regionais devolvem resultados que incluem identificadores de localização.

Um identificador de ocorrência antes da transição tinha o seguinte aspeto:

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

A mesma ocorrência armazenada em us-east1 tem o seguinte aspeto:

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

Restrinja a utilização do ponto final da API global

Para ajudar a aplicar a utilização de pontos finais regionais, use a restrição da política da organização constraints/gcp.restrictEndpointUsage para bloquear pedidos ao ponto final da API global. Para mais informações, consulte o artigo Restringir a utilização de pontos finais.

O que se segue?