Usar o streaming de imagem para extrair imagens de contêiner

Nesta página, mostramos como usar o streaming de imagens no Google Kubernetes Engine (GKE) para extrair imagens de contêiner fazendo streaming dos dados da imagem conforme necessário para seus aplicativos.

Os novos clusters do Autopilot que executam a versão 1.25.5-gke.1000 e posterior do GKE usam automaticamente o streaming de imagens para extrair imagens qualificadas. As instruções nesta página se aplicam somente aos clusters padrão.

Informações gerais

O streaming de imagens é um método de extração de imagens de contêiner em que o GKE transfere dados de imagens qualificadas, conforme solicitado pelos aplicativos. É possível usar o streaming de imagens para permitir que suas cargas de trabalho sejam inicializadas sem esperar o download da imagem inteira, o que leva a melhorias significativas nos tempos de inicialização. O tempo de pull reduzido oferece benefícios, incluindo os seguintes:

• Escalonamento automático mais rápido
• Latência reduzida ao extrair imagens grandes
• Inicialização do pod mais rápida

Com o streaming de imagens, o GKE usa um sistema de arquivos remoto como sistema de arquivos raiz para qualquer contêiner que use imagens de contêiner qualificadas. O GKE faz streaming de dados de imagem do sistema de arquivos remoto, conforme necessário para suas cargas de trabalho. Sem o streaming de imagens, o GKE faz o download de toda imagem de contêiner em cada nó e a usa como o sistema de arquivos raiz das suas cargas de trabalho.

Durante o streaming dos dados da imagem, o GKE faz o download de toda a imagem do contêiner para o sistema de arquivos remoto em segundo plano e o armazena em cache. O GKE exibe solicitações futuras de leitura de dados da imagem em cache.

Quando você implanta cargas de trabalho que precisam ler arquivos específicos na imagem do contêiner, o back-end de streaming de imagens exibe apenas os arquivos solicitados.

Requisitos

Você precisa atender aos seguintes requisitos para usar o streaming de imagens nos clusters Autopilot e Standard do GKE:

• Ative a API Container File System.

  Ativar a API Container File System

• Os novos clusters do Autopilot precisam executar o GKE versão 1.25.5-gke.1000 ou posterior para ativar o streaming de imagens automaticamente. Para ver instruções, consulte Definir a versão e o canal de lançamento de um novo cluster do Autopilot.

• Os clusters novos e atuais do GKE Standard precisam executar a versão 1.18.6-gke.4801 ou posterior.

• Use o Container-Optimized OS com uma imagem de nó. Os nós do Autopilot sempre usam essa imagem de nó.

• As imagens de contêiner precisam ser armazenadas no Artifact Registry.

• Se você usar clusters particulares, será necessário ativar o Acesso privado do Google na sub-rede para que os nós acessem o Serviço de streaming de imagens.

• Se o VPC Service Controls proteger suas imagens de contêiner e você usar o streaming de imagens, inclua também a API Image Streaming (containerfilesystem.googleapis.com) no perímetro de serviço.

• Se os nós do GKE no cluster não usarem a conta de serviço padrão, verifique se a conta de serviço personalizada tem o papel do IAM de Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer) no projeto que hospeda a imagem do contêiner.

Limitações

• Não é possível usar um secret para extrair imagens de contêiner em versões do GKE anteriores a 1.23.5-gke.1900.
• Imagens de contêiner que usam o manifesto de imagem V2, versão 1 do esquema não são qualificadas.
• As imagens de contêiner criptografadas com chaves de criptografia gerenciadas pelo cliente (CMEK) estão qualificadas para streaming de imagem no GKE versão 1.25.3-gke.1000 ou posterior. Nas versões anteriores, o GKE faz o download dessas imagens sem transmitir os dados. Ainda é possível usar as CMEKs para proteger discos permanentes e discos de inicialização personalizados anexados nos clusters que usam o streaming de imagens.
• As imagens de contêiner com camadas duplicadas só são qualificadas para o streaming de imagens no GKE versão 1.28 ou posterior. Nas versões anteriores, o GKE faz o download dessas imagens sem transmitir os dados. Verifique se há camadas vazias ou duplicadas na imagem do contêiner.
• O repositório do Artifact Registry precisa estar na mesma região que os nós do GKE ou em uma multirregião que corresponde à região em que os nós estão em execução. Exemplo:
  • Se os nós estiverem em us-east1, o streaming de imagens estará disponível para repositórios na região us-east1 ou na multirregião us, desde que o GKE e o Artifact Registry estejam em execução em locais de data center nos Estados Unidos.
  • Se os nós estiverem na região northamerica-northeast1, eles serão executados no Canadá. Nessa situação, o streaming de imagens está disponível apenas para repositórios na mesma região.
