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 ambiente de execução as solicite. Isso elimina a latência de "inicialização a frio" associada à primeira extração 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 normalmente é preenchido na primeira extração de um cliente que tem o streaming de imagens ativado. Para cargas de trabalho sensíveis à latência, como o escalonamento vertical de um cluster do Google Kubernetes Engine, aguardar o aquecimento desse cache pode causar atrasos. O pré-aquecimento ajuda a colocar as imagens no cache do 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 específico.

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 no console do Google Cloud .
  • Somente GKE: o pré-aquecimento só é eficaz para clusters do GKE com o streaming de imagens ativado. O streaming de imagens requer 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: não compatíveis. Use a versão específica de uma imagem de arquitetura.
  • Limite do projeto: por padrão, o limite de armazenamento de pré-aquecimento é de 100 GB por projeto. Se não houver espaço suficiente para uma imagem, a operação de pré-aquecimento vai falhar, a menos que você defina force como true na solicitação. Quando force é true, as imagens pré-aquecidas menos recentemente são removidas para abrir espaço para a imagem. Para estimar quanto do limite você usa, consulte Verificar o uso do cache.

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 de API REST.

Funções exigidas

Para receber as permissões necessárias para gerenciar imagens pré-aquecidas, peça ao administrador para conceder a você 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 sobrecarreguem. 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 um version ou um tag.
version Opcional. A versão específica do artefato a ser pré-aquecida. É preciso especificar um version ou um tag.
retention_days Opcional. O número de dias para manter o artefato no cache. Se você não especificar esse campo, o padrão será de três dias.
force Opcional. Se for 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, ele 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).

O método :prewarmArtifact retorna uma operação de longa duração. Quando a operação é concluída, o campo response contém um objeto prewarmedArtifact. Para mais informações sobre os campos desse objeto, consulte Verificar o status de pré-aquecimento.

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

O exemplo a seguir pré-aquece a 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. Se você pré-aquecer o artefato em um local de stream diferente do local do repositório, especifique esse local no campo stream_location. O exemplo a seguir verifica a versão nginx que o exemplo anterior pré-carregou em 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",
    "stream_location": "us-east1"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:checkPrewarmedArtifact"

Se o artefato estiver no cache, a saída será semelhante a esta:

{
  "prewarmedArtifact": {
    "uri": "us-central1-docker.pkg.dev/my-project/my-repo/nginx@sha256:52e85304675567b5e656f5e997576a9d20c57176",
    "location": "us-east1",
    "expirationTime": "2026-03-21T17:04:05.123456Z",
    "state": "ACTIVE",
    "sizeBytes": "734003200",
    "createTime": "2026-03-14T17:04:05.123456Z"
  }
}

Se o artefato não estiver no cache, por exemplo, porque expirou, a resposta será um objeto JSON vazio.

O objeto prewarmedArtifact contém estes campos:

Campo Descrição
uri O URI da imagem, que identifica a imagem por resumo.
location O local do stream em que a imagem é armazenada em cache.
state O estado de armazenamento em cache do artefato: CACHING, ACTIVE ou FAILED.
sizeBytes O tamanho compactado do artefato em bytes. Esse tamanho é contabilizado no limite de armazenamento de pré-aquecimento.
createTime O horário em que o artefato foi pré-aquecido pela primeira vez.
expirationTime O horário em que o artefato expira do cache, a menos que você o pré-aqueça novamente antes disso.
errorMessage O motivo da falha no armazenamento em cache. Este campo é definido apenas quando state é FAILED.

Use o campo state para determinar se o artefato está pronto para streaming:

  • CACHING: o artefato está sendo armazenado em cache e não está pronto para streaming.
  • ACTIVE: o artefato está armazenado em cache e pronto para streaming.
  • FAILED: falha ao armazenar o artefato em cache. O campo errorMessage descreve a falha.

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"

O resultado será o seguinte:

{
  "prewarmedArtifacts": [
    {
      "uri": "us-central1-docker.pkg.dev/my-project/my-repo/nginx@sha256:52e85304675567b5e656f5e997576a9d20c57176",
      "location": "us-east1",
      "expirationTime": "2026-03-21T17:04:05.123456Z",
      "state": "ACTIVE",
      "sizeBytes": "734003200",
      "createTime": "2026-03-14T17:04:05.123456Z"
    },
    {
      "uri": "us-central1-docker.pkg.dev/my-project/my-repo/redis@sha256:4d3c2b1a0f9e8d7c6b5a49382716051f4e3d2c1b",
      "location": "us-east1",
      "expirationTime": "2026-03-17T18:30:12.654321Z",
      "state": "CACHING",
      "sizeBytes": "52428800",
      "createTime": "2026-03-14T18:30:12.654321Z"
    }
  ]
}

A resposta inclui artefatos em todos os estados. Portanto, verifique o campo state para saber quais artefatos estão prontos para streaming. Os artefatos expirados não são incluídos.

Por padrão, cada página de resultados contém até 100 artefatos. Para receber até 1.000 artefatos por página, defina o parâmetro de consulta pageSize. Se a resposta incluir um valor nextPageToken, mais artefatos estarão disponíveis. Para acessar a próxima página, repita a solicitação com o parâmetro de consulta pageToken definido como o valor nextPageToken.

Verificar o uso do cache

O limite de armazenamento de pré-aquecimento se aplica ao sizeBytes total dos artefatos pré-aquecidos no projeto que estão no estado CACHING ou ACTIVE. Os artefatos expirados e os artefatos no estado FAILED não são contabilizados no limite.

Cada solicitação de lista retorna os artefatos pré-aquecidos de um repositório em um local de stream. Para estimar quanto do limite seu projeto usa em um local de stream, faça o seguinte:

  1. Para cada repositório no projeto, independente do local, liste todas as páginas de artefatos pré-aquecidos com o parâmetro de consulta filter=stream_location=LOCATION. Substitua LOCATION pelo local do stream.
  2. Some os valores sizeBytes dos artefatos no estado CACHING ou ACTIVE.

Para liberar espaço antes que os artefatos expirem, remova os que não são mais necessários.

Remover do cache

Para remover explicitamente um artefato do cache de pré-aquecimento, 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