Cómo reducir la latencia con el precalentamiento de imágenes

La preparación previa de imágenes te permite activar de forma explícita la descarga de imágenes de contenedor en la caché de transmisión de imágenes antes de que un cliente de entorno de ejecución las solicite. Esto elimina de manera efectiva la latencia de "inicio en frío" asociada con la primera extracción de una nueva versión de imagen para cargas de trabajo que usan la transmisión de imágenes.

Descripción general

Cuando envías una imagen a Artifact Registry, se almacena en un sistema de almacenamiento subyacente. Para el acceso de baja latencia, Artifact Registry también usa una caché de transmisión de imágenes , que suele propagarse en la primera extracción de un cliente que tiene habilitada la transmisión de imágenes. Para las cargas de trabajo sensibles a la latencia, como el escalamiento vertical de un clúster de Google Kubernetes Engine, esperar a que se prepare esta caché puede causar demoras. La preparación previa ayuda a que las imágenes entren en la caché de transmisión de imágenes con anticipación.

La API de Prewarm Artifact te permite solicitar de forma manual que se almacene en caché previamente una etiqueta o versión de imagen específica. También puedes especificar un período de retención para garantizar que la imagen permanezca en la caché durante un período determinado.

Limitaciones

  • Solo API: La preparación previa solo está disponible con la API de REST de Artifact Registry. La preparación previa no está disponible con gcloud CLI la Google Cloud consola.
  • Solo GKE: La preparación previa solo es efectiva para clústeres de GKE con la transmisión de imágenes habilitada. La transmisión de imágenes requiere software específico que se ejecute en el nodo cliente.
  • Artefacto único: Puedes preparar previamente solo un artefacto (versión o etiqueta) por solicitud a la API.
  • Imágenes de varias arquitecturas: No admitido. Usa la versión específica para una imagen de arquitectura.
  • Límite del proyecto: Existe un límite general de 100 GB por proyecto consumidor para las imágenes preparadas previamente. Cuando se alcanza el límite, se expulsan las imágenes más antiguas para dejar espacio para las nuevas.

Antes de comenzar

  1. Habilita la API de Artifact Registry. Para obtener más información, consulta Habilita Artifact Registry.
  2. Instala la gcloud CLI para obtener tokens de autenticación para las solicitudes a la API de REST.

Roles obligatorios

Para obtener los permisos que necesitas para administrar las imágenes preparadas previamente, pídele a tu administrador que te otorgue los siguientes roles de IAM en el repositorio:

  • Prepara previamente o quita artefactos de la caché (artifactregistry.repositories.prewarmArtifact, artifactregistry.repositories.removePrewarmedArtifact): Escritor de Artifact Registry (roles/artifactregistry.writer)
  • Verifica o enumera los artefactos preparados previamente (artifactregistry.repositories.checkPrewarmedArtifact, artifactregistry.repositories.listPrewarmedArtifacts): Lector de Artifact Registry (roles/artifactregistry.reader)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Este modelo de permisos garantiza que solo los usuarios con acceso de escritura puedan administrar el estado de la caché, lo que evita que los usuarios no autorizados la llenen en exceso. Mientras tanto, los usuarios con acceso de lectura pueden verificar qué artefactos están disponibles para la transmisión.

Prepara previamente una imagen

Para preparar previamente una imagen, realiza una solicitud POST al método :prewarmArtifact de tu repositorio.

API de REST

Referencia: projects.locations.repositories.prewarmArtifact

El cuerpo de la solicitud tiene la siguiente estructura:

{
  "version": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/versions/VERSION",
  "retention_days": 3
}

Como alternativa, usa una etiqueta:

{
  "tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG",
  "retention_days": 3,
  "force": true
}
Campo Descripción
tag Opcional. Es la etiqueta de artefacto específica que se preparará previamente. Debes especificar una version o una tag.
version Opcional. Es la versión de artefacto específica que se preparará previamente. Debes especificar una version o una tag.
retention_days Opcional. Es la cantidad de días que se conservará el artefacto en la caché. Si no especificas este campo, el valor predeterminado es de 3 días.
force Opcional. Si el valor es true, el sistema podría expulsar artefactos más antiguos para dejar espacio para este.
stream_location Opcional. Es la región específica en la que se preparará previamente la imagen. De forma predeterminada, coincide con la ubicación de la imagen. Ten en cuenta que no se admiten las configuraciones multirregionales. Si se especifica una región amplia, los valores predeterminados son us-central1 (EE.UU.), europe-north1 (UE) y asia-east1 (Asia).

Ejemplo: Prepara previamente una versión específica

En el siguiente ejemplo, se prepara previamente la versión sha256:52e... del paquete nginx en el repositorio my-repo en la región "us-east1".

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176",
    "retention_days": 7,
    "stream_location": "us-east1",
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

Ejemplo: Prepara previamente una etiqueta

En el siguiente ejemplo, se prepara previamente la imagen etiquetada como production del paquete my-app.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "projects/my-project/locations/us-central1/repositories/my-repo/packages/my-app/tags/production",
    "force": true
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

Verifica el estado de preparación previa

Para verificar si un artefacto se preparó previamente, usa el método :checkPrewarmedArtifact.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:checkPrewarmedArtifact"

Enumera los artefactos preparados previamente

Para enumerar todos los artefactos preparados previamente en un repositorio, usa el método GET en la colección prewarmedArtifacts. En el siguiente ejemplo, se enumeran todas las imágenes preparadas previamente en my-repo en us-east1. Se requiere el filtro stream_location.

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo/prewarmedArtifacts?filter=stream_location=us-east1"/

Quita de la caché

Para quitar de forma explícita un artefacto de la caché de preparación previa, usa el método :removePrewarmedArtifact. Usa este método para liberar espacio o cuando ya no se necesite una versión de imagen específica en la caché.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:removePrewarmedArtifact"

¿Qué sigue?