• Se as cargas de trabalho lerem muitos arquivos em uma imagem durante a inicialização, talvez você perceba um aumento nos tempos de inicialização devido à latência adicionada pelas leituras remotas de arquivos.
• Talvez você não perceba os benefícios do streaming de imagens durante o primeiro pull de uma imagem qualificada. No entanto, depois que o streaming de imagens armazenar a imagem em cache, a imagem futura extrairá todos os benefícios do cluster pelo streaming de imagens.
• Os clusters do GKE Standard usam a configuração no nível do cluster para determinar se o streaming de imagens será ativado em novos pools de nós criados com o provisionamento automático de nós. No entanto, não é possível usar a separação de cargas de trabalho para criar pools de nós com o streaming de imagens ativado quando ele está desativado no nível do cluster.
• Os recursos de arquivos do Linux, como CAP_NET_RAW, são compatíveis com o streaming de imagens na versão 1.22.6-gke.300 e mais recentes do GKE. Para versões anteriores do GKE, esses recursos não estão disponíveis quando o arquivo de imagem é transmitido ou quando a imagem é salva no disco local. Para evitar possíveis interrupções, não use o streaming de imagens em contêineres com esses recursos nas versões do GKE anteriores a 1.22.6-gke.300. Se o contêiner depende dos recursos de arquivo do Linux, ele pode não começar com erros de permissão negada ao executar com o streaming de imagens ativado.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

• Ativar a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.

• Ative a API Container File System.

  Ativar a API Container File System

Ativar o streaming de imagens em clusters

É possível ativar o streaming de imagens em clusters novos ou atuais usando a sinalização --enable-image-streaming da CLI gcloud ou o Console do Google Cloud. Por padrão, os pools de nós no cluster herdam a configuração de streaming de imagens no nível do cluster. É possível alterar esse comportamento ativando ou desativando o streaming de imagens em pools de nós no cluster.

Todos os novos clusters do Autopilot que executam o GKE versão 1.25.5-gke.1000 e posterior usam streaming de imagens para extrair imagens qualificadas. Para ver instruções, consulte Definir a versão e o canal de lançamento de um novo cluster do Autopilot. As instruções a seguir se aplicam apenas aos clusters padrão do GKE.

Em um novo cluster

É possível ativar o streaming de imagens em novos clusters usando a CLI gcloud ou o console do Google Cloud.

gcloud container clusters create CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

Em um cluster atual

É possível ativar o streaming de imagens em clusters atuais que atendam aos requisitos usando a CLI gcloud ou o console do Google Cloud.

gcloud container clusters update CLUSTER_NAME \
    --enable-image-streaming

Depois de modificar o cluster, o GKE ativa o streaming de imagens nos pools de nós atuais por padrão. Se você ativou ou desativou explicitamente o streaming de imagens em pools de nós individuais, esses pools de nós não herdam as alterações na configuração no nível do cluster.

Verificar se o streaming de imagens está ativado em um cluster

É possível verificar se o streaming de imagens está ativado no nível do cluster usando a CLI gcloud ou o console do Google Cloud.

gcloud container clusters describe CLUSTER_NAME \
    --flatten "nodePoolDefaults.nodeConfigDefaults"

gcfsConfig:
  enabled: true
...

gcfsConfig: {}
...

Ativar o streaming de imagens em pools de nós

Por padrão, os pools de nós herdam a configuração do streaming de imagens no nível do cluster. É possível ativar ou desativar o streaming de imagens em pools de nós específicos usando a CLI gcloud.

Em um novo pool de nós

Para criar um novo pool de nós com streaming de imagens ativado, execute o seguinte comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

Substitua:

• NODE_POOL_NAME: o nome do novo pool de nós.
• CLUSTER_NAME: o nome do cluster do pool de nós.
• COMPUTE_ZONE: a zona do Compute Engine do cluster. Para clusters regionais, use a sinalização --region=COMPUTE_REGION.

Em um pool de nós atual

É possível ativar o streaming de imagens em pools de nós atuais que atendam aos requisitos.

Para atualizar um pool de nós atual para usar o streaming de imagens, execute o seguinte comando:

gcloud container node-pools update POOL_NAME \
    --cluster=CLUSTER_NAME \
    --enable-image-streaming

Verificar se o streaming de imagens está ativado em um pool de nós

Verificar se o streaming de imagens está ativado para um pool de nós:

