Reduzir a latência com pré-aquecimento de imagens

O pré-aquecimento de imagens permite acionar explicitamente o download de imagens de contêiner no cache do streaming de imagens antes que um cliente de tempo de execução as solicite. Isso elimina efetivamente a latência de "inicialização a frio" associada ao primeiro pull de uma nova versão de imagem para cargas de trabalho que usam o streaming de imagens.

Visão geral

Quando você envia uma imagem para o Artifact Registry, ela é armazenada em um sistema de armazenamento subjacente. Para acesso de baixa latência, o Artifact Registry também usa um cache de streaming de imagens, que geralmente é preenchido no primeiro pull de um cliente com o streaming de imagens ativado. Para cargas de trabalho sensíveis à latência, como escalonar um cluster do Google Kubernetes Engine, esperar que esse cache seja aquecido pode causar atrasos. O pré-aquecimento ajuda a colocar imagens no cache de streaming de imagens com antecedência.

A API Prewarm Artifact permite solicitar manualmente que uma versão de imagem ou tag específica seja pré-armazenada em cache. Você também especifica um período de armazenamento para garantir que a imagem permaneça no cache por um período determinado.

Limitações

  • Somente API: o pré-aquecimento está disponível apenas usando a API REST do Artifact Registry. O pré-aquecimento não está disponível usando a CLI gcloud ou o console Google Cloud .
  • Somente no GKE: o pré-aquecimento é eficaz apenas para clusters do GKE com o streaming de imagens ativado. O streaming de imagens exige um software específico em execução no nó do cliente.
  • Artefato único: é possível pré-aquecer apenas um artefato (versão ou tag) por solicitação de API.
  • Imagens de várias arquiteturas: indisponível. Use a versão específica de uma imagem de arquitetura.
  • Limite do projeto: há um limite geral de 100 GB por projeto do consumidor para imagens pré-aquecidas. Quando o limite é atingido, as imagens mais antigas são removidas para abrir espaço para novas imagens.

Antes de começar

  1. Ative a API Artifact Registry. Para mais informações, consulte Ativar o Artifact Registry.
  2. Instale a CLI gcloud para receber tokens de autenticação para solicitações da API REST.

Funções exigidas

Para receber as permissões necessárias para gerenciar imagens pré-aquecidas, peça ao administrador para conceder os seguintes papéis do IAM no repositório:

  • Pré-aquecer ou remover artefatos do cache (artifactregistry.repositories.prewarmArtifact, artifactregistry.repositories.removePrewarmedArtifact): Gravador do Artifact Registry (roles/artifactregistry.writer)
  • Verificar ou listar artefatos pré-aquecidos (artifactregistry.repositories.checkPrewarmedArtifact, artifactregistry.repositories.listPrewarmedArtifacts): Leitor do Artifact Registry (roles/artifactregistry.reader)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Esse modelo de permissão garante que apenas usuários com acesso de gravação possam gerenciar o estado do cache, impedindo que usuários não autorizados o preencham demais. Enquanto isso, os usuários com acesso de leitura podem verificar quais artefatos estão disponíveis para streaming.

Pré-aquecer uma imagem

Para pré-aquecer uma imagem, faça uma solicitação POST ao método :prewarmArtifact do seu repositório.

API REST

Referência: projects.locations.repositories.prewarmArtifact

O corpo da solicitação tem a seguinte estrutura:

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

Como alternativa, use uma tag:

{
  "tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG",
  "retention_days": 3,
  "force": true
}
Campo Descrição
tag Opcional. A tag de artefato específica a ser pré-aquecida. É preciso especificar version ou tag.
version Opcional. A versão específica do artefato a ser pré-aquecida. É preciso especificar version ou tag.
retention_days Opcional. O número de dias em que o artefato será mantido no cache. Se você não especificar esse campo, o padrão será 3 dias.
force Opcional. Se true, o sistema poderá remover artefatos mais antigos para liberar espaço para este.
stream_location Opcional. A região específica em que a imagem será pré-aquecida. Por padrão, isso corresponde ao local da imagem. As configurações multirregionais não são compatíveis. Se uma região ampla for especificada, os padrões serão us-central1 (EUA), europe-north1 (UE) e asia-east1 (Ásia).

Exemplo: pré-aquecer uma versão específica

O exemplo a seguir faz o pré-aquecimento da versão sha256:52e... do pacote nginx no repositório my-repo na região "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"

Exemplo: pré-aquecer uma tag

O exemplo a seguir pré-aquece a imagem marcada como production do pacote 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"

Verificar o status do pré-aquecimento

Para verificar se um artefato está pré-aquecido, use o 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"

Listar artefatos pré-aquecidos

Para listar todos os artefatos pré-aquecidos em um repositório, use o método GET na coleção prewarmedArtifacts. O exemplo a seguir lista todas as imagens pré-aquecidas em my-repo em us-east1. O filtro stream_location é obrigatório.

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"/

Remover do cache

Para remover explicitamente um artefato do cache de pré-inicialização, use o método :removePrewarmedArtifact. Use esse método para liberar espaço ou quando uma versão de imagem específica não for mais necessária no cache.

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"

A seguir