Configurar a localidade dos dados usando endpoints regionais

Nesta página, descrevemos 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, o 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 recuperar dados do Artifact Analysis de qualquer região com disponibilidade. 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 da região em que os dados 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 seus dados no mesmo local em que eles estão armazenados.

Os atestados e os dados de procedência do build são armazenados no endpoint global. Os resultados da verificação de vulnerabilidades e os dados da SBOM são armazenados em endpoints regionais e multirregionais.

Regiões com disponibilidade que aceitam endpoints regionais

É possível usar endpoints regionais para a maioria das regiões compatíveis com o Artifact Analysis.

Para multirregiões e algumas regiões, o Artifact Analysis só é compatível com o endpoint global.

Para uma lista de regiões com suporte e os endpoints de serviço compatíveis com 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 do Artifact Analysis.

Use a sinalização --location.

Use 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 seja compatível com um endpoint regional, o comando 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, de modo 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 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

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 estã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 regional, as ocorrências e as 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 era assim:

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"

Restringir o uso de endpoints de API globais

Para ajudar a aplicar o uso de endpoints regionais, utilize a restrição de política da organização constraints/gcp.restrictEndpointUsage para bloquear solicitações ao endpoint de API global. Para mais informações, consulte Restringir o uso de endpoints.

A seguir