gcloud container node-pools describe POOL_NAME \
    --cluster=CLUSTER_NAME \

A configuração será ativada se a saída for assim:

gcfsConfig:
  enabled: true
...

A configuração será desativada se a saída for assim:

gcfsConfig: {}
...

Programar uma carga de trabalho usando streaming de imagens

Depois de ativar o streaming de imagens no cluster, o GKE o usará automaticamente ao extrair imagens de contêiner qualificadas do Artifact Registry sem precisar de outras configurações.

O GKE adiciona o rótulo cloud.google.com/gke-image-streaming: "true" aos nós em pools de nós com o streaming de imagens ativado. No GKE Standard, se você ativar ou desativar o streaming de imagem em pools de nós específicos para que o cluster tenha uma combinação de nós que usam streaming de imagem e nós que não usam, poderá usar seletores de nós nas implantações para controlar se o GKE programa suas cargas de trabalho em nós que usam streaming de imagem.

No exemplo a seguir, você programa uma implantação que usa uma imagem de contêiner grande em um cluster com o streaming de imagens ativado. Se quiser, é possível comparar o desempenho com um pull de imagem sem a ativação do streaming de imagens.

1. Crie um cluster novo com streaming de imagens ativado:

   gcloud container clusters create CLUSTER_NAME \
       --zone=COMPUTE_ZONE \
       --enable-image-streaming \
       --image-type="COS_CONTAINERD"
   

2. Receba as credenciais para o cluster:

   gcloud container clusters get-credentials CLUSTER_NAME \
       --zone=COMPUTE_ZONE
   

3. Salve o seguinte manifesto como frontend-deployment.yaml:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: frontend
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: guestbook
         tier: frontend
     template:
       metadata:
         labels:
           app: guestbook
           tier: frontend
       spec:
         containers:
         - name: php-redis
           image: us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5
           env:
           - name: GET_HOSTS_FROM
             value: "dns"
           resources:
             requests:
               cpu: 100m
               memory: 100Mi
           ports:
           - containerPort: 80
   

   A imagem do contêiner gb-frontend tem 327 MB.

4. Aplique o manifesto ao cluster:

   kubectl apply -f frontend-deployment.yaml
   

5. Verifique se o GKE criou a implantação:

   kubectl get pods -l app=guestbook
   

   A resposta será semelhante a:

   NAMESPACE    NAME                          READY    STATUS       RESTARTS    AGE
   default      frontend-64bcc69c4b-pgzgm     1/1      Completed    0           3s
   

6. Acesse o log de eventos do Kubernetes para ver os eventos de extração de imagem:

   kubectl get events --all-namespaces
   

   A resposta será semelhante a:

   NAMESPACE  LAST SEEN  TYPE    REASON          OBJECT                                                 MESSAGE
   default    11m        Normal  Pulling         pod/frontend-64bcc69c4b-pgzgm                          Pulling image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5"
   default    11m        Normal  Pulled          pod/frontend-64bcc69c4b-pgzgm                          Successfully pulled image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" in 1.536908032s
   default    11m        Normal  ImageStreaming  node/gke-riptide-cluster-default-pool-f1552ec4-0pjv    Image us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5 is backed by image streaming.
   ...
   

   Nesta saída:

   • O evento Pulled mostra o tempo que leva para o streaming de imagens extrair a imagem.

   • O evento ImageStreaming mostra que o nó usa o streaming de imagens para exibir a imagem do contêiner.

Comparar o desempenho com pulls de imagem padrão

Neste exemplo opcional, você cria um novo cluster com o streaming de imagem desativado e implanta a implantação frontend para comparar o desempenho com o streaming de imagens.

1. Crie um cluster novo com streaming de imagens desativado:

   gcloud container clusters create CLUSTER2_NAME\
       --zone=COMPUTE_ZONE \
       --image-type="COS_CONTAINERD"
   

2. Receba as credenciais para o cluster:

   gcloud container clusters get-credentials CLUSTER2_NAME \
       --zone=COMPUTE_ZONE
   

3. Implante a implantação frontend do exemplo anterior:

   kubectl apply -f frontend-deployment.yaml
   

4. Consiga o log de eventos do Kubernetes:

   kubectl get events --all-namespaces
   

   A resposta será semelhante a:

    NAMESPACE  LAST SEEN  TYPE    REASON     OBJECT                             MESSAGE
    default    87s        Normal  Pulled     pod/frontend-64bcc69c4b-qwmfp      Successfully pulled image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" in 23.929723476s
   

   Observe o tempo que o GKE levou para extrair toda a imagem. Neste exemplo de saída, o GKE precisou quase 24 segundos. Com o streaming de imagens ativado, o GKE só precisava de 1,5 segundo para extrair os dados da imagem que a carga de trabalho exigia para iniciar.

