Configurar a localidade de dados usando endpoints regionais

Esta página descreve os endpoints de serviço globais e regionais do Artifact Analysis e como usá-los.

Um endpoint de serviço é um URL de base que especifica o endereço de rede de um serviço de API. O Artifact Analysis tem endpoints globais e regionais.

  • Endpoint global: por padrão, a Artifact Analysis envia solicitações de API para o endpoint global, containeranalysis.googleapis.com. Os endpoints globais não garantem que os dados em trânsito permaneçam em um local específico e podem extrair dados do Artifact Analysis de qualquer região com suporte. Seus dados podem ser processados fora da região em que estão armazenados.

  • Endpoint regional: um endpoint de serviço que impõe restrições regionais, garantindo que os dados sejam armazenados, transmitidos e processados em uma região especificada. Um endpoint regional só permite que as solicitações prossigam se o recurso afetado existir no local especificado pelo endpoint. Os endpoints regionais usam o seguinte formato:

    containeranalysis.region.rep.googleapis.com

    Considere usar endpoints regionais nas seguintes situações:

    • O aplicativo que precisa acessar seus dados não está geograficamente próximo à região em que eles estão armazenados.

    • Você está armazenando dados em vários locais e quer otimizar a latência, a confiabilidade e a disponibilidade.

    • Você precisa obedecer às políticas ou regulamentações de localidade de dados que exigem que você processe os dados no mesmo local em que eles estão armazenados.

As declarações e os dados de procedência do build são armazenados no endpoint global. Os resultados da verificação de vulnerabilidade e os dados do SBOM são armazenados em endpoints regionais e multirregionais.

Locais com suporte a endpoints regionais

É possível usar endpoints regionais para a maioria das regiões com suporte ao Artifact Analysis.

Para multirregiões e algumas regiões, o Artifact Analysis só oferece suporte ao endpoint global.

Para conferir uma lista de regiões com suporte e os endpoints de serviço com suporte para cada região, consulte Locais de armazenamento de metadados.

Comandos da Google Cloud CLI

Ao usar a CLI gcloud, há duas maneiras de enviar solicitações para o endpoint regional:

  • Use a sinalização --location.
  • Defina o endpoint regional padrão que você quer usar para os comandos Artifact Analysis.

Use a sinalização --location.

É possível usar a flag --location com um dos comandos a seguir para direcionar a solicitação ao endpoint de serviço apropriado:

Para processar a solicitação com um endpoint regional, o local especificado precisa atender aos seguintes requisitos:

Se você omitir a flag --location ou especificar um local que não oferece suporte a um endpoint regional, o comando vai usar o endpoint global.

Por exemplo, o comando a seguir 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

Definir um endpoint padrão para comandos

Por padrão, os comandos da CLI gcloud usam o endpoint global. É possível definir um endpoint regional padrão para comandos do Artifact Analysis para que não seja necessário especificar o local em comandos individuais.

Verifique se você está usando a CLI gcloud 402.0.0 ou uma versão mais recente.

Antes de usar os dados do comando abaixo, faça estas substituições:

  • LOCATION: a região em que os metadados sã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

Usar um endpoint regional para métodos de API

Especifique o endpoint regional em vez do global. Por exemplo, o exemplo a seguir lista ocorrências na região especificada.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: a região em que os metadados são armazenados.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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 notas não incluíam um nome de local nos identificadores. Como as verificações mais recentes armazenam metadados em regiões, as solicitações de API que usam endpoints globais ou regionais retornam resultados que incluem identificadores de local.

Um identificador de ocorrência antes da transição tinha este aspecto:

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

A mesma ocorrência armazenada em us-east1 tem esta aparência:

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

A seguir