Datenlokalität mit regionalen Endpunkten konfigurieren

Auf dieser Seite werden die globalen und regionalen 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 übertragene Daten an einem bestimmten Standort bleiben, 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 Ort verarbeiten, an dem die Daten gespeichert sind.

Attestierungen und Daten zur Build-Herkunft werden im globalen Endpunkt gespeichert. Die Ergebnisse des Scans auf Sicherheitslücken und die 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 multiregionale und einige regionale Standorte unterstützt Artefaktanalyse nur den globalen Endpunkt.

Eine Liste der unterstützten Regionen und der für die einzelnen Regionen unterstützten Dienstendpunkte 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 regionalen Standardendpunkt fest, den Sie für Artefaktanalyse-Befehle verwenden möchten.

Verwenden Sie das Flag --location.

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 erfolgreich 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 Image 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 regionalen Standardendpunkt 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 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

Regionale Endpunkte 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 Projekts in Google Cloud .

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 die Kennungen von Vorkommen und Hinweisen keinen Standortnamen. Da neuere Scans Metadaten in Regionen speichern, geben API-Anfragen, die entweder globale oder regionale Endpunkte verwenden, Ergebnisse zurück, die Standortkennungen enthalten.

Eine Ereignis-ID vor der Umstellung sah so aus:

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

Dasselbe in us-east1 gespeicherte Vorkommen sieht so aus:

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

Nutzung globaler API-Endpunkte 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