Deep Dive: K3s – um Kubernetes inteiro em um único binário, o que ele deixa de fora e seis coisas que ele não fez sozinho
O que roda dentro do binário único do K3s, o que este setup desliga ou substitui, como um cluster de um só nó é atualizado sem surpresas – e seis padrões e lacunas que só apareceram na operação real.

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski
Deep Dive da série em torno do Ansible Tour. O tour explica as roles; os deep dives, a tecnologia por baixo: como ela funciona, por que é usada desse jeito aqui e o que deu errado pelo caminho.
K3s é Kubernetes certificado em um único binário de cerca de 70 MB. API server, scheduler, controller manager, kubelet, kube-proxy, containerd, Flannel, CoreDNS e um controller de network policies sobem todos a partir de um processo e de uma unit do systemd. Isso o torna a escolha óbvia para um cluster de exatamente um nó – e esconde muita coisa. Este post explica o que realmente roda dentro desse binário, o que a parte 2 do tour configura e seis coisas que o K3s não fez sozinho, descobertas só durante a operação.
Índice
🧭 O que tem dentro do binário
Um supervisor, muitos componentes
k3s server é um supervisor. Ele inicia os componentes do control plane do Kubernetes como goroutines dentro do próprio processo – API server, scheduler, controller manager – e, ao lado deles, os componentes do nó: o kubelet, o kube-proxy, o CNI Flannel e um controller de network policies embutido (código do kube-router). O containerd roda como processo filho separado, com seu próprio socket em /run/k3s/containerd/. Tudo compartilha um único fluxo de log no journal (journalctl -u k3s) e um único número de versão.
O datastore: SQLite em vez de etcd
O Kubernetes upstream guarda seu estado no etcd. Um K3s de um nó usa SQLite através do kine, uma camada que traduz a API do etcd para SQL. Todo o estado do cluster – cada Deployment, Secret, ConfigMap, evento – fica em /var/lib/rancher/k3s/server/db/state.db: 24 MB no blog, 23 MB em um servidor Nextcloud, mais um write-ahead log de 20 MB. Com mais de um nó servidor, o K3s passa para o etcd embutido.
containerd, o CRI e o pause container
O kubelet conversa com o containerd pela Container Runtime Interface. Para cada pod, o containerd primeiro sobe um minúsculo container pause, que segura o network namespace do pod; os containers de verdade entram nele. k3s crictl é o cliente CRI para olhar esse nível diretamente – pods, containers, imagens – sem passar pelo API server. O K3s usa cgroup v2 no AlmaLinux 9, então os limites de recursos do pod são simples arquivos de cgroup em /sys/fs/cgroup/kubepods.slice/.
Rede: Flannel, kube-proxy, o controller de policies
- Flannel dá a cada pod um endereço de
10.42.0.0/16(em um nó: um/24), cria uma bridgecni0e um parvethpor pod. Backend aqui: VXLAN – irrelevante em um nó, mas o padrão para um segundo. - kube-proxy transforma Services em regras iptables (via iptables-nft, em tabelas nftables): DNAT de ClusterIP, NodePorts, balanceamento de carga entre endpoints.
- O controller de network policies transforma NetworkPolicies em chains (
KUBE-ROUTER-*,KUBE-NWPLCY-*, umaKUBE-POD-FW-*por pod). Ele faz parte do binário e vem ligado por padrão. Guarde esse aqui.
Certificados e tokens
O K3s cria sua própria CA e todos os certificados no primeiro start (/var/lib/rancher/k3s/server/tls/), válidos por um ano, e os renova automaticamente quando o serviço inicia a menos de 90 dias do vencimento. O kubeconfig de admin é /etc/rancher/k3s/k3s.yaml; o node token em /var/lib/rancher/k3s/server/token é o que um segundo nó precisaria para entrar no cluster.
🛡️ Por que ele está aqui
- Semântica de Kubernetes em um servidor pequeno. Deployments com updates rolling ou recreate, probes que reiniciam um container travado, NetworkPolicies entre pods, limites de recursos, uma admission policy para imagens – sem operar um cluster de control plane.
- Um binário, uma unit, uma versão fixada. A plataforma inteira é reproduzível a partir do Ansible; um upgrade é “trocar o binário, reiniciar a unit”.
- Bom suporte a AlmaLinux e SELinux: uma policy SELinux mantida (
k3s-selinux) e containerd com rotulagem SELinux.
🔧 O que este repositório faz
config.yaml: o que é desligado, o que é ligado
A maioria dos argumentos vem do CIS Kubernetes benchmark: um audit log da API com rotação, EventRateLimit para que um pod em crash loop não inunde a API com eventos, um limite de PIDs por pod contra fork bombs. Uma recomendação é deliberadamente ignorada: AlwaysPullImages puxaria cada imagem do registry a cada start de pod – inclusive o pod de cron do WordPress a cada cinco minutos – e transformaria uma queda curta do registry em pods falhando por toda parte, em troca de uma proteção multi-tenant de que um cluster single-tenant não precisa.
Fixado, e instalado em dois passos
O binário vem do release no GitHub de k3s_version (versions.yml), o script de instalação da mesma tag – não de get.k3s.io, que sempre entrega o script mais novo e respondeu HTTP 500 por um tempo no dia em que o segundo servidor Nextcloud foi montado. O script roda com INSTALL_K3S_SKIP_DOWNLOAD=true, só para criar a unit. Em volta do K3s a role instala Helm, cert-manager com um ClusterIssuer do Let’s Encrypt e o controller F5 nginx-ingress, e faz patch de toda ServiceAccount default para que os pods não recebam mais um token de API que nunca usam (CIS 5.1.5). As roles das aplicações adicionam uma ValidatingAdmissionPolicy por namespace que rejeita pods cujas imagens não venham de uma lista permitida de registries – embutida no API server desde o Kubernetes 1.30, sem componente extra.
O caminho do upgrade
- Ler a versão em execução (
k3s --version). - Se ela difere da fixada: baixar o binário com
get_url,force: true. restoreconno binário.- Executar os handlers na hora – o restart acontece aqui, não no fim do play.
- Esperar até
kubectl get nodesresponder, depois seguir com as roles que fazem deploy no cluster. - No fim do run,
common_version_activecompara a versão do kubelet informada pela API com a fixada.
Os passos 2, 3 e 6 existem, cada um, por causa de um erro – veja abaixo.
🐛 Seis coisas que o K3s não fez sozinho
1. O upgrade que não fez nada
Até 19 de outubro de 2026, a task de download não tinha force. O get_url do Ansible então pula o download quando o arquivo de destino já existe – ou seja, todo aumento de versão desde a primeira instalação tinha sido um no-op nos hosts existentes, em silêncio. Isso veio à tona porque o drift check da v1.37.1 não mostrou mudança nenhuma para o K3s. Desde então, o smoke test no fim de cada run (common_version_active) lê a versão que o kubelet realmente informa, não a do inventário.
A lição: uma task de update que termina não necessariamente atualizou alguma coisa. Depois de subir a versão, o que vale é a versão que o kubelet informa.
2. Pods que o SELinux não confinava
O SELinux estava enforcing em todos os hosts e os diretórios HostPath tinham container_file_t. Mas o K3s só inicia o containerd com suporte a SELinux quando a configuração diz selinux: true – e não dizia. Todo pod rodava como spc_t ou unconfined_service_t, que o SELinux não restringe em nada. Desde 19 de outubro de 2026 a opção está definida e a policy k3s-selinux instalada; todo pod roda agora como container_t com suas próprias categorias MCS, e os pods que existiam antes da mudança tiveram de ser recriados para pegá-la. O deep dive de SELinux conta a história inteira.
3. Um binário novo com o label errado
O get_url escreve por um arquivo temporário e o renomeia. O binário novo recebe, portanto, o label do seu diretório (bin_t) em vez de container_runtime_exec_t da policy, e o K3s iniciaria no domínio errado. Um restorecon depois de cada download resolve.
A lição: SELinux no host não significa SELinux no container. O runtime precisa usá-lo explicitamente, e todo binário recém-baixado precisa receber o label correto depois.
4. O motor de policies que nunca foi necessário
Durante dois meses o Calico rodou ao lado do K3s como suposto motor de NetworkPolicies. Ele não aplicava nada – o Felix do Calico só cuida de interfaces chamadas cali*, o Flannel cria veth* – e toda a aplicação vinha o tempo todo do controller próprio do K3s. A prova foi desagradável: com o controller desligado para um teste (disable-network-policy), um pod no namespace default alcançou o MariaDB na porta 3306. O Calico se foi, e a configuração agora traz um comentário em maiúsculas: nunca desligue o controller embutido. O deep dive de nftables descreve o lado do firewall.
A lição: um componente cujo efeito nunca foi testado é só peso – e um motivo para se sentir seguro sem estar.
5. Uma flag de admission que substituía em vez de adicionar
No Kubernetes upstream, --enable-admission-plugins adiciona plugins à lista padrão. No K3s ela substitui a lista do próprio K3s. Definir só EventRateLimit derrubou em silêncio o NodeRestriction – o plugin que impede um kubelet comprometido de modificar objetos de outros nós. Um novo run do kube-bench pegou isso (CIS 1.2.14 foi de PASS para FAIL). Agora os dois estão listados explicitamente. Uma armadilha parecida: o API server não cria o diretório do seu audit log e se recusa a iniciar sem ele; a role o cria antes do restart.
A lição: uma flag com o mesmo nome pode fazer outra coisa no K3s do que no Kubernetes. Vale a documentação da distribuição, e um novo run do kube-bench depois de cada mudança mostra se algo se perdeu.
📊 Medido
| Blog | Servidor Nextcloud | |
|---|---|---|
| Versão do K3s | v1.37.1+k3s1 | v1.37.1+k3s1 |
| Pods | 17 | 14 |
Memória do k3s server (RSS) | 789 MB | 826 MB |
| containerd (RSS) | 202 MB | 190 MB |
Tempo de CPU do k3s server | 23 min em 7,5 h (≈ 5 % de um core) | 2,5 h em 9,5 h (≈ 26 % de um core) |
| Datastore (state.db + WAL) | 24 + 20 MB | 23 + 20 MB |
| Audit log da API antes de 20/10/2026 | 1,1 GB (no limite configurado) | 1,0 GB, ~230 MB/dia |
| Audit log da API depois da mudança de policy | – | ~28 MB/dia |
Cerca de um gigabyte de RAM para o control plane inteiro é o preço de “Kubernetes de verdade em um nó”. Dois números chamaram atenção. O audit log estava no limite de dez backups de 100 MB – a rotação funcionava, mas os “30 dias” da configuração eram na verdade quatro e meio. E no servidor Nextcloud o control plane usava cinco vezes a CPU do blog, com menos pods.
Sete, não é bug: o mesmo trabalho a cinco vezes o custo
O audit log mostrava a mesma carga de escrita nos três servidores, e um perfil de CPU de 30 segundos – tirado sem restart pelo /debug/pprof do kubelet, que perfila o processo inteiro do K3s – não mostrava um culpado único: tudo estava umas quatro vezes e meia mais caro, principalmente o scheduler do Go acordando goroutines e as system calls por trás disso. Limitar o Go a quatro threads (GOMAXPROCS=4) não mudou nada. A resposta estava em /sys/devices/system/cpu/vulnerabilities/: os servidores Nextcloud rodam em uma geração mais antiga de AMD EPYC afetada pelo Retbleed, e o kernel protege cada retorno de uma função do kernel com um “return thunk”. Para um programa que vive de system calls e trocas de contexto, isso custa caro; a CPU mais nova do blog é “not affected”. Desligar a mitigação em uma máquina virtual compartilhada seria descuido – cerca de 2,6 % de um servidor de oito cores é o preço.
Seis: um audit log que se afogava no próprio ruído
A análise de um arquivo de 100 MB mostrou de onde vinha o volume: heartbeats de lease das leader elections e do kubelet (23 %), requisições de health, discovery e OpenAPI (14 %), o API server falando consigo mesmo (12 %) e requisições somente leitura dos próprios componentes da plataforma, service accounts e nós (cerca de 40 %). Nada disso tem valor de segurança; só empurrava as entradas interessantes para fora da janela de retenção. A policy agora descarta exatamente isso – com duas regras colocadas de propósito antes da regra de descarte: leituras de secrets continuam logadas para qualquer leitor, e tudo o que um administrador faz continua logado. Uma simulação contra o arquivo real previu que sobrariam 10 %; depois do rollout o log passou a crescer cerca de 28 MB por dia em vez de 230.
Upgrades
Uma versão minor por vez, como o Kubernetes exige (1.36 → 1.37, não 1.35 → 1.37). Suba k3s_version no versions.yml, rode o drift check (--check --diff) – agora ele precisa mostrar o download do binário –, rode o playbook e leia o relatório de versões no fim. Um restart do K3s não reinicia nem os pods nem os containers do containerd; a API some por uns 20 segundos, os sites não.
Backups – e o que é realmente necessário
O datastore não tem backup aqui, de propósito. Cada objeto nele é criado pelo Ansible a partir do repositório e do vault: namespaces, Secrets, Deployments, policies. Os dados que importam ficam fora do cluster, em diretórios HostPath e nos bancos de dados, e esses são puxados todas as noites pelo servidor de backup. Restaurar um servidor, portanto, significa: instalar o AlmaLinux, rodar o playbook, restaurar os diretórios de dados. O cluster em si é descartável – o argumento mais forte para manter tudo em código.
🆘 Cola: sintoma → comando
A versão curta deste artigo para o momento em que algo está errado. Execute no host como root; <…> são placeholders.
| Sintoma | Comando |
|---|---|
| Um pod não sobe | k3s kubectl get pods -Ak3s kubectl -n <ns> describe pod <pod> |
| Por que um container caiu? | k3s kubectl -n <ns> logs <pod> -c <container> --previous |
| O que aconteceu recentemente? | k3s kubectl get events -A --sort-by=.lastTimestamp | tail -20 |
| O kubectl trava ou o nó está NotReady | systemctl status k3sjournalctl -u k3s --since -15mink3s crictl ps # containerd, without the API server |
| Quem usa CPU e memória? | k3s kubectl top pods -A |
| ConfigMap ou Secret alterado não está ativo | k3s kubectl -n <ns> rollout restart deployment/<name> |
| Disco enchendo de imagens antigas | k3s crictl rmi --prune |
| Pod bloqueado pelo SELinux? | ausearch -m AVC -ts recent | grep container_tps -eZ | grep container_t | head |
| Quando os certificados vencem? | openssl x509 -enddate -noout -in /var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt |
🎯 As lições
- Depois de um update, confira a versão em execução, não a mensagem da task.
- Containers só ficam confinados se o runtime usa SELinux;
ps -eZmostra isso. - Conhecimento sobre flags do Kubernetes não vale automaticamente para o K3s.
- Um audit log precisa de uma policy que deixe o ruído de fora, ou o ruído empurra para fora as entradas que importam.
- Faça backup só do que não pode ser recriado a partir do repositório.
⚖️ Alternativas – e por que K3s
| Opção | Ponto forte | Por que não aqui |
|---|---|---|
| kubeadm | Kubernetes upstream, nada escondido | etcd, os componentes do control plane e o CNI ficam por sua conta para operar e atualizar separadamente – muito para um nó. |
| k0s | Também um binário único, padrões limpos | Comparável; o K3s tem a policy SELinux mantida e mais documentação para AlmaLinux. |
| MicroK8s | Add-ons fáceis | Distribuído como snap – não se sente em casa no AlmaLinux. |
| Docker/Podman Compose | Bem mais simples | Sem probes com restart, sem NetworkPolicies, sem admission policy, sem rolling updates. |
| K3s | API completa do Kubernetes, menor footprint, policy SELinux | Escolhido. |
O K3s cumpre a promessa: Kubernetes de verdade em um binário. O que as últimas semanas mostraram é que “um binário” também é “um lugar onde os padrões se escondem”. Quatro dos seis problemas acima não eram bugs do K3s, e sim padrões e suposições – SELinux desligado a menos que se peça, uma flag de admission que substitui em vez de adicionar, um controller de policies que já estava lá e a nossa própria regra de audit pega-tudo que logava cada heartbeat. Cada um deles está agora anotado como comentário na role, ao lado da linha que o traria de volta.
