Configurare la località dei dati utilizzando gli endpoint regionali

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 ha endpoint sia globali che regionali.

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

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

    containeranalysis.region.rep.googleapis.com.

    Prendi in considerazione l'utilizzo di endpoint regionali nelle seguenti situazioni:

    • L'applicazione che deve accedere ai tuoi dati non è geograficamente vicina alla regione in cui sono archiviati i tuoi dati.

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

    • Devi rispettare le policy o i regolamenti sulla località dei dati che richiedono l'elaborazione dei dati nella stessa località in cui sono archiviati.

Le attestazioni e i dati di provenienza della build vengono archiviati nell'endpoint globale. I risultati dell'analisi delle vulnerabilità e i dati SBOM vengono archiviati in 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 le multiregioni 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 Località 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 comandi di Artifact Analysis.

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

Imposta 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 sostituzioni seguenti:

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

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 allo spazio di archiviazione dei metadati regionale, le occorrenze e le note non includevano un nome della località nei relativi 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 era simile a questo esempio:

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

La stessa occorrenza archiviata 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 delle policy dell'organizzazione constraints/gcp.restrictEndpointUsage per bloccare le richieste all'endpoint API globale. Per saperne di più, consulta Limita l'utilizzo degli endpoint.

Passaggi successivi