Configurar la localidad de los datos mediante puntos finales regionales

En esta página se describen los endpoints de servicio globales y regionales de Análisis de artefactos, así como la forma de usarlos.

Un endpoint de servicio es una URL base que especifica la dirección de red de un servicio de API. Artifact Analysis tiene endpoints globales y regionales.

  • Endpoint global: de forma predeterminada, Artifact Analysis envía solicitudes de API al endpoint global, containeranalysis.googleapis.com. Los endpoints globales no garantizan que los datos en tránsito permanezcan en una ubicación concreta y pueden recuperar datos de análisis de artefactos de cualquier región admitida. Es posible que tus datos se traten fuera de la región en la que se almacenan.

  • Punto de conexión regional: un punto de conexión de servicio que aplica restricciones regionales para asegurar que los datos se almacenen, transmitan y procesen en una región específica. Un endpoint regional solo permite que se procesen las solicitudes si el recurso afectado se encuentra en la ubicación especificada por el endpoint. Los puntos finales regionales usan el siguiente formato:

    containeranalysis.region.rep.googleapis.com.

    Te recomendamos que uses los endpoints regionales en las siguientes situaciones:

    • La aplicación que necesita acceder a tus datos no está cerca geográficamente de la región en la que se almacenan tus datos.

    • Almacenas datos en varias ubicaciones y quieres optimizar la latencia, la fiabilidad y la disponibilidad.

    • Debes cumplir las políticas o normativas de localización de datos que te exigen tratar los datos en la misma ubicación en la que se almacenan.

Las certificaciones y los datos de procedencia de la compilación se almacenan en el endpoint global. Los resultados de los análisis de vulnerabilidades y los datos de la lista de materiales de software se almacenan en endpoints regionales y multirregionales.

Ubicaciones que admiten puntos finales regionales

Puedes usar endpoints regionales en la mayoría de las regiones que admite Artifact Analysis.

En el caso de las multirregiones y algunas regiones, Artifact Analysis solo admite el endpoint global.

Para ver una lista de las regiones admitidas y los endpoints de servicio que se admiten en cada región, consulta Ubicaciones de almacenamiento de metadatos.

Comandos de la CLI de Google Cloud

Cuando usas gcloud CLI, hay dos formas de enviar solicitudes al endpoint regional:

  • Usa la marca --location.
  • Define el endpoint regional predeterminado que quieras usar para los comandos de análisis de artefactos.

Usar la marca --location

Puedes usar la marca --location con uno de los siguientes comandos para dirigir la solicitud al endpoint de servicio adecuado:

Para procesar correctamente la solicitud con un endpoint regional, la ubicación especificada debe cumplir los siguientes requisitos:

Si omite la marca --location o especifica una ubicación que no admite un endpoint regional, el comando usará el endpoint global.

Por ejemplo, el siguiente comando muestra las vulnerabilidades de una imagen almacenada en us-east1:

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

Definir un endpoint predeterminado para los comandos

De forma predeterminada, los comandos de gcloud CLI usan el endpoint global. Puedes definir un endpoint regional predeterminado para los comandos de análisis de artefactos de forma que no tengas que especificar la ubicación en los comandos individuales.

Asegúrate de que usas la CLI de gcloud 402.0.0 o una versión posterior.

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

  • LOCATION: la región en la que se almacenan tus metadatos.

Ejecuta el siguiente 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

Usar un endpoint regional para los métodos de la API

Especifica el endpoint regional en lugar del global. Por ejemplo, el siguiente ejemplo muestra las incidencias de la región especificada.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION: la región en la que se almacenan tus metadatos.
  • PROJECT_ID: el ID del proyecto de Google Cloud .

Método HTTP y URL: 

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

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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 de la transición al almacenamiento de metadatos regionales, las incidencias y las notas no incluían el nombre de una ubicación en sus identificadores. Como los análisis más recientes almacenan metadatos en regiones, las solicitudes a la API que usan endpoints globales o regionales devuelven resultados que incluyen identificadores de ubicación.

Un identificador de ocurrencia antes de la transición tenía este aspecto:

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

La misma ocurrencia almacenada en us-east1 tiene este aspecto:

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

Restringir el uso de endpoints de API globales

Para ayudar a aplicar el uso de endpoints regionales, usa la restricción de política de organización constraints/gcp.restrictEndpointUsage para bloquear las solicitudes al endpoint de la API global. Para obtener más información, consulta Restringir el uso de endpoints.

Siguientes pasos