Limpar

Para evitar cobranças, exclua os clusters criados nos exemplos anteriores:

gcloud container clusters delete CLUSTER_NAME CLUSTER2_NAME

Desativar o streaming de imagens

Se você usa o Autopilot do GKE, não é possível desativar o streaming de imagens em clusters individuais. É possível desativar a API Container File System, que desativa o streaming de imagens para todo o projeto.

Se você usa clusters padrão do GKE, pode desativar o streaming de imagens em clusters individuais ou em pools de nós específicos, conforme descrito nas seções a seguir.

Desativar o streaming de imagens em um cluster padrão do GKE

É possível desativar o streaming de imagens em clusters atuais do GKE Padrão usando a CLI gcloud ou o console do Google Cloud.

gcloud container clusters update CLUSTER_NAME \
    --no-enable-image-streaming

Em um novo pool de nós

Para desativar o streaming de imagens ao criar um novo pool de nós, especifique a sinalização --no-enable-image-streaming, como no seguinte comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --no-enable-image-streaming

Em um pool de nós atual

Para desativar o streaming de imagens em um pool de nós atual, execute o comando abaixo:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --no-enable-image-streaming

Reserva de memória para streaming de imagem

O GKE reserva recursos de memória para streaming de imagens, além da memória reservada para a execução dos componentes do sistema de nós. O GKE não reserva recursos adicionais de CPU para streaming de imagens. Nos clusters do GKE Standard, essa reserva muda os recursos de memória disponíveis para você solicitar nos pods. No Autopilot do GKE, o GKE gerencia as alocações de sistema para que não haja impacto na programação das suas cargas de trabalho.

Para detalhes sobre as reservas de memória que o GKE faz para componentes de nó, consulte Arquitetura de cluster Standard.

Nos nós que usam streaming de imagem, o GKE faz as seguintes reservas de memória extras para novas reservas:

• Não há memória adicional para máquinas com menos de 1 GiB de memória
• 1% dos primeiros 4 GiB de memória
• 0,8% dos próximos 4 GiB de memória (até 8 GiB)
• 0,4% dos próximos 8 GiB de memória (até 16 GiB)
• 0,24% dos próximos 112 GiB de memória (até 128 GiB)
• 0,08% de qualquer memória acima de 128 GiB

Solução de problemas

O GKE não usa o sistema de arquivos de streaming de imagens

Se o log de eventos do GKE não mostrar os eventos de streaming de imagens, a imagem não terá o sistema de arquivos remoto. Se o GKE extraiu a imagem anteriormente no nó, esse é o comportamento esperado, porque o GKE usa o cache local da imagem para pulls subsequentes em vez de usar o streaming de imagens. Para verificar isso, procure Container image IMAGE_NAME already present on machine no campo Message do evento Pulled do pod.

Se você não vir o evento de streaming de imagens durante a primeira extração de imagem no nó, verifique se atende aos requisitos de streaming de imagem. Se você atender aos requisitos, poderá diagnosticar o problema verificando os registros do serviço de streaming de imagem (chamado gcfsd):

1. Acesse a página do Explorador de registros no console do Google Cloud:

   Acessar o Explorador de registros

2. No campo Consulta, insira a seguinte consulta:

   logName="projects/PROJECT_ID/logs/gcfsd"
   resource.labels.cluster_name="CLUSTER_NAME"
   

   Substitua:

   • PROJECT_ID: o nome do projeto.
   • CLUSTER_NAME: o nome do cluster.

3. Clique em Executar consulta.

Também é possível verificar os registros gcfsd usando o Explorador de registros:

1. Acesse o Explorador de registros no console do Google Cloud:

   Acessar o Explorador de registros

2. No campo Consulta, insira a seguinte consulta:

   logName="projects/PROJECT_ID/logs/gcfsd"
   

   Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

PermissionDenied

Se os registros gcfsd exibirem uma mensagem de erro semelhante à seguinte, o nó não terá o escopo da API correto. O GKE extrai imagens de contêiner para cargas de trabalho sem usar o streaming de imagens.

level=fatal msg="Failed to create a Container File System client: rpc error:
code = PermissionDenied desc = failed to probe endpoint: rpc error: code = PermissionDenied
desc = Request had insufficient authentication scopes."

Para corrigir isso, conceda o escopo correto ao nó para permitir que ele use o streaming de imagens. Adicione o escopo devstorage.read_only ao cluster ou pool de nós, semelhante ao seguinte comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming \
    --scope="https://www.googleapis.com/auth/devstorage.read_only"

