Configurar a localidade de 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, 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 compatível. Seus dados podem ser tratados fora da região em que são armazenados.

  • Endpoint regional: um endpoint de serviço que impõe restrições regionais, garantindo que os dados sejam armazenados, transmitidos e tratados 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 eles estão armazenados.

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

    • É necessário obedecer às políticas ou regulamentações de localidade de dados que exigem o tratamento dos dados no mesmo local em que eles são armazenados.

Os dados de atestações e de procedência do build são armazenados no endpoint global. Os resultados da verificação de vulnerabilidades e os dados da lista de materiais de software (SBOM, na sigla em inglês) são armazenados em endpoints regionais e multirregionais.

Locais que oferecem suporte a endpoints regionais

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

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

Para conferir uma lista de regiões compatíveis e os endpoints de serviço disponíveis em cada uma delas, consulte Locais de armazenamento de metadados.

Comandos da Google Cloud CLI

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

  • Use a sinalização --location.
  • Defina o endpoint regional padrão que você quer usar para 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 ofereça suporte a um endpoint regional, o comando usará o endpoint global.

Por exemplo, o comando a seguir lista 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 não precisar 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 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

Usar um endpoint regional para métodos de API

Especifique o endpoint regional em vez do global. Por exemplo, o código 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 seus metadados estão armazenados.
  • PROJECT_ID: o ID do projeto do seu Google Cloud projeto.

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 regional de metadados, as ocorrências e observações 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 globais da API

Para ajudar a aplicar o uso de endpoints regionais, use 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