Configura la località dei dati utilizzando gli endpoint a livello di regione

Questa pagina descrive gli endpoint di servizio globali e regionali di Artifact Analysis e come utilizzarli.

Un endpoint di servizio è un URL di base che specifica l'indirizzo di rete di un servizio API. Artifact Analysis dispone di endpoint globali e regionali.

  • Endpoint globale: per impostazione predefinita, Artifact Analysis invia richieste API all'endpoint globale containeranalysis.googleapis.com. Gli endpoint globali non garantiscono che i dati in transito rimangano in una posizione specifica e possono recuperare i dati di Artifact Analysis da qualsiasi regione supportata. I tuoi dati potrebbero essere trattati al di fuori della regione in cui sono archiviati.

  • Endpoint regionale: un endpoint di servizio che applica restrizioni regionali, garantendo che i dati vengano archiviati, trasmessi ed elaborati in una regione specificata. Un endpoint regionale consente l'elaborazione delle richieste solo se la risorsa interessata esiste nella località specificata dall'endpoint. Gli endpoint regionali utilizzano il seguente formato:

    containeranalysis.region.rep.googleapis.com.

    Valuta l'utilizzo di endpoint regionali nelle seguenti situazioni:

    • L'applicazione che deve accedere ai tuoi dati non si trova in una posizione geografica vicina alla regione in cui sono archiviati i dati.

    • Archivi i dati in più posizioni e vuoi ottimizzare la latenza, l'affidabilità e la disponibilità.

    • Devi rispettare le norme o i regolamenti sulla località dei dati che richiedono di elaborare i dati nella stessa posizione in cui sono archiviati.

I dati di attestazione e di provenienza della build vengono archiviati nell'endpoint globale. I risultati della scansione delle vulnerabilità e i dati SBOM vengono archiviati negli endpoint regionali e multiregionali.

Località che supportano gli endpoint regionali

Puoi utilizzare gli endpoint regionali per la maggior parte delle regioni supportate da Artifact Analysis.

Per più regioni e alcune regioni, Artifact Analysis supporta solo l'endpoint globale.

Per un elenco delle regioni supportate e degli endpoint di servizio supportati per ogni regione, consulta Posizioni di archiviazione dei metadati.

Comandi di Google Cloud CLI

Quando utilizzi gcloud CLI, esistono due modi per inviare richieste all'endpoint regionale:

  • Utilizza il flag --location.
  • Imposta l'endpoint regionale predefinito che vuoi utilizzare per i comandiArtifact Analysisi.

Utilizza il flag --location

Puoi utilizzare il flag --location con uno dei seguenti comandi per indirizzare la richiesta all'endpoint di servizio appropriato:

Per elaborare correttamente la richiesta con un endpoint regionale, la località specificata deve soddisfare i seguenti requisiti:

Se ometti il flag --location o specifichi una località che non supporta un endpoint regionale, il comando utilizza l'endpoint globale.

Ad esempio, il seguente comando elenca le vulnerabilità di un'immagine archiviata in us-east1:

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

Impostare un endpoint predefinito per i comandi

Per impostazione predefinita, i comandi gcloud CLI utilizzano l'endpoint globale. Puoi impostare un endpoint regionale predefinito per i comandi di Artifact Analysis in modo da non dover specificare la località nei singoli comandi.

Assicurati di utilizzare gcloud CLI 402.0.0 o versioni successive.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • LOCATION: la regione in cui sono archiviati i metadati.

Esegui questo comando:

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

Utilizza un endpoint regionale per i metodi API

Specifica l'endpoint regionale anziché quello globale. Ad esempio, l'esempio seguente elenca le occorrenze nella regione specificata.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • LOCATION: la regione in cui sono archiviati i metadati.
  • PROJECT_ID: l'ID progetto del tuo Google Cloud progetto.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima della transizione all'archiviazione dei metadati a livello regionale, le occorrenze e le note non includevano un nome di località nei loro identificatori. Poiché le scansioni più recenti archiviano i metadati nelle regioni, le richieste API che utilizzano endpoint globali o regionali restituiscono risultati che includono identificatori di località.

Un identificatore di occorrenza prima della transizione aveva questo aspetto:

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

La stessa occorrenza memorizzata in us-east1 ha il seguente aspetto:

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

Limita l'utilizzo degli endpoint API globali

Per contribuire a imporre l'utilizzo di endpoint regionali, utilizza il vincolo del criterio dell'organizzazione constraints/gcp.restrictEndpointUsage per bloccare le richieste all'endpoint API globale. Per ulteriori informazioni, vedi Limitare l'utilizzo degli endpoint.

Passaggi successivi