Entendendo o armazenamento local no Kubernetes com K3s e Local Path Provisioner

Engenheiros que implantam cargas de trabalho baseadas em estado (stateful), como bancos de dados ou filas de mensagens, no Kubernetes frequentemente enfrentam desafios com o armazenamento persistente. Em clusters de nó único, laboratórios domésticos (homelabs) e ambientes de computação de borda (edge), sistemas distribuídos complexos como Longhorn ou Ceph introduzem uma alta sobrecarga de CPU e memória, enquanto mapeamentos diretos de diretórios do hospedeiro criam conflitos de segurança e agendamento. Em uma análise arquitetural publicada em 8 de outubro de 2026, o arquiteto de software Mihai Farcas detalhou como o Local Path Provisioner da Rancher oferece uma alternativa leve para armazenamento local no nó.

Armazenamento efêmero e abstrações de volume

Por padrão, os sistemas de arquivos de contêineres são efêmeros, descartando dados de execução não salvos sempre que um processo é reiniciado. Mapeamentos diretos de diretórios do hospedeiro resolvem a retenção básica de arquivos no Docker tradicional, mas falham no Kubernetes devido à falta de visibilidade no agendamento, ao risco de acúmulo de arquivos ao remover pods e à perda de isolamento dos contêineres. O Kubernetes resolve isso por meio de três camadas de abstração de armazenamento: PersistentVolumes para a alocação de armazenamento físico, PersistentVolumeClaims para as requisições das aplicações e StorageClasses para o provisionamento dinâmico.

Provisionamento dinâmico por meio de pods auxiliares

O Local Path Provisioner da Rancher executa como um pod controlador dentro do cluster para automatizar o gerenciamento de diretórios locais nos nós. Fundamentalmente, o provisionador utiliza o modo de associação de volume configurado como WaitForFirstConsumer, mantendo as solicitações de armazenamento pendentes até que o agendador do Kubernetes atribua o pod a um nó com base em restrições de processamento e memória. Uma vez atribuído, o controlador inicializa um pod auxiliar temporário baseado em busybox nessa máquina para criar um diretório dedicado no hospedeiro, registra o PersistentVolume e permite que o kubelet do nó faça o mapeamento direto da pasta para o contêiner. Quando o PersistentVolumeClaim é excluído sob a política de remoção padrão, outro pod auxiliar remove o diretório do hospedeiro para evitar o acúmulo de arquivos desnecessários no disco.

Trade-offs operacionais e limites de implantação

Como os volumes de caminho local são mapeados diretamente para as unidades NVMe do hospedeiro sem a sobrecarga de replicação via rede, eles oferecem baixa latência e alto desempenho, evitando a sobrecarga de 15% a 30% na CPU associada às camadas de armazenamento distribuído. No entanto, essa arquitetura vincula os dados a um único nó físico, não oferecendo failover de hardware se a máquina falhar. As aplicações que utilizam provisionadores de caminho local devem confiar na replicação em nível de aplicação — como clusters de réplicas de banco de dados — ou em ferramentas externas de instantâneos (snapshots). Além disso, solicitações normais de capacidade nos volumes atuam apenas como filtros de agendamento, e não como cotas rígidas de sistema de arquivos, a menos que as partições do hospedeiro estejam especificamente configuradas com suporte a cotas de projeto.

Ilustração editorial gerada por IA; não é uma fotografia documental.

Fonte: Mount Local Storage to Kubernetes Pods: An Easy Tutorial Using K3s and the Local Path Provisioner