Datenlokalität mit regionalen Endpunkten konfigurieren

Auf dieser Seite werden globale und regionale Dienstendpunkte von Artefaktanalyse und ihre Verwendung beschrieben.

Ein Dienstendpunkt ist eine Basis-URL, die die Netzwerkadresse eines API-Dienstes angibt. Artefaktanalyse hat sowohl globale als auch regionale Endpunkte.

  • Globaler Endpunkt: Standardmäßig sendet Artefaktanalyse API-Anfragen an den globalen Endpunkt containeranalysis.googleapis.com. Globale Endpunkte garantieren nicht, dass Daten während der Übertragung an einem bestimmten Standort verbleiben, und können Artefaktanalyse-Daten aus jeder unterstützten Region abrufen. Ihre Daten werden möglicherweise außerhalb der Region verarbeitet, in der sie gespeichert sind.

  • Regionaler Endpunkt: Ein Dienstendpunkt, der regionale Einschränkungen erzwingt, damit Daten in einer bestimmten Region gespeichert, übertragen und verarbeitet werden. Ein regionaler Endpunkt lässt nur Anfragen zu, wenn die betroffene Ressource am vom Endpunkt angegebenen Standort vorhanden ist. Regionale Endpunkte haben das folgende Format:

    containeranalysis.region.rep.googleapis.com.

    In den folgenden Situationen sollten Sie regionale Endpunkte verwenden:

    • Die Anwendung, die auf Ihre Daten zugreifen muss, befindet sich nicht in der Nähe der Region, in der Ihre Daten gespeichert sind.

    • Sie speichern Daten an mehreren Standorten und möchten Latenz, Zuverlässigkeit und Verfügbarkeit optimieren.

    • Sie müssen Richtlinien oder Vorschriften zur Datenlokalität einhalten, die vorschreiben, dass Sie Ihre Daten am selben Standort verarbeiten, an dem sie gespeichert sind.

Attestierungen und Daten zur Build-Herkunft werden am globalen Endpunkt gespeichert. Ergebnisse von Sicherheitslückenscans und SBOM-Daten werden an regionalen und multiregionalen Endpunkten gespeichert.

Standorte, die regionale Endpunkte unterstützen

Sie können regionale Endpunkte für die meisten Regionen verwenden, die von Artefaktanalyse unterstützt werden.

Für Multiregionen und einige Regionen unterstützt Artefaktanalyse nur den globalen Endpunkt.

Eine Liste der unterstützten Regionen und der Dienstendpunkte, die für jede Region unterstützt werden , finden Sie unter Speicherorte für Metadaten.

Google Cloud CLI-Befehle

Wenn Sie die gcloud CLI verwenden, gibt es zwei Möglichkeiten, Anfragen an den regionalen Endpunkt zu senden:

  • Verwenden Sie das Flag --location.
  • Legen Sie den standardmäßigen regionalen Endpunkt fest, den Sie für Artefaktanalyse-Befehle verwenden möchten.

Flag --location verwenden

Sie können das Flag --location mit einem der folgenden Befehle verwenden, um die Anfrage an den entsprechenden Dienstendpunkt weiterzuleiten:

Damit die Anfrage mit einem regionalen Endpunkt verarbeitet werden kann, muss der angegebene Standort die folgenden Anforderungen erfüllen:

Wenn Sie das Flag --location weglassen oder einen Standort angeben, der keinen regionalen Endpunkt unterstützt, verwendet der Befehl den globalen Endpunkt.

Mit dem folgenden Befehl werden beispielsweise Sicherheitslücken für ein Bild aufgelistet, das in us-east1 gespeichert ist:

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

Standardendpunkt für Befehle festlegen

Standardmäßig verwenden die gcloud CLI-Befehle den globalen Endpunkt. Sie können einen standardmäßigen regionalen Endpunkt für Artefaktanalyse-Befehle festlegen, damit Sie den Standort nicht in einzelnen Befehlen angeben müssen.

Achten Sie darauf, dass Sie die gcloud CLI 402.0.0 oder höher verwenden.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • LOCATION: die Region, in der Ihre Metadaten gespeichert sind.

Führen Sie den folgenden Befehl aus:

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

Regionalen Endpunkt für API-Methoden verwenden

Geben Sie den regionalen Endpunkt anstelle des globalen Endpunkts an. Im folgenden Beispiel werden Vorkommen in der angegebenen Region aufgelistet.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • LOCATION: die Region, in der Ihre Metadaten gespeichert sind.
  • PROJECT_ID: die Projekt-ID Ihres Google Cloud Projekts.

HTTP-Methode und URL: 

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Vor der Umstellung auf die regionale Metadatenspeicherung enthielten Vorkommen und Hinweise keinen Standortnamen in ihren IDs. Da bei neueren Scans Metadaten in Regionen gespeichert werden, enthalten API-Anfragen mit globalen oder regionalen Endpunkten Ergebnisse mit Standort-IDs.

Eine Vorkommens-ID vor der Umstellung sah so aus:

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

Dasselbe Vorkommen, das in us-east1 gespeichert ist, sieht so aus:

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

Nutzung globaler API-Endpunkt einschränken

Um die Verwendung regionaler Endpunkte zu erzwingen, können Sie die Einschränkung der Organisationsrichtlinie constraints/gcp.restrictEndpointUsage verwenden, um Anfragen an den globalen API-Endpunkt zu blockieren. Weitere Informationen finden Sie unter Endpunktnutzung einschränken.

Nächste Schritte