TrueNAS Scale Electric Eel: migrando do Kubernetes para Docker Compose sem perder dados

A atualização 24.10 do TrueNAS Scale, codinome "Electric Eel", marcou uma das mudanças mais significativas na história recente da plataforma: a remoção do backend Kubernetes (k3s) em favor de um runtime Docker nativo gerenciado via Docker Compose. Para quem opera um homelab ou infraestrutura de pequena empresa, isso não é apenas uma nota de rodapé; é uma mudança tectônica na eficiência e na gestão de armazenamento.

Se você passou os últimos anos lutando contra charts Helm complexos, problemas de DNS interno do cluster ou simplesmente observando 10% da sua RAM desaparecer apenas para manter o plano de controle do Kubernetes vivo, essa atualização é para você. No entanto, a migração exige planejamento. O Docker Compose é mais simples, mas não é mágico. A persistência de dados em ZFS precisa ser tratada com respeito para evitar o pesadelo de containers vazios após o reboot.

Resumo em 30 segundos

Adeus k3s: O TrueNAS Scale 24.10 removeu a camada de orquestração Kubernetes, eliminando um overhead massivo de CPU e RAM.

Docker Nativo: Agora você pode usar arquivos compose.yaml padrão, facilitando a portabilidade e o uso de imagens que não possuem charts oficiais.

Cuidado com os Dados: A migração não é automática para Apps de terceiros (como TrueCharts). Você precisará mapear manualmente seus Datasets ZFS para os volumes do Docker para garantir a persistência.

O impacto do overhead do k3s em servidores domésticos

Durante as versões Angelfish até Dragonfish, o TrueNAS Scale apostou no k3s (uma distribuição leve de Kubernetes) para gerenciar aplicações. Embora tecnicamente impressionante para escala horizontal, essa decisão impôs um "imposto" pesado em setups de nó único.

Em um servidor com 16GB ou 32GB de RAM, o k3s consumia, em idle, cerca de 2GB a 4GB apenas para rodar seus serviços de sistema (coredns, traefik ingress, metrics-server, etcd). Para um storage appliance, isso é um pecado capital. Cada gigabyte ocupado pelo sistema operacional é um gigabyte a menos para o ARC (Adaptive Replacement Cache) do ZFS.

Figura: Comparativo visual do impacto na memória RAM: o overhead do Kubernetes vs. a eficiência do Docker nativo liberando espaço para o cache ZFS.

Ao migrar para o Docker nativo no Electric Eel, removemos a necessidade de manter um etcd database rodando constantemente e toda a complexidade de redes overlay do Kubernetes. O resultado é que o sistema operacional volta a consumir o mínimo necessário, devolvendo recursos preciosos para o que realmente importa: servir arquivos e proteger dados.

Diferenças arquiteturais: Cluster vs Runtime

Para entender como migrar sem perder dados, precisamos desmistificar onde os dados vivem. No modelo antigo (Kubernetes), usávamos PVCs (Persistent Volume Claims) que o sistema provisionava dinamicamente. Muitas vezes, o usuário nem sabia onde aquela pasta estava montada no pool ZFS.

No modelo Docker Compose (Electric Eel), voltamos ao básico e robusto Bind Mount. Você diz explicitamente: "Pegue este Dataset ZFS /mnt/tank/app_data/plex e monte dentro do container em /config".

💡 Dica Pro: Não use volumes nomeados do Docker (ex: docker volume create). Eles ficam enterrados na estrutura do sistema operacional e são difíceis de fazer backup via snapshot do ZFS. Sempre use caminhos absolutos do host (Host Paths) apontando para seus Datasets.

Tabela Comparativa: Kubernetes (k3s) vs Docker Compose

Característica	Kubernetes (k3s) no Scale	Docker Compose (Electric Eel)
Complexidade	Alta (Pods, Services, Ingress, PVCs)	Baixa (Containers, Portas, Volumes)
Uso de Recursos	Alto (CPU constante, RAM reservada)	Mínimo (Apenas o processo do container)
Rede	Overlay complexa (CNI), isolamento padrão	Bridge simples ou Host Network
Armazenamento	PVCs (Abstração sobre o ZFS)	Bind Mounts (Mapeamento direto ZFS)
Backup	Requer ferramentas de exportação de PVC	Snapshots ZFS diretos no Dataset

A tentação da VM e os gargalos de I/O

Antes do Electric Eel, muitos usuários (eu incluso) desistiam do sistema de Apps nativo e subiam uma VM Linux (Ubuntu/Debian) apenas para rodar o Portainer e o Docker. Embora funcional, essa abordagem introduz uma penalidade de performance severa no contexto de storage.

Quando você roda o Docker dentro de uma VM:

Dupla Camada de Filesystem: O dado passa pelo EXT4 da VM, depois pelo disco virtual (vDev), e só então chega ao ZFS do host.
Isolamento do ARC: A VM tem sua própria RAM gerenciada. Se o ZFS no host tiver dados em cache, a VM não consegue acessá-los diretamente na velocidade da memória; ela precisa solicitar via protocolo de rede ou disco virtual.
Complexidade de Rede: Você acaba gerenciando bridges e IPs virtuais desnecessários.

Com o Electric Eel, o Docker roda "bare-metal" no kernel do TrueNAS. O container acessa o Dataset ZFS diretamente. A latência de I/O é praticamente zero. Se você ainda mantém uma VM "Docker-Host", a hora de aposentá-la é agora.

