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
forcecomotruena solicitação. Quandoforceé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
- Ative a API Artifact Registry. Para mais informações, consulte Ativar o Artifact Registry.
- 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 campoerrorMessagedescreve 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:
- 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. SubstituaLOCATIONpelo local do stream. - Some os valores
sizeBytesdos artefatos no estadoCACHINGouACTIVE.
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
- Enviar e extrair imagens de contêiner
- Gerenciar imagens de contêiner
- Saiba mais sobre o Streaming de imagens no Google Kubernetes Engine