FailedPrecondition

Se você vir uma mensagem de erro com code = FailedPrecondition, a imagem não foi importada para o sistema de arquivos remoto de streaming de imagem.

Talvez você perceba esse erro se tentar usar o streaming de imagens com um pool de nós atual. Se um nó no pool de nós já tiver a imagem do contêiner no disco, o GKE usará a imagem local em vez de usar o streaming de imagem para conseguir a imagem.

Para corrigir isso, tente o seguinte:

• Aguarde alguns minutos e tente implantar a carga de trabalho novamente.
• Adicione novos nós ou um novo pool de nós e programe a carga de trabalho nesses nós.

InvalidArgument

Se você perceber uma mensagem de erro com code=InvalidArgument, a imagem do contêiner que sua carga de trabalho usa não será qualificada para o streaming de imagens. Verifique se a imagem atende aos requisitos. Se sua imagem não estiver no Artifact Registry, tente migrar para o Artifact Registry.

backend.FileContent failed

O erro a seguir pode aparecer ao ler arquivos de contêiner com o streaming de imagens ativado:

level=error msg="backend.FileContent failed" error="rpc error: code = ResourceExhausted desc = Quota exceeded for quota metric 'Content requests per project per region' and limit 'Content requests per project per region per minute per region' of service 'containerfilesystem.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'." layer_id="sha256:1234567890" module=gcfs_backend offset=0 path=etc/passwd size=4096

Esse erro indica que o projeto excedeu a cota necessária para ler arquivos do serviço de sistema de arquivos do contêiner remoto. Para resolver esse problema, aumente as seguintes cotas:

• Solicitações de conteúdo por projeto, por região e por minuto, por região
• Solicitações de conteúdo por projeto e região

O GKE faz o download da imagem sem fazer streaming dos dados

As imagens de contêiner que usam chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) só estão qualificadas para o streaming de imagens no GKE versão 1.25.3-gke.1000 ou posterior. As imagens de contêiner com camadas duplicadas só são qualificadas para o streaming de imagens no GKE versão 1.28 ou posterior. Consulte as Limitações para mais informações.

Verificar se há camadas vazias ou duplicadas

Para verificar se há camadas vazias ou duplicadas na imagem do contêiner, execute o seguinte comando:

docker inspect IMAGE_NAME

Substitua IMAGE_NAME pelo nome da imagem de contêiner.

Na saída do comando, inspecione as entradas em "Layers".

Se uma das entradas corresponder exatamente à seguinte saída "sha256", a imagem do contêiner terá uma camada vazia e não estará qualificada para o streaming de imagens.

"Layers": [
  ...
  "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4",
  ...
]

Se houver entradas duplicadas como no exemplo a seguir, a imagem do contêiner terá camadas duplicadas e não será qualificada para o streaming de imagens.

"Layers": [
  "sha256:28699c71935fe3ffa56533db44ad93e5a30322639f7be70d5d614e06a1ae6d9b",
  ...
  "sha256:28699c71935fe3ffa56533db44ad93e5a30322639f7be70d5d614e06a1ae6d9b",
  ...
]

O comando mv e as chamadas do sistema renameat2 falham em arquivos de link simbólico

Para os nós do GKE que executam a versão 1.25 e posteriores, quando o streaming de imagens estiver ativado, o comando mv e a chamada de sistema renameat2 poderão falhar em arquivos de link simbólico em imagens de contêiner com a mensagem de erro "Esse dispositivo ou endereço não existe". O problema é causado por uma regressão em kernels recentes do Linux.

Essas chamadas do sistema não são comuns. Portanto, a maioria das imagens não é afetada por esse problema. O problema geralmente acontece nos estágios de inicialização do contêiner quando um aplicativo está sendo preparado para executar e mover arquivos. Não é possível testar a imagem localmente. Por isso, o GKE recomenda usar o streaming de imagens em ambientes de teste para encontrar o problema antes que a imagem seja usada na produção.

A correção está disponível nas seguintes versões de patch do GKE:

• 1.25: 1.25.14-gke.1351000 e posterior
• 1.26: 1.26.9-gke.1345000 e posterior
• 1.27: 1.27.6-gke.100 e posterior
• 1.28: 1.28.1-gke.1157000 e posterior

Outra possibilidade para atenuar esse problema em todas as cargas de trabalho afetadas é substituir o código que leva à chamada de sistema renameat2. Se não for possível modificar o código, desative o streaming de imagens no pool de nós para atenuar o problema.