Figura: Ilustração do caminho de I/O: a complexidade e latência de rodar Docker em VM versus o acesso direto ao ZFS no modo nativo.

Estruturando o compose.yaml para ZFS

A chave para a migração sem perda de dados é o mapeamento correto dos volumes. Vamos assumir que você está migrando um servidor Plex ou Jellyfin.

No cenário antigo, seus dados de configuração estavam em um PVC. Você precisará localizar esses dados no shell (geralmente em /mnt/pool/ix-applications/...) e movê-los para um Dataset limpo e organizado, por exemplo: /mnt/tank/docker/plex/config.

Aqui está como um arquivo compose.yaml deve ser estruturado para garantir que o ZFS faça seu trabalho de proteção de dados:

services:
  plex:
    image: lscr.io/linuxserver/plex:latest
    container_name: plex
    network_mode: host
    environment:
      - PUID=568  # ID do usuário 'apps' no TrueNAS (verifique o seu)
      - PGID=568  # ID do grupo 'apps'
      - TZ=America/Sao_Paulo
      - VERSION=docker
    volumes:
      # CRÍTICO: Isso deve ser um Dataset ZFS com snapshots automáticos ativados
      - /mnt/tank/docker/plex/config:/config
      
      # Mapeamento de Mídia (Leitura/Escrita)
      - /mnt/tank/media/filmes:/data/filmes
      - /mnt/tank/media/series:/data/series
      
      # Transcode em RAM (Opcional, mas recomendado)
      - /dev/shm:/transcode
    restart: unless-stopped

⚠️ Perigo: Nunca mapeie a raiz do seu pool (/mnt/tank) diretamente para dentro de um container. Se um container for comprometido ou tiver um bug de script (ex: rm -rf /), ele pode apagar todo o seu storage. Mapeie apenas os sub-datasets necessários.

Figura: Diagrama de mapeamento de armazenamento: conectando Datasets ZFS específicos aos diretórios internos do container via Bind Mounts seguros.

Métricas de redução de consumo

Após realizar a migração de um cluster k3s com 15 Apps (incluindo Nextcloud, Plex e arr-stack) para o Docker Compose nativo no TrueNAS 24.10, os resultados em um servidor com Intel Xeon e 64GB de RAM foram imediatos:

Uso de CPU em Idle: Caiu de média 8-12% para 1-2%. O processo k3s-server era notoriamente "barulhento", gerando interrupções constantes de CPU.
Memória RAM Disponível: Recuperação de aproximadamente 3.5GB de RAM que antes eram "reservados" ou usados pelos pods de sistema do Kubernetes.
Tempo de Boot: O tempo para que todos os serviços estivessem "prontos" após um reboot caiu de 4 minutos para menos de 45 segundos.

Essa eficiência não é apenas estética; ela significa menos calor gerado, menos energia consumida e, crucialmente, mais memória para o cache de leitura do ZFS, o que acelera o acesso aos seus arquivos via SMB ou NFS.

Figura: Gráfico de performance antes e depois da migração: queda drástica no uso de CPU e RAM e redução no tempo de boot.

Veredito do Homelab

A transição para o TrueNAS Scale Electric Eel e o abandono do Kubernetes é a melhor decisão que a iXsystems tomou para o mercado de entrada e entusiasta. Embora a migração exija trabalho manual — especialmente para quem dependia da "mágica" (e complexidade) do TrueCharts — o resultado final é um sistema mais robusto, previsível e alinhado com o padrão da indústria.

Se você está adiando a atualização por medo de quebrar seus Apps, a recomendação é clara: faça backup dos seus dados, documente seus caminhos de armazenamento e migre. A simplicidade de um arquivo compose.yaml e a performance recuperada valem cada minuto investido na reconfiguração.

FAQ: Perguntas Frequentes sobre a Migração

O que acontece com meus Apps TrueCharts na atualização para o Electric Eel?

Eles não migram automaticamente. Como a TrueCharts descontinuou o suporte ao TrueNAS Scale em favor do Talos Linux, você deve exportar seus dados (PVCs) manualmente e recriar os serviços usando Docker Compose nativo ou Apps oficiais. Se você atualizar sem remover os apps antigos, eles simplesmente deixarão de funcionar.

Posso continuar usando o Portainer no TrueNAS Scale 24.10?

Sim, mas agora ele roda como um container Docker nativo, não mais como um chart Helm. Isso simplifica o acesso ao socket do Docker, mas exige cuidado para não conflitar com a gestão de Apps da própria interface do TrueNAS. A recomendação é usar a interface nativa para stacks simples e o Portainer apenas se precisar de gestão avançada visual.

Qual a vantagem de performance ao remover o Kubernetes?

A remoção do k3s libera recursos significativos de CPU e RAM (frequentemente 2GB+ de RAM em idle) que eram usados apenas para manter o plano de controle do cluster (etcd, coredns, ingress), permitindo que esses recursos sejam usados pelo cache ARC do ZFS, melhorando a velocidade de leitura e escrita do storage.

Referências & Leitura Complementar

iXsystems. (2024). TrueNAS Scale 24.10 Release Notes. Disponível na documentação oficial do TrueNAS.
Docker. (2024). Compose File Reference Specification. Documentação técnica sobre a estrutura compose.yaml.
OpenZFS. (2023). ZFS ARC (Adaptive Replacement Cache) Architecture. Explicação técnica sobre como a memória livre beneficia o desempenho do ZFS.