Coleta de Lixo

Coleta de lixo (Garbage collection) é um termo coletivo para os vários mecanismos que o Kubernetes usa para limpar os recursos do cluster. Isso permite a limpeza de recursos como os seguintes:

Proprietários e dependentes

Muitos objetos no Kubernetes se vinculam uns aos outros através de referências de proprietário. As referências de proprietário informam à camada de gerenciamento quais objetos são dependentes de outros. O Kubernetes usa referências de proprietário para dar à camada de gerenciamento, e outros clientes da API, a oportunidade de limpar recursos relacionados antes de excluir um objeto. Na maioria dos casos, o Kubernetes gerencia referências de proprietário automaticamente.

A propriedade é diferente do mecanismo de labels e seletores que alguns recursos também usam. Por exemplo, considere um Service que cria objetos EndpointSlice. O Service usa labels para permitir que a camada de gerenciamento determine quais objetos EndpointSlice são usados para esse Service. Além das labels, cada EndpointSlice que é gerenciado em nome de um Service tem uma referência de proprietário. As referências de proprietário ajudam diferentes partes do Kubernetes a evitar interferir com objetos que elas não controlam.

Exclusão em cascata

O Kubernetes verifica e exclui objetos que não têm mais referências de proprietário, como os Pods deixados para trás quando você exclui um ReplicaSet. Quando você exclui um objeto, pode controlar se o Kubernetes exclui os dependentes do objeto automaticamente, em um processo chamado exclusão em cascata. Existem dois tipos de exclusão em cascata, como segue:

  • Exclusão em cascata em primeiro plano
  • Exclusão em cascata em segundo plano

Você também pode controlar como e quando a coleta de lixo exclui recursos que têm referências de proprietário usando finalizadores do Kubernetes.

Exclusão em cascata em primeiro plano

Na exclusão em cascata em primeiro plano, o objeto proprietário que você está excluindo primeiro entra em um estado de exclusão em progresso. Neste estado, o seguinte acontece com o objeto proprietário:

  • O servidor de API do Kubernetes define o campo metadata.deletionTimestamp do objeto para o momento em que o objeto foi marcado para exclusão.
  • O servidor de API do Kubernetes também define o campo metadata.finalizers para foregroundDeletion.
  • O objeto permanece visível através da API do Kubernetes até que o processo de exclusão seja concluído.

Depois que o objeto proprietário entra no estado de exclusão em progresso, o controlador exclui dependentes que conhece. Após excluir todos os objetos dependentes que conhece, o controlador exclui o objeto proprietário. Neste ponto, o objeto não é mais visível na API do Kubernetes.

Durante a exclusão em cascata em primeiro plano, os únicos dependentes que bloqueiam a exclusão do proprietário são aqueles que têm o campo ownerReference.blockOwnerDeletion=true e estão no cache do controlador de coleta de lixo. O cache do controlador de coleta de lixo pode não conter objetos cujo tipo de recurso não pode ser listado/observado com sucesso, ou objetos que são criados simultaneamente com a exclusão de um objeto proprietário. Veja Usar exclusão em cascata em primeiro plano para saber mais.

Exclusão em cascata em segundo plano

Na exclusão em cascata em segundo plano, o servidor de API do Kubernetes exclui o objeto proprietário imediatamente e o controlador de coleta de lixo (personalizado ou padrão) limpa os objetos dependentes em segundo plano. Se um finalizador existir, ele garante que os objetos não sejam excluídos até que todas as tarefas de limpeza necessárias sejam concluídas. Por padrão, o Kubernetes usa exclusão em cascata em segundo plano, a menos que você use manualmente a exclusão em primeiro plano ou escolha tornar órfãos os objetos dependentes.

Veja Usar exclusão em cascata em segundo plano para saber mais.

Dependentes órfãos

Quando o Kubernetes exclui um objeto proprietário, os dependentes deixados para trás são chamados de objetos órfãos. Por padrão, o Kubernetes exclui objetos dependentes. Para aprender como sobrescrever este comportamento, veja Excluir objetos proprietários e tornar órfãos os dependentes.

Coleta de lixo de containers e imagens não utilizados

O kubelet executa coleta de lixo em imagens não utilizadas a cada cinco minutos e em containers não utilizados a cada minuto. Você deve evitar usar ferramentas externas de coleta de lixo, pois estas podem quebrar o comportamento do kubelet e remover containers que deveriam existir.

Para configurar opções para coleta de lixo de containers e imagens não utilizados, ajuste o kubelet usando um arquivo de configuração e altere os parâmetros relacionados à coleta de lixo usando o tipo de recurso KubeletConfiguration.

Ciclo de vida da imagem de container

O Kubernetes gerencia o ciclo de vida de todas as imagens através do seu gerenciador de imagens, que é parte do kubelet, com a cooperação do cadvisor. O kubelet considera os seguintes limites de uso de disco ao tomar decisões de coleta de lixo:

  • HighThresholdPercent
  • LowThresholdPercent

O uso de disco acima do valor HighThresholdPercent configurado aciona a coleta de lixo, que exclui imagens em ordem baseada na última vez que foram usadas, começando com a mais antiga primeiro. O kubelet exclui imagens até que o uso de disco atinja o valor LowThresholdPercent.

Coleta de lixo para imagens de container não utilizadas

ESTADO DA FUNCIONALIDADE: Kubernetes v1.30 [beta] (habilitado por padrão: true)

Como uma funcionalidade beta, você pode especificar o tempo máximo que uma imagem local pode ficar não utilizada, independentemente do uso de disco. Esta é uma configuração do kubelet que você configura para cada node.

Para configurar a definição, você precisa definir um valor para o campo imageMaximumGCAge no arquivo de configuração do kubelet.

O valor é especificado como uma duração do Kubernetes. Veja duração no glossário para mais detalhes.

Por exemplo, você pode definir o campo de configuração para 12h45m, o que significa 12 horas e 45 minutos.

Coleta de lixo de containers

O kubelet coleta lixo de containers não utilizados baseado nas seguintes variáveis, que você pode definir:

  • MinAge: a idade mínima na qual o kubelet pode coletar lixo de um container. Desabilite definindo como 0.
  • MaxPerPodContainer: o número máximo de containers mortos que cada Pod pode ter. Desabilite definindo como menor que 0.
  • MaxContainers: o número máximo de containers mortos que o cluster pode ter. Desabilite definindo como menor que 0.

Além dessas variáveis, o kubelet coleta lixo de containers não identificados e excluídos, tipicamente começando com o mais antigo primeiro.

MaxPerPodContainer e MaxContainers podem potencialmente entrar em conflito um com o outro em situações onde manter o número máximo de containers por Pod (MaxPerPodContainer) iria além do total permitido de containers mortos globais (MaxContainers). Nesta situação, o kubelet ajusta MaxPerPodContainer para resolver o conflito. Um cenário de pior caso seria rebaixar MaxPerPodContainer para 1 e despejar os containers mais antigos. Adicionalmente, containers pertencentes a Pods que foram excluídos são removidos uma vez que são mais antigos que MinAge.

Configurando coleta de lixo

Você pode ajustar a coleta de lixo de recursos configurando opções específicas para os controladores que gerenciam esses recursos. As seguintes páginas mostram como configurar coleta de lixo:

Próximos passos

Última modificação November 04, 2025 at 7:28 AM PST: [pt-br] Create content/pt-br/docs/concepts/architecture/garbage-collection.md (#51881) (fd402f9f7f)