Neste post, vamos cobrir exatamente essa lacuna: tudo o que precisa mudar no sistema operacional de fábrica antes que o primeiro binário do Kubernetes encoste no disco. No kubeadm, essa etapa é mascarada como uma simples checagem de preflight. Aqui, sem instaladores automáticos, nós assumimos essa responsabilidade e deixamos o Ansible preparar cada nó de forma repetível, previsível e sem surpresas.

Duas roles, três grupos de máquinas

Todo o código desta etapa está dividido em duas roles no repositório parceiro ¹, porque as máquinas do laboratório têm papéis e requisitos diferentes:

A infra-sistema cuida do que qualquer máquina do laboratório precisa, inclusive as que nunca vão rodar kubelet. A k8s-cluster-base cuida apenas de quem vai ser nó.

todos (cluster.yml, tag cluster-sistema)
├── suporte
│   ├── loadbalancers  -> infra-sistema
│   └── nfs            -> infra-sistema
└── cluster            (cluster.yml, tag cluster-kubernetes-base)
    ├── managers       -> infra-sistema + k8s-cluster-base
    └── workers        -> infra-sistema + k8s-cluster-base

clientes (ops.yml, tag ops-sistema)
└── kubox              -> infra-sistema

O grupo todos recebe a infra-sistema no cluster.yml. O grupo cluster recebe, além dela, a k8s-cluster-base. E o kubox, que está fora de todos e mora no grupo clientes, recebe a infra-sistema pelo ops.yml. É por isso que não existe swapoff nem br_netfilter no balanceador: ele não é nó, e carregar módulo de ponte numa máquina que só roda HAProxy seria enfeite.

Do lado do Makefile, as duas roles ficam em alvos diferentes:

# Trecho do Makefile
infra: garante-config
	ANSIBLE_CONFIG="$(CFG)" ansible-playbook "$(PLAYBOOK)" $(ANSIBLE_VERBOSE) --tags cluster-artefatos,cluster-pki,cluster-sistema,cluster-balanceador,cluster-nfs

control-plane: garante-config
	ANSIBLE_CONFIG="$(CFG)" ansible-playbook "$(PLAYBOOK)" $(ANSIBLE_VERBOSE) --tags cluster-kubernetes-base,cluster-kubelet,cluster-etcd,cluster-kube-apiserver,cluster-kube-controller-manager,cluster-kube-scheduler

O make infra leva a infra-sistema (junto com artefatos, PKI, balanceador e NFS). O make control-plane abre com a k8s-cluster-base e segue para o kubelet e o resto do control plane. Dentro do cluster.yml, a ordem dos plays também importa: artefatos, PKI, sistema, balanceador, NFS e só então a base dos nós.

A role infra-sistema: o que toda máquina precisa

O arquivo que importa aqui é o 00-base.yml. São poucas tasks, mas cada uma resolve um problema que costuma aparecer no pior momento possível.

SELinux permissivo, de novo

Lembra do setenforce 0 escondido no Vagrantfile, lá na Parte 2? A infra-sistema repete a instrução, desta vez declarativa:

# Trecho de ansible/infra-sistema/tasks/00-base.yml (nome da task encurtado)
- name: Colocar SELinux em modo permissivo
  become: true
  ansible.posix.selinux:
    policy: targeted
    state: permissive

Redundante? Um pouco, e de propósito. O módulo ² faz duas coisas: grava o modo no /etc/selinux/config, para sobreviver ao reboot, e aplica na hora o equivalente a um setenforce 0. A role não deve depender de quem criou a VM. Se você trocar de box, provisionar de outro jeito, ou se alguém rodar setenforce 1 no meio do caminho, a próxima execução do playbook devolve a máquina ao estado combinado.

Pacotes, fuso horário e locale

A lista de pacotes em defaults/main.yml da role (pacotes_extras) não traz nada de Kubernetes, mas entrega a base operacional: utilitários de rede e shell (mtr, nano, wget, bash-completion), suporte a idiomas para o pt_BR.UTF-8 e o dnf-utils (que traz o needs-restarting, usado mais adiante para decidir se o nó precisa reiniciar após atualizações de kernel).

Em seguida, o Ansible garante que todas as VMs estejam sob o mesmo fuso horário (America/Sao_Paulo) e locale. Fuso alinhado evita dor de cabeça na hora de correlacionar logs de componentes distribuídos como etcd e kube-apiserver.

O arquivo /etc/hosts gerado pelo inventário

Não existe servidor de DNS no laboratório. As VMs enxergam a internet pela eth0 e conversam entre si pela eth1, e nada no meio traduz worker1.k8sbox.local para 172.24.0.41. Quem faz esse papel é um /etc/hosts gerado a partir do próprio inventário, pelo template hosts.j2:

# Trecho de ansible/infra-sistema/templates/hosts.j2
# Hostname da máquina
127.0.1.1 {{ inventory_hostname }}

# Entradas para os FQDNs dos endpoints
{{ keepalived_vip_ip }} {{ vip_api_fqdn }} {{ vip_etcd_fqdn }}

# Entradas das máquinas do cluster
{% for host in groups['todos'] %}
{{ hostvars[host].ansible_host }} {{ hostvars[host].fqdn }}
{% endfor %}

O IP e o FQDN de cada máquina vêm de ansible_host e fqdn, exatamente os campos que você viu no hosts-*.yml da Parte 3. No topologia mini, o arquivo renderizado fica assim (a ordem das últimas linhas pode variar):

# Hostname da máquina
127.0.1.1 manager1

# Entradas para os FQDNs dos endpoints
172.24.0.10 api.k8sbox.local etcd.k8sbox.local

# Entradas das máquinas do cluster
172.24.0.21 loadbalancer1.k8sbox.local
172.24.0.25 nfs.k8sbox.local
172.24.0.31 manager1.k8sbox.local
172.24.0.41 worker1.k8sbox.local
172.24.0.42 worker2.k8sbox.local

Repare na linha do meio. O IP 172.24.0.10 é o VIP do Keepalived, configurado para o balanceador de carga. Mesmo antes do serviço subir, o nome api.k8sbox.local já aponta para ele em todas as máquinas desde agora. Quando o VIP responder, todo mundo já sabe onde ele mora. E é esse nome, não o IP de um manager individual, que o kube-proxy usa para falar com a API (https://api.k8sbox.local:6443) e que consta nos certificados emitidos para o cluster.

Tailspin: colorização de logs

Para fechar a infra-sistema, instalamos o Tailspin ³ (tspin). Ele destaca automaticamente IPs, datas, status HTTP e níveis de severidade na saída padrão, transformando a leitura do journalctl em algo muito mais legível quando a rede ou o kubelet começarem a chiar:

$ journalctl -u sshd --no-pager | tspin

O binário é baixado no host pela role de artefatos e descompactado em /usr/local/bin com verificação de idempotência para não baixar novamente se já existir. Diferente dos binários do Kubernetes, aqui usamos a URL latest sem checksum rígido — concessão aceitável para uma ferramenta de conveniência em lab local descartável.

A role k8s-cluster-base: transformando uma VM em nó

Daqui em diante estamos apenas nas máquinas do grupo cluster, os managers e os workers. O main.yml da role importa dois arquivos de tasks: 01-instalacao.yml e 02-pki.yml. O primeiro é uma sequência em que a ordem não é estética:

flowchart TD
    PKG["<b>1. Pacotes</b><br>dnf instala as ferramentas e o kernel-modules-extra"]
    RB["<b>2. Reboot condicional</b><br>needs-restarting -r decide se a VM reinicia agora"]
    MOD["<b>3. Módulos de kernel</b><br>overlay, br_netfilter, vxlan e a família nf_*"]
    NFT["<b>4. Serviço nftables</b><br>habilitado e iniciado"]
    SWP["<b>5. Swap</b><br>swapoff agora e entrada do fstab comentada"]
    SYS["<b>6. Parâmetros sysctl</b><br>ip_forward e bridge-nf-call-*"]
    USR["<b>7. Usuário e diretórios</b><br>conta kubernetes, /etc/kubernetes e /var/lib/kubernetes"]
    PKI["<b>8. Certificados dos CAs</b><br>cópia para /etc/kubernetes/pki"]

    PKG --> RB
    RB --> MOD
    MOD --> NFT
    NFT --> SWP
    SWP --> SYS
    SYS --> USR
    USR --> PKI

    class PKG key;
    class RB,MOD,NFT,SWP,SYS,USR neutral;
    class PKI success;

Duas dependências de ordem merecem atenção. O reboot precisa vir antes dos módulos, e os módulos precisam vir antes do sysctl. Já vamos ver por quê.

Os pacotes do nó

Em vez de uma lista de compras, vou agrupar pelo problema que cada pacote resolve. A variável é pacotes_kubernetes, nos defaults da role:

Nada disso inicia serviço ou altera comportamento do sistema. São ferramentas esperando para serem úteis.

O reboot condicional

Logo depois da instalação de pacotes, a role pergunta se a máquina precisa reiniciar:

# Trecho de ansible/k8s-cluster-base/tasks/01-instalacao.yml
- name: Verificar se precisa reiniciar pós-instalação de pacotes
  ansible.builtin.command: needs-restarting -r
  register: reboot_check_k8s
  ignore_errors: true
  changed_when: reboot_check_k8s.rc == 1
  failed_when: reboot_check_k8s.rc not in [0, 1]
  notify: Reiniciar VM

- name: Executar reboot imediato se necessário
  ansible.builtin.meta: flush_handlers

O needs-restarting -r devolve código de saída 0 quando está tudo em ordem e 1 quando algum componente central (kernel, glibc, systemd, entre outros) foi atualizado e o reboot é recomendado. O Ansible não tem como saber isso sozinho, então a task traduz: código 1 vira "changed", e "changed" dispara o notify.

Por padrão, handlers só executam no fim do play. O meta: flush_handlers força a execução agora, e o handler faz o reboot de verdade, esperando a máquina voltar:

# Trecho de ansible/k8s-cluster-base/handlers/main.yml
- name: Reiniciar VM
  ansible.builtin.reboot:
    post_reboot_delay: 10
    reboot_timeout: 300

Reiniciar antes de qualquer outra coisa não é capricho. Se o dnf trouxe um kernel mais novo, os módulos instalados pertencem a ele, e o modprobe procura sempre em /lib/modules/$(uname -r), ou seja, no kernel que está rodando. Carregar módulos sem reiniciar poderia resultar em "módulo não encontrado" por um motivo confuso.

Módulos de kernel

A lista de módulos está em modulos_kernel_kubernetes:

Boa parte desses módulos seria carregada sob demanda pelo próprio kernel, mas listar explicitamente compra duas coisas: ambiente determinístico em todas as máquinas e falha antecipada. Um módulo que não existe estoura no Ansible, na hora, e não às três da manhã dentro de um pod.

A role registra a lista em dois lugares ao mesmo tempo:

# Trecho de ansible/k8s-cluster-base/tasks/01-instalacao.yml
- name: Garantir configuração de módulos necessários
  ansible.builtin.copy:
    dest: /etc/modules-load.d/kubernetes.conf
    content: "{{ modulos_kernel_kubernetes | join('\n') }}\n"
    mode: "0644"
  notify: Recarregar módulos do kernel

- name: Carregar módulos explicitamente
  community.general.modprobe:
    name: "{{ item }}"
    state: present
    persistent: present
  loop: "{{ modulos_kernel_kubernetes }}"

O arquivo /etc/modules-load.d/kubernetes.conf é lido pelo systemd-modules-load a cada boot, e o conteúdo é só um módulo por linha:

overlay
br_netfilter
vxlan
ip_tables
ip6_tables
nf_tables
nf_nat
nf_conntrack
xt_conntrack

Já a task do modprobe ⁴ carrega os módulos na hora, sem esperar o próximo boot, e o parâmetro persistent: present pede ao módulo do Ansible para também registrar cada um em /etc/modules-load.d/. Na prática, as duas coisas se sobrepõem. Se um dia a role for enxugada, uma delas pode sair sem que ninguém perceba.

Por que swap e Kubernetes não se dão

Essa é a regra mais famosa da lista, e quase sempre repetida sem explicação. No Linux, os limites de memória de um contêiner são barreiras impostas pelo cgroup (control group): se o processo ultrapassa o teto estipulado, o kernel aciona o OOM Killer (Out of Memory Killer), finaliza o processo excedente e o orquestrador sobe outro em seu lugar. É um corte seco, mas rápido e previsível.

Agora some swap à equação:

• O limite deixa de ser parede. Um pod acima do teto pode ter páginas empurradas para o disco, em vez de morrer. Em vez de uma queda rápida, você ganha uma lentidão arrastada, difícil de enxergar.
• O agendador planeja com RAM. O scheduler decide onde encaixar um pod somando requests de memória. Se o nó empurra páginas para o disco por baixo dos panos, o plano de encaixe vira ficção.
• O nó não se defende. Os limiares de despejo (eviction) do kubelet olham para a memória disponível. Com swap, o nó pode ficar patinando no disco em vez de despejar pods a tempo.

Por padrão, o kubelet nem tenta conviver com isso: ele recusa iniciar se detectar swap ativo. A configuração failSwapOn ⁵ tem como valor padrão true, e o template kubelet-config.yml.j2 do projeto mantém essa diretriz intacta. Se o swap estiver ligado quando o kubelet subir, ele simplesmente não inicializa.

A role cuida do swap em três tasks:

# Trecho de ansible/k8s-cluster-base/tasks/01-instalacao.yml
- name: Verificar se swap está ativo
  ansible.builtin.command: swapon --show
  register: swap_status
  changed_when: false

- name: Desabilitar swap
  ansible.builtin.command: swapoff -a
  when: swap_status.stdout != ""
  changed_when: true

- name: Remover entrada de swap do /etc/fstab
  ansible.builtin.replace:
    path: /etc/fstab
    regexp: '^([^#].*?\sswap\s.*)'
    replace: '# \1'

A primeira task só observa: se swapon --show não imprimir nada, não há swap. A segunda só roda quando há, e liga o swap para fora na hora. A terceira é a que garante que o problema não volta depois de um reboot.

A expressão regular merece uma leitura calma. O padrão ^([^#].*?\sswap\s.*) pega qualquer linha que não comece com # e que tenha a palavra swap cercada por espaços, e a substitui por ela mesma com # na frente. O [^#] no início é o que torna a task idempotente: uma linha já comentada não casa mais, então a segunda execução não encontra nada para mudar.

O serviço nftables

Uma distinção ajuda aqui: quem aplica as regras de filtragem é o subsistema nf_tables do kernel, sempre presente. O serviço nftables.service apenas garante o carregamento das tabelas base no boot. Habilitamos esse serviço porque o kube-proxy do projeto é configurado em mode: nftables (na role addon-kube-proxy). Esse modo dispensa o legado do iptables e exige kernel recente ⁶, requisito que o AlmaLinux 10 atende com folga.

Repare no que não está nessa role: regras de filtragem do host. O projeto não configura firewall de máquina, e no laboratório isso funciona porque a rede 172.24.0.0/24 é privada e isolada. Em produção, isso precisaria virar regras explícitas para as portas do cluster, como as que listamos no all.yml: 6443 para a API, 2379 e 2380 para o etcd, e 10250 para o kubelet.

Parâmetros de sysctl e a ponte que enxerga o firewall

Chegamos à task que dá mais "ah, então era isso". Três parâmetros, aplicados por loop:

# Trecho de ansible/k8s-cluster-base/tasks/01-instalacao.yml
- name: Configurar parâmetros de rede para Kubernetes
  ansible.posix.sysctl:
    name: "{{ item.key }}"
    value: "{{ item.value }}"
    state: present
    reload: true
  loop:
    - { key: "net.ipv4.ip_forward", value: "1" }
    - { key: "net.bridge.bridge-nf-call-iptables", value: "1" }
    - { key: "net.bridge.bridge-nf-call-ip6tables", value: "1" }

O módulo sysctl ⁷ do Ansible grava cada valor no /etc/sysctl.conf, para persistir entre boots, e recarrega as configurações logo em seguida (reload: true). Vamos por parâmetro:

Agora o "porquê" da segunda linha, que é a que menos gente entende. Uma bridge Linux é um switch virtual que opera na camada 2. Por padrão, o firewall do kernel só enxerga tráfego de camada 3, então quadros que passam de uma porta da bridge para outra seguem direto, sem nenhuma regra de NAT ou de conexão olhar para eles. O módulo br_netfilter muda isso, e o parâmetro bridge-nf-call-iptables liga o comportamento ¹⁰.

O cenário que quebra sem isso é um clássico de hairpin:

flowchart TD
    CALL["<b>1. Pod A chama um Service</b><br>O destino é o IP virtual do Service"]
    DNAT["<b>2. Regra de NAT do kube-proxy</b><ul><li>O destino vira o IP do Pod B</li><li>Pod B está no mesmo nó, na mesma bridge</li></ul>"]
    OFF["<b>3a. Sem br_netfilter</b><ul><li>A bridge entrega a resposta direto, sem passar pelo firewall</li><li>O conntrack não desfaz o NAT</li><li>Pod A recebe resposta de um IP que nunca contatou e descarta</li></ul>"]
    ON["<b>3b. Com br_netfilter e sysctl em 1</b><ul><li>A resposta passa pelo firewall do kernel</li><li>O conntrack reverte o NAT</li><li>Pod A enxerga a resposta vindo do IP do Service</li></ul>"]

    CALL --> DNAT
    DNAT --> OFF
    DNAT --> ON

    class CALL key;
    class DNAT neutral;
    class OFF failure;
    class ON success;

Sem o módulo, o Pod B responde diretamente ao Pod A pela bridge, sem que ninguém desfaça a tradução de endereço feita na ida. O Pod A espera uma resposta do IP do Service e recebe uma vinda do IP do Pod B. Descarta. A chamada simplesmente trava, e só quando o Service tem um endpoint no mesmo nó que quem chama. É o tipo de bug que "funciona na minha máquina" e quebra em produção quando o escalonador muda um pod de lugar.

Também por isso a ordem das tasks importa: as chaves net.bridge.* só existem no /proc/sys depois que o módulo br_netfilter é carregado. Rode o sysctl antes e o kernel responde cannot stat /proc/sys/net/bridge/bridge-nf-call-iptables: No such file or directory.

Usuário, diretórios e os CAs

Os últimos passos da role preparam o terreno para os arquivos do cluster:

# Trecho de ansible/k8s-cluster-base/tasks/01-instalacao.yml
- name: Criar usuário kubernetes
  ansible.builtin.user:
    name: kubernetes
    system: true
    shell: /usr/sbin/nologin
    home: /var/lib/kubernetes
    create_home: false

- name: Criar diretório de configuração
  ansible.builtin.file:
    path: "{{ item }}"
    state: directory
    owner: root
    group: kubernetes
    mode: "0750"
  loop:
    - /etc/kubernetes
    - /etc/kubernetes/pki

- name: Criar diretório de trabalho do Kubernetes
  ansible.builtin.file:
    path: /var/lib/kubernetes
    state: directory
    owner: kubernetes
    group: kubernetes
    mode: "0700"

A conta kubernetes é de sistema e não tem shell de login: ninguém entra por ela, ela só existe para ser dona de coisas. As permissões seguem o princípio do menor privilégio:

Nas próximas partes, você vai ver certificados e chaves nascendo com dono root, grupo kubernetes e modo 0640 ou 0644. A ideia é dar um dono e um grupo reconhecíveis aos arquivos do cluster, em vez de largar tudo como root:root, e deixar o acesso de leitura sob controle de quem pertence ao grupo.

O arquivo 02-pki.yml fecha a role. É o primeiro contato da PKI com os nós: ele copia, a partir da pasta de artefatos do host, os certificados dos três CAs intermediários (etcd, kubernetes e front-proxy) para /etc/kubernetes/pki, com modo 0644:

# Trecho de ansible/k8s-cluster-base/tasks/02-pki.yml
- name: Copiar certificados dos CAs
  ansible.builtin.copy:
    src: "{{ item.src }}"
    dest: "{{ item.dest }}"
    owner: root
    group: kubernetes
    mode: "{{ item.mode }}"
  loop:
    - src: "{{ pki_cas.etcd.path_cert }}"
      dest: "/etc/kubernetes/pki/{{ pki_cas.etcd.path_cert | basename }}"
      mode: "0644"
    # (...) o mesmo para o certificado do CA kubernetes e do CA front-proxy

Os certificados são públicos, então 0644 é razoável. A geração das chaves, as autoridades certificadoras e as emissões de cada par são tratadas na role de PKI.

Executando só o que importa

Se você quiser rodar exatamente o que este post cobre, sem seguir para o kubelet e o resto do control plane, o comando é um conjunto de tags:

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible-playbook ./ansible/cluster.yml \
    --tags cluster-artefatos,cluster-pki,cluster-sistema,cluster-kubernetes-base

As quatro tags correspondem às dependências que vimos: artefatos (baixa o Tailspin no host), PKI (gera os CAs), sistema (a infra-sistema) e cluster-kubernetes-base (a k8s-cluster-base). Pode haver um reboot no meio do caminho, quando o needs-restarting mandar. Se preferir o caminho completo de uma vez, make k8s-in-a-box faz tudo e você volta aqui para entender o que aconteceu.

Diagnóstico e Troubleshooting

Todos os comandos abaixo rodam do host, a partir da raiz do repositório, com as VMs ligadas (make up). A saída mostra o laboratório mini (um manager e dois workers), e a ordem dos hosts pode variar.

Swap desligado

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible cluster -m command -a "swapon --show"
manager1 | CHANGED | rc=0 >>

worker1 | CHANGED | rc=0 >>

worker2 | CHANGED | rc=0 >>

Saída vazia depois do >> é o resultado esperado: nenhum dispositivo de swap ativo. Para dupla checagem, free -h deve mostrar a linha de swap zerada.

Módulos de kernel carregados

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible cluster -m shell \
    -a "lsmod | awk '{print \$1}' | grep -xE 'overlay|br_netfilter|vxlan'"

Cada nó deve listar as três linhas, uma por módulo (a ordem varia). Se algum faltar, confira se o arquivo /etc/modules-load.d/kubernetes.conf existe e, em seguida, se a máquina reiniciou depois da instalação do kernel.

Parâmetros de sysctl

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible cluster -m command \
    -a "sysctl net.ipv4.ip_forward net.bridge.bridge-nf-call-iptables net.bridge.bridge-nf-call-ip6tables"
manager1 | CHANGED | rc=0 >>
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1

Os três valores precisam ser 1 em todos os nós. Se o comando reclamar de cannot stat, o módulo br_netfilter não está carregado.

Para confirmar que os valores sobrevivem a um reboot, veja o que foi gravado no arquivo:

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible cluster -m shell \
    -a "grep -E 'ip_forward|bridge-nf' /etc/sysctl.conf"

SELinux

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible todos -m command -a "getenforce"
manager1 | CHANGED | rc=0 >>
Permissive

Todas as máquinas de todos devem responder Permissive. O kubox é checado separadamente, porque recebe a role por outro playbook.

Resolução de nomes

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible todos -m command -a "getent hosts api.k8sbox.local"
manager1 | CHANGED | rc=0 >>
172.24.0.10     api.k8sbox.local etcd.k8sbox.local

Todas as máquinas precisam responder o IP do VIP. Lembre: use getent, não nslookup.

Usuário, diretórios e certificados dos CAs

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible cluster -b -m command \
    -a "stat -c '%U:%G %a %n' /etc/kubernetes /etc/kubernetes/pki /var/lib/kubernetes"
manager1 | CHANGED | rc=0 >>
root:kubernetes 750 /etc/kubernetes
root:kubernetes 750 /etc/kubernetes/pki
kubernetes:kubernetes 700 /var/lib/kubernetes

O -b (become) é necessário porque os diretórios têm modo 0750 e o usuário vagrant não pertence ao grupo kubernetes.

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible cluster -b -m shell \
    -a "stat -c '%a %U:%G %n' /etc/kubernetes/pki/*"
manager1 | CHANGED | rc=0 >>
644 root:kubernetes /etc/kubernetes/pki/ca-etcd-cert.pem
644 root:kubernetes /etc/kubernetes/pki/ca-front-proxy-cert.pem
640 root:kubernetes /etc/kubernetes/pki/ca-front-proxy-priv.pem
644 root:kubernetes /etc/kubernetes/pki/ca-k8s-cert.pem
640 root:kubernetes /etc/kubernetes/pki/ca-k8s-priv.pem

Se você pediu o mesmo comando a um worker, vai ver a saída idêntica, e as linhas priv são exatamente o alerta que fizemos há pouco.

Para a conta de sistema:

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible cluster -m shell \
    -a "getent passwd kubernetes | cut -d: -f1,6,7"
manager1 | CHANGED | rc=0 >>
kubernetes:/var/lib/kubernetes:/usr/sbin/nologin

Tailspin instalado

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible todos -m shell -a "command -v tspin"
manager1 | CHANGED | rc=0 >>
/usr/local/bin/tspin

Problemas comuns

Conclusão

Neste ponto, as VMs deixaram de ser servidores genéricos e viraram candidatas a nó. Todas se enxergam pelo nome, os nós têm memória de verdade, o kernel sabe rotear e deixa o firewall espiar as pontes, e existem uma conta, três diretórios e três certificados de CA esperando o resto da família chegar.

O que não existe ainda é o mais importante: nenhum binário do Kubernetes, nenhum serviço do cluster rodando, nenhum certificado de componente. Só a fundação, que ninguém elogia e todo mundo sente quando falta.

Dá para perceber que esses três CAs apareceram sem muita explicação. Chaves, CSRs, cadeias de confiança, mTLS e SANs parecem vocabulário puramente acadêmico até virarem a causa de um nó que se recusa a entrar no cluster. No próximo post (Parte 5: Certificados e a Infraestrutura de PKI (em breve)), vamos parar de rodar automações e dissecar, com calma e sem código de role, por que componentes distribuídos precisam provar quem são e como a PKI sustenta toda a segurança do Kubernetes.

Referências

A maioria dos desenvolvedores e operadores de infraestrutura aprendeu a usar contêineres como se fossem "máquinas virtuais mais leves e rápidas". Essa metáfora quebra galho para começar, mas ela é conceitualmente falsa. Contêineres não são máquinas virtuais. Não existe um hipervisor emulando placa-mãe, processador ou controladora SCSI. Não existe um segundo kernel dando boot silencioso no fundo da sua máquina. O que existe é um processo comum, rodando no mesmo kernel que o seu editor de texto e o seu navegador, só que usando uma coleira extremamente sofisticada fornecida pelo próprio sistema operacional.

Entender essa coleira é o divisor de águas entre o profissional que só sabe colar comandos do Stack Overflow e aquele que realmente resolve problemas quando o bicho pega em produção. Quando uma aplicação estoura o limite de memória e é abatida sem piedade pelo sistema operacional, quando duas instâncias brigam pela mesma porta de rede, ou quando você precisa projetar um cluster distribuído com Kubernetes, a abstração bonitinha do Docker desaparece. O que sobra é o kernel puro.

Este conhecimento também é o alicerce fundamental para a nossa série sobre criação de clusters locais com o projeto Kubernetes in a Box e para a etapa de empacotamento que veremos na Parte 14 da série Spring Boot Tutorial. Sem dominar o que é um contêiner por baixo do capô, tentar entender a arquitetura de Pods, Container Network Interface (CNI) ou Container Runtime Interface (CRI) vira mero exercício de decoreba.

Contêiner Não é VM: A Distinção que Muda Tudo

Para consolidar o funcionamento prático, precisamos sepultar de vez a ideia de que um contêiner é uma máquina virtual em miniatura.

Imagine a estrutura física de moradia. Uma máquina virtual é como uma casa isolada em seu próprio lote de terreno. Essa casa tem fundações de concreto próprias, caixa d'água exclusiva, gerador elétrico individual e seu próprio quadro de disjuntores. Se o encanamento dessa casa arrebentar, o problema fica restrito a ela. Em contrapartida, construir essa estrutura exige muito material, ocupa um espaço físico enorme e custa caro para manter aquecida.

Um contêiner é como um apartamento dentro de um edifício moderno. O apartamento tem paredes sólidas, fechadura na porta e total privacidade interior: os vizinhos não enxergam o que você faz dentro da sua sala. Porém, o apartamento compartilha toda a infraestrutura estrutural do edifício: a fundação de sustentação, os prumadas hidráulicas e as colunas de cabos elétricos. Essa infraestrutura compartilhada é o kernel Linux. Se a fundação de concreto do prédio sofrer um abalo estrutural gravíssimo (uma falha catastrófica de pânico no kernel), todos os apartamentos sentem o impacto imediatamente.

Em termos de arquitetura de computadores, a virtualização tradicional funciona por meio de um hipervisor (hypervisor). Em hipervisores do Tipo 1 (como VMware ESXi, KVM e Xen) ou do Tipo 2 (como VirtualBox e VMware Workstation), o software cria uma camada de emulação de hardware completa. Cada máquina virtual convidada (guest) acredita piamente que tem processadores x86 exclusivos, barramentos PCI, placas de rede Realtek ou Intel e controladoras de disco dedicadas. Por conta disso, cada máquina virtual precisa carregar um sistema operacional convidado completo: rodar o processo de inicialização (bootloader), subir um kernel próprio, inicializar serviços de sistema (como o systemd) e carregar drivers. Isso consome centenas de megabytes de memória RAM apenas para manter a máquina em espera, além de exigir minutos preciosos para reiniciar.

        VIRTUALIZAÇÃO (VM)                           CONTÊINERES

┌─────────────────────────────────┐       ┌─────────────────────────────────┐
│  App A   │   App B   │   App C  │       │  App A   │   App B   │   App C  │
├──────────┼───────────┼──────────┤       ├──────────┼───────────┼──────────┤
│ Libs /   │  Libs /   │  Libs /  │       │ Libs /   │  Libs /   │  Libs /  │
│ Bins     │  Bins     │  Bins    │       │ Bins     │  Bins     │  Bins    │
├──────────┼───────────┼──────────┤       ├──────────┴───────────┴──────────┤
│ Guest OS │ Guest OS  │ Guest OS │       │        Container Runtime        │
│ (Kernel) │ (Kernel)  │ (Kernel) │       │     (containerd, runc, crun)    │
├──────────┴───────────┴──────────┤       ├─────────────────────────────────┤
│           Hypervisor            │       │       Sistema Operacional       │
│       (KVM, Xen, VMware)        │       │       Host (Kernel Linux)       │
├─────────────────────────────────┤       ├─────────────────────────────────┤
│         Hardware Físico         │       │         Hardware Físico         │
└─────────────────────────────────┘       └─────────────────────────────────┘

Nos contêineres, essa camada de emulação de hardware simplesmente não existe. Quando você inicia um contêiner, o runtime não pede para uma CPU virtual dar boot. Ele simplesmente faz chamadas de sistema normais do Linux (como clone e execve) para criar um novo processo comum no sistema hospedeiro.

A diferença reside no fato de que esse novo processo recebe restrições estritas do kernel sobre o que ele pode visualizar e quantos recursos ele pode consumir. O tempo de inicialização cai de quarenta segundos para dez milissegundos porque criar um contêiner tem exatamente o mesmo custo computacional que iniciar qualquer programa na linha de comando.

Essa tabela deixa claro o que um contêiner realmente é: o resultado de três tecnologias nativas do kernel Linux trabalhando em uníssono. Os namespaces criam as paredes visuais de isolamento, os cgroups agem como o medidor de consumo de recursos, e os union filesystems estruturam o sistema de arquivos em camadas. Vamos analisar detalhadamente cada uma dessas peças.

Namespaces: Os Muros de Isolamento do Kernel

Se um contêiner é apenas um processo comum rodando no mesmo kernel do hospedeiro, surge a pergunta inevitável: como uma aplicação dentro do contêiner não enxerga os outros processos do servidor, não escuta conexões nas interfaces de rede de outras aplicações e não acessa os arquivos das outras pastas?

A resposta atende pelo nome de namespaces ¹.

Um namespace é uma camada de abstração do kernel Linux que envelopa recursos globais do sistema em partições isoladas. Quando um processo é colocado dentro de um namespace, ele passa a enxergar uma visão filtrada e privativa daquele recurso específico. Para todos os efeitos práticos, aquele processo tem a ilusão completa de que é a única entidade existente em toda a máquina.

O kernel Linux disponibiliza atualmente oito tipos diferentes de namespaces, cada um responsável por fatiar um subsistema específico:

A criação e manipulação desses muros é realizada por três chamadas de sistema fundamentais: clone() (que aceita as flags CLONE_NEW* para criar um processo filho já nascido em novos namespaces), unshare() (que desconecta o processo atual de seus namespaces herdados) e setns() (que anexa um processo em execução a um namespace preexistente).

Vamos deixar a teoria de lado e exercitar essas chamadas diretamente no terminal.

Isolamento de Processos: O Namespace PID

No Linux, todo processo possui um número identificador único chamado PID. O primeiro processo inicializado pelo kernel ao ligar a máquina recebe o PID 1 (tradicionalmente o /sbin/init ou o systemd). Todos os outros processos do sistema são descendentes diretos ou indiretos dele.

Quando você isola o namespace PID, o primeiro processo disparado dentro do novo ambiente recebe o PID 1 privativo. Ele se torna o processo pai de todas as tarefas daquele espaço. Ao mesmo tempo, ele perde totalmente a capacidade de enxergar ou enviar sinais de encerramento (kill) para qualquer processo que esteja no hospedeiro.

Vamos abrir uma sessão isolada usando o comando utilitário unshare ²:

# No host: conferir a quantidade massiva de processos normais
$ ps aux | head -n 5
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.0 169592 13092 ?        Ss   09:00   0:01 /sbin/init
root         2  0.0  0.0      0     0 ?        S    09:00   0:00 [kthreadd]
root         3  0.0  0.0      0     0 ?        I<   09:00   0:00 [rcu_gp]
root         4  0.0  0.0      0     0 ?        I<   09:00   0:00 [rcu_par_gp]

# Criar um namespace PID isolado disparando um novo shell bash
$ sudo unshare --pid --fork --mount-proc bash

# Dentro do novo ambiente: listar os processos ativos
$ ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.0   8536  5312 pts/0    S    14:00   0:00 bash
root         2  0.0  0.0  10072  3456 pts/0    R+   14:00   0:00 ps aux

A flag --mount-proc remonta o sistema de arquivos /proc no novo contexto; sem ela, o utilitário ps continuaria lendo a tabela de processos do host.

Repare no detalhe da chamada: a flag --fork é estritamente necessária porque a chamada de sistema unshare(CLONE_NEWPID) afeta apenas os processos filhos criados posteriormente. Para que o seu shell assuma o papel de PID 1 dentro do novo espaço, o utilitário precisa criar um processo filho bifurcado (forked).

Isolamento de Rede: O Namespace NET

O namespace de rede isola todos os artefatos relacionados à comunicação: tabelas de roteamento, regras de filtragem (iptables e nftables), sockets abertos e interfaces de rede físicas ou lógicas.

Quando um novo namespace NET é instanciado, ele nasce como um deserto digital:

# No hospedeiro: listar interfaces existentes
$ ip link
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether bc:24:11:43:82:aa brd ff:ff:ff:ff:ff:ff
3: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default
    link/ether 02:42:1a:de:99:11 brd ff:ff:ff:ff:ff:ff

# Disparar um namespace de rede isolado
$ sudo unshare --net bash

# Verificar as interfaces disponíveis no novo contexto
$ ip link
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00

# Tentar consultar tabelas de roteamento
$ ip route
# (absolutamente nada retornado)

O namespace de rede nasce isolado do mundo exterior, contendo exclusivamente a interface de loopback em estado desligado.

É exatamente por essa razão que um contêiner Docker recém-criado não interfere nas portas do seu computador hospedeiro. Se uma aplicação subir escutando na porta 80 dentro do contêiner, essa porta fica aberta apenas dentro do seu namespace de rede privativo. Para expô-la ao mundo exterior, ferramentas como o Docker criam pares de interfaces virtuais conectadas por um cabo de rede virtual imaginário (veth pair), plugando uma ponta dentro do contêiner e a outra em uma ponte de rede (bridge) no hospedeiro.

Isolamento de Hostname: O Namespace UTS

O namespace UTS (cujo nome histórico vem de UNIX Timesharing System) permite que um grupo de processos tenha seu próprio nome de máquina (hostname) e domínio de rede sem impactar o resto do sistema.

# Consultar nome original do host
$ hostname
meu-servidor-producao

# Criar namespace UTS e trocar o nome localmente
$ sudo unshare --uts bash
$ hostname conteiner-temporario
$ hostname
conteiner-temporario

# Sair da sessão isolada e conferir o host original
$ exit
$ hostname
meu-servidor-producao

O hostname configurado dentro da sessão isolada desaparece ao sair, mantendo a configuração do hospedeiro intacta.

Inspecionando os Namespaces no Próprio Linux

Toda essa mágica não fica escondida em estruturas de dados misteriosas. O Linux expõe os namespaces de qualquer tarefa em execução através do pseudo-sistema de arquivos /proc.

Se você listar a pasta /proc/<PID>/ns/, verá apontadores simbólicos especiais:

# Inspecionar os namespaces do seu próprio terminal
$ ls -la /proc/self/ns/
total 0
dr-x--x--x 2 usuario usuario 0 set  8 14:00 .
dr-xr-xr-x 9 usuario usuario 0 set  8 14:00 ..
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 cgroup -> 'cgroup:[4026531835]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 ipc -> 'ipc:[4026531839]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 mnt -> 'mnt:[4026531841]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 net -> 'net:[4026531840]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 pid -> 'pid:[4026531836]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 pid_for_children -> 'pid:[4026531836]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 time -> 'time:[4026531834]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 time_for_children -> 'time:[4026531834]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 user -> 'user:[4026531837]'
lrwxrwxrwx 1 usuario usuario 0 set  8 14:00 uts -> 'uts:[4026531838]'

Os números entre colchetes representam o identificador de inode do namespace no kernel; dois processos compartilham o mesmo namespace se os números de inode forem idênticos.

Agora veja a prova cabal. Vamos subir um contêiner com o Docker e inspecionar os mesmos apontadores a partir do sistema operacional hospedeiro:

# Subir um contêiner alpine dormindo em segundo plano
$ docker run -d --name teste-namespaces alpine sleep 3600

# Descobrir o PID do processo sleep no hospedeiro
$ CONTAINER_PID=$(docker inspect -f '{{.State.Pid}}' teste-namespaces)
$ echo "O PID real no hospedeiro é: $CONTAINER_PID"
O PID real no hospedeiro é: 28419

# Comparar os namespaces do contêiner com os do hospedeiro
$ ls -l /proc/$CONTAINER_PID/ns/net /proc/1/ns/net
lrwxrwxrwx 1 root root 0 set  8 14:05 /proc/1/ns/net -> 'net:[4026531840]'
lrwxrwxrwx 1 root root 0 set  8 14:05 /proc/28419/ns/net -> 'net:[4026532455]'

Os números de inode são completamente diferentes, comprovando que o processo do contêiner vive em um namespace de rede próprio.

O Segredo do Comando docker exec: nsenter

Quando você roda docker exec -it teste-namespaces sh, o Docker não cria um contêiner novo nem faz conexões remotas via SSH. Ele simplesmente descobre o PID do processo principal do contêiner no hospedeiro e executa a chamada de sistema setns() para colocar um novo terminal dentro dos mesmos namespaces já utilizados por aquele contêiner.

O utilitário de linha de comando que faz isso diretamente no Linux chama-se nsenter ³:

# Entrar nos namespaces do contêiner usando apenas ferramentas padrão do Linux
$ sudo nsenter --target $CONTAINER_PID --pid --net --mount --uts --ipc sh

# Agora estamos dentro da visão do contêiner
/ # hostname
teste-namespaces
/ # ps aux
PID   USER     TIME  COMMAND
    1 root      0:00 sleep 3600
    7 root      0:00 sh
    8 root      0:00 ps aux
/ # exit

O comando nsenter anexa o terminal aos namespaces do processo alvo sem depender do daemon do Docker.

Cgroups: O Guarda de Recursos

Os namespaces resolvem com brilhantismo a questão da visibilidade: eles garantem que os processos não enxerguem o que não devem. Mas imagine a seguinte situação: você cria um contêiner em um namespace isolado, mas uma linha de código maliciosa ou mal implementada dispara um laço infinito que aloca memória sem parar ou cria milhares de threads simultâneas.

Se dependêssemos apenas de namespaces, esse contêiner solitário consumiria 100% da CPU do computador, esgotaria toda a memória física do hospedeiro e causaria o travamento total do sistema operacional, derrubando todos os outros contêineres que dividem o mesmo servidor.

Para resolver o problema do consumo desenfreado de hardware, entram em cena os Control Groups ou simplesmente cgroups ⁴.

Se o namespace representa a parede de alvenaria do seu apartamento, o cgroup é a caixa de disjuntores e o hidrômetro: ele determina rigidamente quanta corrente elétrica e quantos litros de água aquele cômodo tem permissão para puxar da rede principal.

No Linux, os cgroups não são configurados por meio de interfaces obscuras ou comandos mágicos. Eles são implementados como um pseudo-sistema de arquivos montado tradicionalmente no caminho /sys/fs/cgroup/. Isso significa que, para criar um grupo de controle, limitar recursos e associar processos a ele, basta usar operações básicas de sistema de arquivos: criar pastas com mkdir e escrever valores numéricos em arquivos de texto com comandos simples como echo.

A Grande Mudança: Cgroups v1 versus Cgroups v2

Durante muitos anos, o Linux utilizou a primeira versão dos grupos de controle (cgroups v1). No modelo v1, cada recurso (CPU, memória, entrada e saída de disco, identificadores de processo) vivia em uma hierarquia de diretórios totalmente separada e independente dentro de /sys/fs/cgroup/. Um processo podia pertencer ao grupo limite-baixo na hierarquia de memória, mas pertencer ao grupo prioridade-alta na hierarquia de CPU.

Na prática, gerenciar essa matriz multidimensional virou um pesadelo de complexidade para os desenvolvedores de sistemas operacionais. Além disso, surgiam inconsistências graves: o controlador de memória não conversava direito com o controlador de gravação em disco (writeback cache), gerando bloqueios misteriosos de I/O.

Para solucionar essas dores, o engenheiro Tejun Heo liderou a reestruturação que deu origem aos cgroups v2 (também conhecida como Unified Hierarchy ou hierarquia unificada) ⁵. No cgroups v2, existe apenas uma árvore de diretórios unificada. Um processo pertence a exatamente um cgroup, e todos os controladores de recursos habilitados para aquele grupo são aplicados de forma consistente sobre os mesmos processos.

Você pode verificar qual versão está em operação no seu sistema inspecionando as montagens:

# Verificar o tipo de montagem ativa em /sys/fs/cgroup
$ mount | grep cgroup
cgroup2 on /sys/fs/cgroup type cgroup2 (rw,nosuid,nodev,noexec,relatime,nsdelegate)

Se a saída indicar o tipo cgroup2, seu sistema já opera com a moderna hierarquia unificada adotada por padrão em distribuições recentes como Debian 12+, Ubuntu 22.04+ e Fedora.

Os principais controladores de recursos disponíveis no cgroups v2 e seus arquivos correspondentes são apresentados na tabela a seguir:

Criando e Testando um Cgroup Manualmente

Vamos construir um grupo de controle na mão, sem recorrer ao Docker, para ver a mecânica pura do kernel em ação.

Primeiro, garantimos que os controladores desejados estejam habilitados para delegação na raiz dos cgroups:

# Habilitar controladores de memória e processos para os subdiretórios
$ echo "+memory +pids" | sudo tee /sys/fs/cgroup/cgroup.subtree_control
+memory +pids

# Criar um novo grupo de controle chamado laboratorio-cgroup
$ sudo mkdir /sys/fs/cgroup/laboratorio-cgroup

# Inspecionar os arquivos gerados automaticamente pelo kernel dentro da nova pasta
$ ls /sys/fs/cgroup/laboratorio-cgroup/
cgroup.controllers      cgroup.procs            memory.high             memory.stat
cgroup.events           cgroup.stat             memory.max              pids.current
cgroup.freeze           cgroup.subtree_control  memory.min              pids.events
cgroup.kill             memory.current          memory.oom.group        pids.max

O simples fato de criar um diretório faz o kernel popular instantaneamente a pasta com as interfaces de controle do cgroup v2.

Agora vamos estabelecer limites rígidos para este grupo: um teto de 50 megabytes de memória RAM e um limite de no máximo 20 processos simultâneos:

# Definir o limite de memória em bytes (50 MB = 52428800 bytes)
$ echo "52428800" | sudo tee /sys/fs/cgroup/laboratorio-cgroup/memory.max
52428800

# Definir o limite máximo de processos (pids)
$ echo "20" | sudo tee /sys/fs/cgroup/laboratorio-cgroup/pids.max
20

# Conferir se as configurações foram gravadas
$ cat /sys/fs/cgroup/laboratorio-cgroup/memory.max
52428800

Valores gravados nesses arquivos são imediatamente assumidos pelo subsistema de alocação de memória do kernel.

Para colocar um processo sob a tutela desse cgroup, basta escrever o número do seu PID dentro do arquivo cgroup.procs. Vamos anexar a sessão atual do nosso terminal (representada pela variável especial $$):

# Mover o shell atual para dentro do cgroup criado
$ echo $$ | sudo tee /sys/fs/cgroup/laboratorio-cgroup/cgroup.procs

# Consultar o consumo atual de memória da nossa sessão em bytes
$ cat /sys/fs/cgroup/laboratorio-cgroup/memory.current
1925120

O shell consome aproximadamente 1.8 MB de memória RAM; o kernel rastreia a contabilidade em tempo real com precisão de bytes.

O Guarda em Ação: O Assassino OOM (Out of Memory Killer)

O que acontece se uma aplicação que vive dentro de um cgroup tentar ultrapassar o teto estipulado no arquivo memory.max?

O kernel Linux entra em ação através do mecanismo OOM Killer (Out of Memory Killer). Ele avalia os processos pertencentes àquele grupo específico e envia um sinal fatal SIGKILL para eliminar a aplicação gulosa, protegendo a estabilidade de todo o restante do servidor hospedeiro.

Vamos forçar essa situação usando o Docker com limites declarados:

# Subir um contêiner limitado a meros 30 MB de RAM e tentar forçar o consumo de 60 MB
$ docker run --name teste-estouro --memory=30m alpine sh -c \
    "head -c 60M /dev/zero | tail -c +1 > /dev/null"

# Inspecionar o motivo do encerramento do contêiner
$ docker inspect teste-estouro --format='Status: {{.State.Status}} | OOMKilled: {{.State.OOMKilled}} | ExitCode: {{.State.ExitCode}}'
Status: exited | OOMKilled: true | ExitCode: 137

O código de saída 137 indica terminação por sinal fatal (128 + 9 para SIGKILL), acompanhado pelo marcador OOMKilled configurado como verdadeiro.

Se você consultar as mensagens de diagnóstico do kernel no mesmo instante com o comando dmesg, verá o registro oficial do evento:

$ sudo dmesg -T | tail -n 6
[...] oom-kill:constraint=CONSTRAINT_MEMCG,nodemask=(null),cpuset=docker-...
[...] memory: usage 30720kB, limit 30720kB, failcnt 1
[...] Memory cgroup out of memory: Killed process 31405 (sh) total-vm:63280kB, anon-rss:29840kB

O kernel deixa registrado explicitamente que o encerramento ocorreu por restrição do grupo de controle de memória (CONSTRAINT_MEMCG).

Union Filesystems: Imagens em Camadas

Chegamos à terceira perna do nosso tripé fundamental. Até aqui, vimos como os namespaces isolam a visão dos processos e como os cgroups limitam o consumo de memória e processamento. Mas resta um problema crucial: de onde vem o sistema de arquivos que o contêiner enxerga?

Se você baixar uma imagem oficial do Ubuntu, ela tem cerca de 80 megabytes. Se você precisar rodar cem contêineres idênticos desse mesmo Ubuntu no mesmo servidor, copiar 80 MB cem vezes gastaria 8 gigabytes de espaço em disco e demoraria vários segundos durante a clonagem.

A solução elegante encontrada pelo ecossistema de contêineres é o uso de Sistemas de Arquivos de União (Union Filesystems), materializados no Linux moderno pelo driver de kernel OverlayFS ⁶.

A Mecânica do Copy-on-Write (CoW)

A ideia central de um sistema de arquivos de união é sobrepor múltiplos diretórios de forma transparente, apresentando para quem consome o ponto de montagem a ilusão de um único diretório unificado.

As imagens de contêiner são compostas por uma pilha de camadas estáticas somente leitura (read-only). Cada comando executado no processo de construção de uma imagem gera uma nova fatia fina gravada em disco. Quando você inicia um contêiner baseado nessa imagem, o runtime não duplica esses dados: ele simplesmente adiciona uma camada finíssima e efêmera de leitura e escrita (read-write) no topo de toda a pilha.

A regra de ouro desse modelo chama-se Copy-on-Write (CoW):

1. Operação de Leitura: Se a sua aplicação ler um arquivo que pertence à imagem base, o sistema acessa diretamente o arquivo na camada inferior somente leitura.
2. Operação de Modificação: No milissegundo em que sua aplicação tenta alterar um arquivo existente da imagem base, o OverlayFS intercepta a chamada, faz uma cópia idêntica daquele arquivo para a camada superior de escrita e aplica a alteração exclusivamente na cópia. O arquivo original na camada inferior permanece 100% intocado.
3. Operação de Criação: Qualquer novo arquivo criado vai direto para a camada superior de escrita.
4. Operação de Remoção: Se um arquivo da camada base for apagado, o OverlayFS cria um arquivo especial de bloqueio (whiteout file) na camada de escrita, ocultando o arquivo original da visão unificada.

┌─────────────────────────────────────────────────────────┐
│              VISÃO UNIFICADA DO CONTÊINER               │  <- Diretório "merged"
│            /app  /etc  /usr  /bin  /tmp                 │     (o processo enxerga isto)
├─────────────────────────────────────────────────────────┤
│          CAMADA DE ESCRITA EFÊMERA (R/W)                │  <- Diretório "upperdir"
│     Arquivos criados ou modificados pelo contêiner      │     (morre com o contêiner)
├─────────────────────────────────────────────────────────┤
│          CAMADA DA IMAGEM: COPY app.jar (R/O)           │  <- Diretório "lowerdir[0]"
├─────────────────────────────────────────────────────────┤
│          CAMADA DA IMAGEM: RUN apt-get install (R/O)    │  <- Diretório "lowerdir[1]"
├─────────────────────────────────────────────────────────┤
│          CAMADA BASE: FROM debian:bookworm (R/O)        │  <- Diretório "lowerdir[2]"
└─────────────────────────────────────────────────────────┘

O OverlayFS estrutura essa mágica dividindo a operação em quatro diretórios fundamentais:

• lowerdir: Os diretórios base somente leitura (as camadas da imagem). Múltiplos caminhos podem ser encadeados separando-os por dois-pontos.
• upperdir: O diretório de leitura e escrita onde ficam as modificações efetuadas pelo contêiner.
• workdir: Uma pasta de serviço interna necessária para o kernel preparar operações atômicas antes de exibi-las.
• merged: O diretório final onde o sistema de arquivos unificado é montado e disponibilizado para consumo.

Montando um OverlayFS na Mão

Para entender isso em definitivo, nada melhor do que criar as camadas e montá-las manualmente sem usar nenhum comando do Docker:

# Criar a estrutura física dos diretórios no /tmp
$ mkdir -p /tmp/experimento-overlay/{base,escrita,trabalho,unificado}

# Criar arquivos simulando uma camada base de sistema operacional
$ echo "Configuracao padrao v1.0" > /tmp/experimento-overlay/base/sistema.conf
$ echo "Binario utilitario" > /tmp/experimento-overlay/base/ferramenta.sh
$ chmod +x /tmp/experimento-overlay/base/ferramenta.sh

# Montar o OverlayFS usando o utilitário padrão de montagem do Linux
$ sudo mount -t overlay overlay \
    -o lowerdir=/tmp/experimento-overlay/base,upperdir=/tmp/experimento-overlay/escrita,workdir=/tmp/experimento-overlay/trabalho \
    /tmp/experimento-overlay/unificado

# Listar o conteúdo da visão unificada
$ ls /tmp/experimento-overlay/unificado/
ferramenta.sh  sistema.conf

# Conferir o conteúdo do arquivo lido da camada base
$ cat /tmp/experimento-overlay/unificado/sistema.conf
Configuracao padrao v1.0

A pasta unificada expõe perfeitamente os arquivos que fisicamente residem dentro da pasta base.

Agora, vamos observar o comportamento do Copy-on-Write alterando um arquivo e criando um item inédito:

# Modificar o arquivo existente através do diretório unificado
$ echo "Configuracao customizada pelo usuario" > /tmp/experimento-overlay/unificado/sistema.conf

# Criar um arquivo novo dentro da visão unificada
$ echo "Arquivo gerado em execucao" > /tmp/experimento-overlay/unificado/novo.log

# O arquivo original na camada base PERMANECE INTACTO
$ cat /tmp/experimento-overlay/base/sistema.conf
Configuracao padrao v1.0

# O arquivo modificado e o arquivo novo foram parar no diretório de escrita (upperdir)
$ ls /tmp/experimento-overlay/escrita/
novo.log  sistema.conf

$ cat /tmp/experimento-overlay/escrita/sistema.conf
Configuracao customizada pelo usuario

# Desmontar o sistema de arquivos de teste
$ sudo umount /tmp/experimento-overlay/unificado

A camada base permaneceu imutável; toda e qualquer alteração foi gravada exclusivamente dentro do diretório de escrita.

Quando você roda docker rm meu-conteiner, tudo o que o Docker precisa fazer em disco é deletar o diretório upperdir correspondente. As camadas da imagem base nunca foram alteradas, e por isso podem ser compartilhadas concorrentemente por centenas de contêineres sem risco de corrupção cruzada.

A Especificação OCI e o Ecossistema de Runtimes

Nos primeiros anos de vida do Docker, toda essa orquestração de chamadas de sistema era centralizada em um daemon monolítico e proprietário. À medida que grandes empresas começaram a adotar contêineres para cargas de trabalho críticas, surgiu o receio de que o formato ficasse refém dos rumos comerciais de uma única empresa.

Para sanar essa preocupação, a indústria se uniu sob a tutela da Linux Foundation e instituiu a Open Container Initiative (OCI). O trabalho da OCI gerou três padrões fundamentais abertos que regem o universo de contêineres até hoje:

1. OCI Image Specification: Define como uma imagem deve ser empacotada em disco. Uma imagem OCI nada mais é do que um conjunto de arquivos compactados (tarballs) contendo as camadas de arquivos do sistema, acompanhados de um manifesto em formato JSON descrevendo arquitetura de hardware, variáveis de ambiente, portas e comandos de entrada.
2. OCI Runtime Specification: Define como pegar aquele sistema de arquivos descompactado e executá-lo no sistema operacional. Ela descreve a estrutura de um arquivo padronizado chamado config.json, que lista os namespaces que devem ser criados, os limites de cgroups e os privilégios do processo.
3. OCI Distribution Specification: Padroniza a API HTTP para publicação, busca e transferência de imagens entre registros de contêineres (como Docker Hub, Quay.io, GitHub Container Registry e Amazon ECR).

A Cadeia de Execução Moderna

Graças à padronização OCI, o ecossistema de execução foi modularizado em camadas independentes de responsabilidade:

┌──────────────┐
│  docker CLI  │  Interface com o usuário (interpreta comandos e flags)
└──────┬───────┘
       │  API REST (via socket unix /var/run/docker.sock)
       ▼
┌──────────────┐
│   dockerd    │  Daemon de gerenciamento (imagens, volumes, redes e API)
└──────┬───────┘
       │  gRPC
       ▼
┌──────────────┐
│  containerd  │  Runtime de Alto Nível (baixa imagens, gerencia ciclo de vida)
└──────┬───────┘
       │  Execução OCI
       ▼
┌──────────────┐
│     runc     │  Runtime de Baixo Nível (chama clone, unshare, cgroups e morre)
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Processo   │  Sua aplicação rodando isolada dentro do kernel
└──────────────┘

Repare na separação nítida:

• O Runtime de Alto Nível (como containerd ou CRI-O) é responsável por baixar imagens pela rede, validar assinaturas criptográficas, descompactar camadas em disco e preparar o sistema de arquivos montado.
• O Runtime de Baixo Nível (como runc ou crun) tem um papel estritamente pontual: ele recebe uma pasta já montada com um arquivo config.json, invoca as chamadas de sistema do kernel (unshare, mount, configuração de cgroup), executa o binário da sua aplicação e em seguida se encerra, deixando o processo isolado rodando supervisionado pelo kernel.

O Raio-X do config.json da OCI

Você pode comprovar que um contêiner não passa de uma pasta com um arquivo JSON utilizando o próprio runc ⁷ instalado no sistema.

Vamos gerar uma especificação padrão de contêiner OCI:

# Criar uma pasta temporária para o nosso pacote OCI
$ mkdir -p /tmp/bundle-oci && cd /tmp/bundle-oci

# Gerar o arquivo de configuração de referência da OCI
$ runc spec

# Inspecionar as primeiras linhas do arquivo gerado
$ head -n 35 config.json
{
	"ociVersion": "1.0.2-dev",
	"process": {
		"terminal": true,
		"user": {
			"uid": 0,
			"gid": 0
		},
		"args": [
			"sh"
		],
		"env": [
			"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
			"TERM=xterm"
		],
		"cwd": "/"
	},
	"root": {
		"path": "rootfs",
		"readonly": true
	},
	"hostname": "runc",
	"mounts": [
		{
			"destination": "/proc",
			"type": "proc",
			"source": "proc"
		}

O arquivo config.json padroniza universalmente cada parâmetro de execução do processo.

Se você rolar o arquivo até a seção linux, encontrará exatamente as estruturas de dados que estudamos nas seções anteriores deste post:

"namespaces": [
	{ "type": "pid" },
	{ "type": "network" },
	{ "type": "ipc" },
	{ "type": "uts" },
	{ "type": "mount" }
]

Qualquer ferramenta que gere essa pasta com essa estrutura consegue rodar um contêiner em qualquer distribuição Linux do planeta. É a interoperabilidade levada ao estado da arte.

Grand Finale: Construindo um Mini-Contêiner do Zero

Chegou a hora de juntar todas as peças. Nós vimos a história, entendemos por que contêineres não são máquinas virtuais, exploramos os namespaces, configuramos cgroups na mão e montamos camadas com OverlayFS.

Agora, vamos provar a tese inicial: um contêiner é apenas um processo com a coleira do kernel.

Abaixo está o código de um script em Bash funcional com cerca de 50 linhas úteis. Ele faz absolutamente tudo o que o Docker faz por baixo do capô quando você roda docker run: baixa uma distribuição Linux mínima oficial (Alpine Linux), monta as camadas com OverlayFS preservando a imagem intacta, cria um cgroup v2 com limites estritos de memória e quantidade de processos, isola todos os namespaces necessários e entrega um terminal interativo com o processo assumindo o PID 1.

#!/bin/bash
# mini-conteiner.sh: Um motor de contêineres funcional em ~50 linhas de shell script
# Uso: sudo ./mini-conteiner.sh
set -euo pipefail

CONTAINER_DIR="/tmp/mini-conteiner-lab"
ALPINE_VERSION="3.20"
ALPINE_ARCH="x86_64"
ALPINE_URL="https://dl-cdn.alpinelinux.org/alpine/v${ALPINE_VERSION}/releases/${ALPINE_ARCH}/alpine-minirootfs-${ALPINE_VERSION}.0-${ALPINE_ARCH}.tar.gz"
CGROUP_NAME="mini-conteiner-$$"
MEMORY_LIMIT="104857600"  # Limite estrito de 100 MB em bytes
PIDS_LIMIT="50"           # Limite máximo de 50 processos

echo "==> [1/6] Preparando estrutura de diretórios do OverlayFS..."
mkdir -p "${CONTAINER_DIR}"/{rootfs,upper,work,merged}

echo "==> [2/6] Obtendo imagem base oficial do Alpine Linux ${ALPINE_VERSION}..."
if [ ! -f "${CONTAINER_DIR}/alpine.tar.gz" ]; then
    curl -fsSL "${ALPINE_URL}" -o "${CONTAINER_DIR}/alpine.tar.gz"
    tar xzf "${CONTAINER_DIR}/alpine.tar.gz" -C "${CONTAINER_DIR}/rootfs"
fi

echo "==> [3/6] Montando sistema de arquivos OverlayFS (camadas CoW)..."
mount -t overlay overlay \
    -o "lowerdir=${CONTAINER_DIR}/rootfs,upperdir=${CONTAINER_DIR}/upper,workdir=${CONTAINER_DIR}/work" \
    "${CONTAINER_DIR}/merged"

echo "==> [4/6] Configurando limites de recursos via Cgroup v2 (${CGROUP_NAME})..."
# Garante que os controladores de memória e processos estejam delegáveis aos subdiretórios
echo "+memory +pids" > /sys/fs/cgroup/cgroup.subtree_control 2>/dev/null || true
CGROUP_PATH="/sys/fs/cgroup/${CGROUP_NAME}"
mkdir -p "${CGROUP_PATH}"
echo "${MEMORY_LIMIT}" > "${CGROUP_PATH}/memory.max"
echo "${PIDS_LIMIT}" > "${CGROUP_PATH}/pids.max"

echo "==> [5/6] Preparando arquivos de configuração (DNS)..."
mkdir -p "${CONTAINER_DIR}/merged/etc"
cat << 'EOF' > "${CONTAINER_DIR}/merged/etc/resolv.conf"
nameserver 1.1.1.1
nameserver 8.8.8.8
EOF

echo "==> [6/6] Inicializando processo isolado em novos Namespaces..."
echo "     Ambiente pronto! Digite 'exit' para sair e liberar os recursos."
echo ""

# unshare isola PID, rede, hostname, IPC, pontos de montagem e cgroups
# Pseudo-sistemas (/proc, /sys, /dev) são montados no namespace privado do contêiner
unshare --pid --fork --net --uts --ipc --mount --cgroup \
    sh -c "
        echo \$\$ > '${CGROUP_PATH}/cgroup.procs' 2>/dev/null || true
        mount -t proc proc '${CONTAINER_DIR}/merged/proc'
        mount -t sysfs sysfs '${CONTAINER_DIR}/merged/sys'
        mount --bind /dev '${CONTAINER_DIR}/merged/dev'
        exec chroot '${CONTAINER_DIR}/merged' /bin/sh -c '
            hostname mini-conteiner
            export PATH=/bin:/sbin:/usr/bin:/usr/sbin
            echo \"==================================================\"
            echo \"  BEM-VINDO AO SEU CONTÊINER ARTESANAL!\"
            echo \"  Hostname: \$(hostname)\"
            echo \"  PID local: \$\$\"
            echo \"  Memória limitada a: 100 MB\"
            echo \"==================================================\"
            exec /bin/sh
        '
    "

echo ""
echo "==> Finalizando e desmontando camadas com segurança..."
sleep 1
umount -l "${CONTAINER_DIR}/merged" 2>/dev/null || true
rmdir "${CGROUP_PATH}" 2>/dev/null || true
echo "==> Limpeza concluída com sucesso."

Script autossuficiente demonstrando a convergência prática de namespaces, cgroups v2 e OverlayFS.

Entendendo a Mecânica Passo a Passo

A elegância desse script reside no fato de que cada bloco de código espelha diretamente os conceitos que dissecamos ao longo de todo o texto:

O primeiro bloco prepara as quatro pastas exigidas pelo driver OverlayFS. O segundo passo faz o papel do comando docker pull: ele baixa um arquivo comprimido de apenas três megabytes contendo os binários do Alpine Linux e descompacta o conteúdo na pasta rootfs. Essa pasta atua como a nossa camada inferior imutável (lowerdir).

No terceiro passo, o script realiza a montagem do OverlayFS. O diretório merged passa a ser a nossa visão consolidada, enquanto a pasta upper acolherá qualquer arquivo modificado pelo usuário durante o teste.

No quarto passo, o script fala diretamente com o subsistema cgroups v2 do kernel: habilita os controladores para delegação aos subgrupos em cgroup.subtree_control, cria a pasta correspondente ao grupo de controle do contêiner e grava os limites de cem megabytes de RAM e cinquenta identificadores de processo.

O quinto passo cuida da configuração básica de rede, gravando diretamente servidores de DNS públicos em /etc/resolv.conf para evitar conflitos com o resolvedor local em stub (127.0.0.53) do systemd-resolved.

No sexto passo, a grande mágica se concretiza: o utilitário unshare dispara novas instâncias de todos os seis namespaces essenciais. No namespace privado de montagem recém-criado, o script monta os pseudo-sistemas de arquivos /proc, /sys e /dev (garantindo que o /proc reflita exclusivamente a tabela de processos do novo contêiner e que essas montagens desapareçam do hospedeiro assim que o namespace for encerrado). Antes de entregar o terminal ao usuário, o shell grava o seu próprio identificador de processo dentro do arquivo cgroup.procs daquele cgroup, garantindo que os limites de hardware passem a valer imediatamente. Em seguida, a chamada exec chroot substitui o processo atual pelo /bin/sh assumindo rigorosamente o PID 1.

Ao digitar exit, a rotina de encerramento entra em ação: desmonta o ponto OverlayFS e remove o diretório do cgroup, devolvendo o sistema operacional hospedeiro exatamente ao estado em que se encontrava.

Exercícios

Para fixar a dinâmica de isolamento do kernel, namespaces, cgroups e OverlayFS, execute os desafios práticos abaixo no seu terminal Linux.

1. Criando Rootless com User Namespaces

Crie um namespace de usuário (User Namespace) sem utilizar privilégios de sudo, mapeando o seu usuário atual para o usuário root dentro da sessão isolada através do comando:

$ unshare --user --map-root-user bash

Dentro dessa nova sessão, execute os comandos whoami e id. Em seguida, abra outro terminal no seu hospedeiro, descubra o PID desse novo shell bash e verifique com qual usuário ele está registrado no sistema executando ps -o user,pid,comm -p <PID>. O que você observa e por que esse mecanismo é crucial para a segurança de contêineres modernos?

2. O Bloqueio de Fork Bombs com o Controller de PIDs

Suba um contêiner em segundo plano restringindo o número total de processos simultâneos com um teto de segurança (por exemplo, --pids-limit=20):

$ docker run -d --name teste-pids --pids-limit=20 alpine sleep 3600

Em seguida, conecte-se a ele via terminal interativo (docker exec -it teste-pids sh) e dispare a clássica fork bomb de shell do ecossistema Unix:

/ # :(){ :|:& };:

O que acontece a partir do momento em que a função recursiva atinge o limite? Como o hospedeiro se comporta e qual métrica no cgroup confirma a contenção?

sh: can't fork: Resource temporarily unavailable

3. Múltiplas Camadas e Resolução de Conflitos no OverlayFS

Crie duas pastas de base diferentes: /tmp/overlay-multi/camada1 contendo um arquivo app.env com o texto AMB=producao e /tmp/overlay-multi/camada2 contendo um arquivo app.env com o texto AMB=desenvolvimento. Monte um OverlayFS passando ambas no parâmetro lowerdir com a sintaxe lowerdir=/tmp/overlay-multi/camada2:/tmp/overlay-multi/camada1. Qual conteúdo é exibido ao ler app.env no diretório montado e qual é a regra de precedência do kernel?

4. Investigando o Mini-Contêiner a Partir do Hospedeiro

Execute o script mini-conteiner.sh. Enquanto o terminal interno estiver ativo aguardando comandos, abra outro terminal comum no seu hospedeiro e execute os seguintes passos de investigação:

1. Localize o processo do contêiner com ps aux | grep mini-conteiner.
2. Compare a lista de namespaces de /proc/<PID>/ns/ do processo localizado com os namespaces do processo 1 do host.
3. Consulte o arquivo /sys/fs/cgroup/mini-conteiner-<PID>/memory.current para averiguar o consumo de RAM em bytes.
4. Volte ao terminal do contêiner e execute ps aux. Quantos processos aparecem? Como você explica essa diferença gritante entre a visão do hospedeiro e a visão interna?

O Que Vem na Parte 2

Chegamos ao fim da primeira metade da nossa jornada.

Neste post, despimos o contêiner de todos os seus mitos de marketing. Você viu que não há mágica nem virtualização pesada: existem namespaces estabelecendo o que os processos conseguem ver, cgroups limitando o que eles conseguem gastar de hardware, e sistemas de arquivos de união entregando imagens em camadas sem desperdício de disco. Vimos também como a especificação da OCI padronizou essa fundação em componentes modulares como o runc e o containerd.

Mas vamos ser francos: ninguém em sã consciência vai ficar escrevendo scripts manuais em shell script e calculando offsets de montagem de OverlayFS toda vez que precisar colocar uma API em produção às três horas da tarde de uma sexta-feira.

É exatamente aqui que entram as ferramentas modernas de engenharia.

Na Parte 2 da nossa série (em breve), vamos subir para a camada de ferramentas e práticas do mundo real:

• Anatomia avançada de Dockerfiles: como estruturar construções em múltiplos estágios (multi-stage builds) eficientes para compilar aplicações pesadas gerando imagens de produção com menos de cem megabytes;
• O ciclo de vida do contêiner: as diferenças operacionais críticas entre estados de pausa, parada graciosa com tratamento de sinais SIGTERM e extermínio abrupto com SIGKILL;
• Redes no Docker: a arquitetura de pontes virtuais (bridge), tabelas de roteamento e resolução interna de nomes via DNS integrado;
• Docker Compose: como orquestrar múltiplos serviços interligados com bancos de dados, filas e caches em uma stack completa;
• A revolução do Podman: a arquitetura sem daemons centralizados (daemonless), contêineres sem privilégios (rootless) por padrão e a criação nativa de Pods no modelo do Kubernetes;
• Segurança de contêineres: análise de vulnerabilidades em imagens, restrição de capacidades administrativas do Linux (capabilities) e os perigos fatais de montar o socket do Docker em ambientes compartilhados.

Nos vemos na Parte 2 para colocar toda essa fundação em prática no mundo real.

Referências

Para quem só quer conectar o celular ou o notebook com um mínimo de controle e desempenho, essa automação de desktop mais atrapalha do que ajuda.

A minha dúvida era bem prática: tenho um computador rodando Debian Trixie, conectado no cabo de rede e com uma placa Intel Wi-Fi 6E AX211 sobrando ali. Será que consigo transformar essa placa num Access Point moderno pra atender meus dispositivos móveis? A ideia era montar algo enxuto: Wi-Fi 6 (802.11ax), WPA3-Personal puro (SAE) e regras simples de nftables, sem mágica de interface gráfica.

A resposta curta é sim, dá pra fazer. A resposta longa é que o processo virou uma caça aos motivos de o rádio simplesmente se recusar a emitir sinal, esbarrando em microcódigo da Intel, travas regulatórias e mensagens crípticas no dmesg.

O ponto de partida: o hardware da máquina

Antes de sair chutando parâmetros de rádio no escuro, o jeito mais prático é olhar o que realmente está espetado na máquina. Tentar adivinhar configuração sem saber qual driver ou firmware está no comando é o caminho mais rápido pra perder horas sem sair do lugar.

A máquina onde fiz os testes é um desktop rodando Debian Trixie. As peças do quebra-cabeça:

O detalhe fundamental dessa tabela é o controlador Intel AX211 com arquitetura CNVi (Connectivity Interface). Diferente de adaptadores PCIe tradicionais onde o processador e o rádio moram na mesma plaquinha dedicada, no modelo CNVi a Intel resolveu dividir o casamento: o cérebro lógico do Wi-Fi fica soldado dentro do chipset da placa-mãe (PCH), enquanto o slot M.2 abriga só os transceptores analógicos de radiofrequência (CRF).

Essa intimidade profunda entre a placa-mãe e o rádio significa uma coisa bem simples: você não manda em quase nada. O microcódigo da Intel tem rédea curta sobre o que o hardware pode ou não fazer, e ele não aceita desaforo do sistema operacional.

A ideia: separando as peças sem depender do desktop

A tentação mais comum ao criar um hotspot no Linux é deixar o NetworkManager cuidar de tudo: ele cria uma ponte virtual, sobe um dnsmasq temporário onde bem entender e joga um punhado de regras legadas de iptables.

O problema é que o NetworkManager se comporta igual àquele estagiário excessivamente proativo: você não pediu nada, mas ele vê uma interface dando sopa, assume o controle sem avisar, tenta adivinhar o que você quer e, no primeiro sinal de instabilidade, reseta o link ou decide unilateralmente que a interface virou "não gerenciável". Pra um AP que você só quer deixar quieto funcionando no canto, essa boa vontade é a receita perfeita pra dor de cabeça.

Em vez de brigar com o desktop, a saída foi chutar o NetworkManager pra longe e separar as responsabilidades em camadas simples:

┌────────────────────────────────────────────────────────┐
│               PILHA DE SOFTWARE PURA (AP)              │
│                                                        │
│  [NetworkManager]  ──> Isolar interface (unmanaged)    │
│         │                                              │
│  [ifupdown / L3]   ──> Fixar IP estático no boot       │
│         │              (/etc/network/interfaces)       │
│  [dnsmasq / L7]    ──> Subir DHCP e DNS exclusivo      │
│         │              (Sub-rede 192.168.100.0/24)     │
│  [hostapd / L1-L2] ──> Subir rádio 802.11ax + WPA3     │
│         │              (Canal 13, SAE puro, CCMP)      │
│  [nftables / L3-L4]──> Forwarding e NAT Masquerade     │
│                        (Regras atômicas sem iptables)  │
└────────────────────────────────────────────────────────┘

Cada peça tem uma função direta:

1. Camada L3 Estática (ifupdown): Assume a interface wlp0s20f3, garantindo um IP fixo logo no boot sem interferência de applets de desktop.
2. Camada de Suporte L7 (dnsmasq): Entrega DHCP rápido e DNS na sub-rede sem fio, escutando estritamente nessa interface.
3. Camada de Rádio L1/L2 (hostapd): Controla a sinalização do rádio 802.11ax, os beacons e o handshake criptográfico em WPA3-Personal (SAE) via Netlink (nl80211).
4. Camada de Encaminhamento L3/L4 (nftables): Faz a filtragem de estados via conntrack e aplica o NAT Masquerade em direção à placa cabeada enp0s31f6.

Na teoria, era só subir os serviços e conectar. Na prática, o rádio tinha outros planos.

O primeiro tropeço: por que o rádio se recusa a emitir

Com os arquivos rascunhados, iniciei os serviços pro primeiro teste. O comando sudo systemctl start hostapd rodou de primeira e o status parecia animador:

● hostapd.service - Access point and authentication server for Wi-Fi and Ethernet
     Loaded: loaded (/usr/lib/systemd/system/hostapd.service; enabled; preset: enabled)
     Active: active (running) since Sun 2026-09-28 10:15:22 -03; 4s ago
...
Sep 28 10:15:22 debian hostapd[14205]: wlp0s20f3: interface state UNINITIALIZED->COUNTRY_UPDATE
Sep 28 10:15:22 debian hostapd[14205]: wlp0s20f3: interface state COUNTRY_UPDATE->ENABLED
Sep 28 10:15:22 debian hostapd[14205]: wlp0s20f3: AP-ENABLED

O hostapd reportava com todas as letras: AP-ENABLED. Na teoria, o ponto de acesso estava no ar e transmitindo.

Peguei o celular, abri o painel de redes sem fio e nada. O SSID não aparecia na lista de varredura. Esperei alguns minutos, forcei novas buscas e nada mudou. Não havia sinal sendo emitido.

Fui ao terminal investigar o estado da interface com o utilitário ip:

ip addr show wlp0s20f3

O resultado expôs a contradição:

3: wlp0s20f3: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000
    link/ether 02:00:00:00:00:01 brd ff:ff:ff:ff:ff:ff
    inet 192.168.100.1/24 brd 192.168.100.255 scope global wlp0s20f3
       valid_lft forever preferred_lft forever

Como é possível o hostapd indicar que o ponto de acesso está habilitado (AP-ENABLED) enquanto o kernel Linux classifica o link como state DOWN e com a flag NO-CARRIER ativa?

O paradoxo do AP-ENABLED com interface em state DOWN

Essa discrepância entre o que o software jura que está fazendo e o que o hardware realmente entrega é a clássica divisão de mundos do Linux: o espaço de usuário (userspace) vive de otimismo; o kernel vive da realidade física do silício.

O hostapd opera em userspace. Para conversar com os adaptadores modernos, ele conversa via Netlink usando a família nl80211 ¹. Quando o serviço sobe, ele despacha mensagens pedindo a criação do BSSID lógico, aloca as estruturas em memória e avisa ao subsistema cfg80211 que o AP está autorizado a rodar. Na cabeça do hostapd, o dever foi cumprido: tá autorizado, logo AP-ENABLED.

Só que o kernel Linux não cai em papo furado. Uma interface de rede só abandona a flag NO-CARRIER e atinge o estado state UP quando o rádio físico reporta que a portadora está ligada de verdade (LOWER_UP). No cabo de rede, é quando o conector detecta tensão elétrica no cobre. No Wi-Fi, é quando o chip efetivamente liga o transmissor, sintoniza a frequência e joga os primeiros beacons 802.11 no ar.

Se o hostapd comemora que o AP subiu, mas a interface continua em NO-CARRIER no kernel, a constatação é límpida (depois de perder um belo par de horas quebrando a cabeça): o microcódigo da Intel simplesmente puxou o freio de mão e se recusou a transmitir um mísero watt de sinal.

A armadilha do Location Aware Regulatory e o perfil country 00

Ao investigar por que a interface teimava em não emitir sinal no início dos testes, executei o comando de auditoria regulatória do subsistema sem fio:

sudo iw reg get

A saída foi esclarecedora:

global
country BR: DFS-FCC
    (2400 - 2483 @ 40), (N/A, 30), (N/A)
    (5150 - 5250 @ 80), (N/A, 27), (N/A), NO-OUTDOOR, AUTO-BW
    (5250 - 5350 @ 80), (N/A, 27), (0 ms), NO-OUTDOOR, DFS, AUTO-BW
    (5470 - 5725 @ 160), (N/A, 27), (0 ms), DFS, AUTO-BW
    (5725 - 5850 @ 80), (N/A, 30), (N/A), AUTO-BW
    (5925 - 7125 @ 320), (N/A, 12), (N/A), NO-OUTDOOR

phy#0 (self-managed)
country 00: DFS-UNSET
    (2402 - 2437 @ 40), (6, 22), (N/A), AUTO-BW, NO-HT40MINUS, NO-80MHZ, NO-160MHZ
    (2422 - 2462 @ 40), (6, 22), (N/A), AUTO-BW, NO-80MHZ, NO-160MHZ
    (2447 - 2482 @ 40), (6, 22), (N/A), AUTO-BW, NO-HT40PLUS, NO-80MHZ, NO-160MHZ
    (5170 - 5190 @ 160), (6, 22), (N/A), NO-OUTDOOR, AUTO-BW, IR-CONCURRENT, NO-HT40MINUS, NO-320MHZ, PASSIVE-SCAN
    (5735 - 5755 @ 160), (6, 22), (N/A), AUTO-BW, IR-CONCURRENT, NO-HT40MINUS, NO-320MHZ, PASSIVE-SCAN

Observe a divergência entre as duas seções da saída:

1. A seção global informa country BR, refletindo o banco de dados regulatório que o sistema operacional tentou carregar (wireless-regdb).
2. A seção física phy#0 exibe a indicação self-managed, vinculada ao código universal country 00: DFS-UNSET.

Essa distinção explica uma dúvida muito comum: por que executar sudo iw reg set BR altera o global, mas não surte efeito nenhum na placa phy#0?

No subsistema sem fio do Linux (cfg80211), os adaptadores dividem-se em duas categorias:

• Placas gerenciadas pelo kernel: Em chipsets abertos como MediaTek (mt7921e) ou Atheros (ath9k), o driver repassa a autoridade regulatória diretamente para o kernel. Quando você roda iw reg set BR, o sistema atualiza as frequências e potências da interface física quase de imediato.
• Placas com domínio auto-gerenciado (self-managed): Os adaptadores da Intel possuem a flag interna WIPHY_FLAG_CUSTOM_REGULATORY. Ao carregar o módulo iwlwifi ², a placa avisa ao kernel que ela mesma manda nas próprias regras a partir de tabelas gravadas na memória OTP (One-Time Programmable) durante a fabricação. O microcódigo simplesmente ignora os seus palpites.

E quando há conflito entre o que o sistema operacional quer e o que a placa física declara, a regra do kernel é implacável: a restrição mais severa sempre vence. Se o sistema operacional autoriza canais abertos e potência alta no Brasil, mas a tabela gravada no silício da placa (phy#0) bate o pé dizendo que o canal é restrito ou passivo, não tem conversa: o hardware vence e o kernel senta e chora.

Para coroar a burocracia, os adaptadores Intel vêm equipados com o famigerado LAR (Location Aware Regulatory) ³.

O LAR foi desenhado sob a premissa de mobilidade em notebooks: a placa escuta os roteadores ao redor para descobrir se você pousou em Guarulhos ou em Frankfurt antes de emitir rádio. Só tem um pequeno detalhe: o meu computador não sai da minha mesa e passa a maior parte da sua vida espetado na tomada da parede e ligado no cabo de rede. Não tem a menor chance de esse gabinete acordar subitamente na Baviera. Mas a Intel insiste em tratá-lo como se fosse um ultrabook passeando no saguão de um aeroporto internacional.

A lógica do LAR funciona em três passos:

1. Para descobrir em que canto do planeta está operando, a placa precisa conectar-se como cliente (STA) a algum ponto de acesso ou escutar passivamente anúncios periódicos de quadros 802.11d com o código do país (Country IE).
2. Se múltiplos roteadores vizinhos confirmarem que estão no Brasil, o próprio microcódigo da Intel valida o consenso e atualiza a tabela da placa para BR.
3. Mas quando tentamos usar a placa puramente como ponto de acesso autônomo (Master/AP), ela não se conecta a ninguém para herdar essa validação geográfica.

Resultado: sem o consenso de outros rádios vizinhos, a placa assume a paranoia máxima e recua para o perfil mundial de contingência: o country 00.

E o que dita o perfil country 00?

• Faixa de 5 GHz e 6 GHz: recebe as diretivas mandatórias PASSIVE-SCAN e NO-IR (No Initiate Radiation), proibindo categoricamente qualquer emissão de beacons como AP.
• Faixa de 2.4 GHz: a transmissão é autorizada de 2402 a 2482 MHz, mas com uma trava explícita: NO-HT40PLUS na faixa superior (canais agregados de 40 MHz para cima são sumariamente vetados).

Somado a isso, o NetworkManager rodando em paralelo vivia tentando assumir o controle da interface, forçando-a para baixo toda vez que o hostapd inicializava. Para isolar as variáveis e estabelecer um ponto de partida limpo e estável, o primeiro passo foi blindar a interface contra o NetworkManager e configurar o rádio no canal canônico mais seguro da literatura: o canal 6 (channel=6), com largura fixa de 20 MHz.

A evidência no dmesg: os erros de microcódigo do firmware Intel

Durante a bateria de testes com o módulo AX211, experimentei combinações mais agressivas de parâmetros High Efficiency (HE) e canais de 40 MHz em frequências limítrofes.

A resposta do hardware foi imediata. Ao consultar o buffer de mensagens do kernel com dmesg -T, encontrei o registro de reinício do microcódigo:

[Sun Sep 28 10:22:09 2026] iwlwifi 0000:00:14.3: Microcode SW error detected. Restarting 0x0.
[Sun Sep 28 10:22:09 2026] iwlwifi 0000:00:14.3: Loaded firmware version: 89.4d42c933.0 so-a0-gf-a0-89.ucode
[Sun Sep 28 10:22:09 2026] iwlwifi 0000:00:14.3: 0x00000084 | ADVANCED_SYSASSERT

O microcódigo so-a0-gf-a0-89.ucode, rodando no microcontrolador dedicado do AX211, encontrou uma combinação de parâmetros pedida pelo driver iwlmvm que violava as tabelas rígidas da sua memória.

Em vez de devolver um erro civilizado para o kernel, o firmware entrou em pânico (ADVANCED_SYSASSERT) e puxou a tomada do próprio chip (Restarting 0x0). O driver do Linux teve que recarregar o arquivo .ucode do zero, derrubando a interface e desconectando tudo no susto.

O recado da Intel foi direto e sem meias palavras: ou você joga pelas regras estritas do microcódigo, ou a placa vai reiniciar na sua cara toda vez que você tentar inventar moda.

A tentação do 5 GHz na faixa UNII-3 e o veto definitivo de silício

Durante a auditoria aprofundada das tabelas de radiofrequência com iw phy phy0 info, uma descoberta parecia abrir uma brecha tentadora no bloqueio da Intel.

Embora toda a faixa baixa de 5 GHz (canais 36 a 144) estivesse carimbada com no IR, os canais altos da faixa UNII-3 (canais 149 a 165, de 5745 a 5825 MHz) exibiam uma condição diferente:

Frequencies:
    * 5745.0 MHz [149] (22.0 dBm)
    * 5765.0 MHz [153] (22.0 dBm)
    * 5785.0 MHz [157] (22.0 dBm)
    * 5805.0 MHz [161] (22.0 dBm)
    * 5825.0 MHz [165] (22.0 dBm)

No Brasil, sob regulamentação da Anatel e em conformidade com as regras da FCC, a faixa UNII-3 não divide frequências com radares meteorológicos (dispensando o complexo mecanismo DFS) e autoriza emissão de maior potência. Como a placa havia escutado passivamente o ambiente e herdado temporariamente o código geográfico country BR: DFS-UNSET, a flag restritiva de no IR parecia ter desaparecido desses cinco canais.

A ideia era tentadora: por que me contentar com os 286 Mbps da faixa de 2.4 GHz se dava pra tentar o canal 149 com canais agregados de 80 MHz (vht_oper_chwidth=1, he_oper_chwidth=1) e buscar taxas bem mais altas no Wi-Fi 6?

Ajustei o hostapd.conf para operar em 5 GHz no canal 149 e reiniciei o daemon. O log de depuração (hostapd -d) mostrou exatamente onde o microcódigo barra a operação:

wlp0s20f3: interface state UNINITIALIZED->COUNTRY_UPDATE
Previous country code BR, new country code BR 
nl80211: Regulatory information - country=00
...
nl80211: 5735-5755 @ 160 MHz 22 mBm (no IR)
Frequency 5745 (primary) not allowed for AP mode, flags: 0x20053 NO-IR
Primary frequency not allowed
wlp0s20f3: IEEE 802.11 Hardware does not support configured channel
Could not select hw_mode and channel. (-3)
wlp0s20f3: AP-DISABLED 

O log expõe com exatidão onde o firmware da Intel puxa o freio de mão:

1. A ilusão da escuta passiva: Enquanto a placa atua apenas escutando o ar em silêncio (scan passivo), o firmware tolera a indicação de country BR. Dá a falsa impressão de que a frequência alta está pronta pra uso.
2. O bloqueio ao ligar a transmissão: No milissegundo em que o hostapd tenta colocar a interface em modo Master e ligar o transmissor em 5 GHz, a memória de fábrica do chip (OTP) assume o controle. O microcódigo ignora solenemente a instrução do sistema operacional e força o perfil mundial de contingência (country=00).
3. O recuo forçado: Sob country=00, o canal 149 recebe a trava 0x20053 NO-IR (proibido iniciar transmissão). O subsistema cfg80211 do kernel acata a ordem do silício, recusa a operação e derruba a interface para AP-DISABLED.

O motivo dessa sabotagem é uma mistura de regulação e contenção de custos ⁴. Os adaptadores AX201 e AX211 foram homologados internacionalmente apenas como dispositivos clientes (estações móveis). Testar e certificar um transmissor para operar como ponto de acesso autônomo (Master AP) em 5 GHz e 6 GHz exige processos de homologação caríssimos e baterias de testes de conformidade de radar (DFS) que a Intel não quis pagar para placas de desktop/laptop. Para blindar os seus próprios advogados contra multas de órgãos reguladores mundo afora, a fabricante trancou o microcódigo no silício: você comprou o hardware, mas quem decide onde ele pode transmitir são os advogados da Intel.

Se o seu objetivo de vida for montar um roteador Linux moderno operando em 5 GHz ou 6 GHz a 1.200 Mbps ou 2.400 Mbps, esqueça a Intel. A saída definitiva no mundo open source é trocar o módulo M.2 por chipsets MediaTek ⁵ (como o MT7921 ou MT7922). A MediaTek adotou a postura elegante de manter drivers 100% livres no kernel (mt7921e), sem essa palhaçada de LAR e autorizando operação Master plena em 5 GHz.

No ecossistema Intel AX, contudo, a realidade é essa: o canal de 2.4 GHz em 20 MHz é o único refúgio seguro onde o microcódigo nos deixa brincar em paz.

A falácia do atualizar o kernel resolve tudo

Em fóruns e discussões na internet, a resposta automática para qualquer problema envolvendo drivers Wi-Fi no Linux é o clichê habitual: "compila o kernel 6.13, 6.14 ou espera o Linux 7.x nos backports que resolve".

Essa recomendação ignora a fronteira física do problema:

1. O que não muda com kernels novos: A trava regulatória do LAR e as restrições NO-IR em 5 GHz/6 GHz para modo AP residem no firmware e na memória OTP gravada no silício pela Intel. Nenhum kernel, por mais recente que seja, tem o poder de sobrepor essa verificação sem que você adulterasse o código do driver e recompilasse o microcódigo fechado da Intel.
2. O que muda de verdade com kernels novos: A evolução da árvore principal do kernel traz melhorias reais na sincronização de filas de transmissão concorrentes (txqs), redução de race conditions no driver iwlwifi quando múltiplos dispositivos comunicam-se via Wi-Fi 6 e suporte a revisões mais recentes da API de firmware (como as transições da API 80 para a 89 e 90).

No nosso caso, o kernel Debian padrão (Linux 6.12) com o firmware da série 89 provou-se totalmente estável, contanto que as restrições do rádio fossem respeitadas na camada de configuração.

A pilha de produção: configuração limpa e determinística

Com a causa raiz compreendida e os limites do hardware devidamente mapeados, passamos à implementação da pilha de produção. Cada componente foi configurado de forma declarativa e com inicialização gerenciada pelo systemd.

Isolamento e endereçamento estático no ifupdown

Para que o hostapd assuma a interface sem que o NetworkManager tente desconectá-la ou atribuir endereços via DHCP de terceiros, declaramos o dispositivo diretamente no /etc/network/interfaces.

No Debian, o NetworkManager respeita por padrão os dispositivos configurados no ifupdown e os coloca em modo não gerenciado (unmanaged):

# /etc/network/interfaces
auto wlp0s20f3
iface wlp0s20f3 inet static
    address 192.168.100.1
    netmask 255.255.255.0

Configuração estática da camada L3 para o adaptador sem fio.

Para fechar qualquer brecha onde o NetworkManager pudesse recapturar a interface após um reinício de sessão gráfica ou atualização de pacote, adicionamos uma regra de blindagem explícita no /etc/NetworkManager/conf.d/99-unmanaged.conf:

# /etc/NetworkManager/conf.d/99-unmanaged.conf
[keyfile]
unmanaged-devices=interface-name:wlp0s20f3

Blindagem definitiva para impedir qualquer interferência de daemons de desktop.

Essa configuração combinada garante que, durante a fase de inicialização da rede (networking.service), a interface wlp0s20f3 receba imediatamente o endereço de gateway 192.168.100.1/24, ficando totalmente invisível para os applets de bandeja do desktop.

Serviços de suporte: DHCP e DNS com dnsmasq

Para distribuir endereços e resolver nomes com agilidade, o dnsmasq ⁶ continua imbatível: consome meia dúzia de megabytes de RAM e responde quase instantaneamente.

O arquivo /etc/dnsmasq.conf foi moldado para isolar o serviço estritamente na interface sem fio, sem vazar requisições para a rede cabeada (enp0s31f6):

# /etc/dnsmasq.conf
interface=wlp0s20f3
listen-address=192.168.100.1
bind-dynamic
dhcp-range=192.168.100.10,192.168.100.100,255.255.255.0,12h
dhcp-option=option:dns-server,1.1.1.1,8.8.8.8

Configuração do dnsmasq com amarração dinâmica na interface sem fio.

O parâmetro bind-dynamic aqui é o segredo: diferente do rígido bind-interfaces, ele permite que o dnsmasq aguarde e se vincule à interface assim que ela receber o IP estático, sem capotar o serviço com erro de socket se o daemon subir alguns milissegundos antes da rede durante o boot.

A camada de rádio: hostapd com Wi-Fi 6 e WPA3 puro

Esta é a peça central do quebra-cabeça. O /etc/hostapd/hostapd.conf reúne as diretivas de rádio para operar em 2.4 GHz contornando o LAR da Intel, mas ativando os recursos do padrão 802.11ax (Wi-Fi 6) ⁷ e a segurança do WPA3-Personal puro (SAE):

# /etc/hostapd/hostapd.conf
interface=wlp0s20f3
driver=nl80211
ssid=Debian-Hotspot-AX

# Domínio regulatório e governança de RF
country_code=BR
ieee80211d=1

# Socket UNIX para gerência e telemetria com hostapd_cli
ctrl_interface=/run/hostapd
ctrl_interface_group=0

# Banda e Canal (2.4 GHz - Canal 13 fora do engarrafamento)
hw_mode=g
channel=13

# Otimização física: Preâmbulo Curto (96 µs vs 192 µs)
preamble=1

# Criptografia WPA3-Personal Puro (SAE) e blindagem contra timing attacks
wpa=2
wpa_key_mgmt=SAE
rsn_pairwise=CCMP
ieee80211w=2
sae_pwe=2
wpa_passphrase=SuaSenhaForteAqui

# QoS e alicerce do Wi-Fi 4 (WMM obrigatório para HT/HE)
wmm_enabled=1
ieee80211n=1
ht_capab=[SHORT-GI-20][TX-STBC][RX-STBC1]

# Wi-Fi 6 (802.11ax - High Efficiency)
ieee80211ax=1
he_su_beamformer=1
he_su_beamformee=1
he_oper_chwidth=0

dtim_period=2

Arquivo hostapd.conf afinado no canal 13 com WPA3-SAE, extensões 802.11ax e preâmbulo curto.

Para entender o que cada uma dessas diretivas está orquestrando no rádio:

• Identificação da interface e sinalização (interface, driver, ssid, country_code, ieee80211d):
  • interface=wlp0s20f3: O nome do adaptador físico gerado pelo systemd com base no barramento PCIe/CNVi.
  • driver=nl80211: A interface Netlink moderna do Linux. Esqueça drivers legados como wext: o nl80211 é a única pilha que conversa nativamente com as extensões 802.11n, ac e ax.
  • country_code=BR e ieee80211d=1: Injeta nos beacons periódicos o código do Brasil. Isso avisa aos clientes conectados em que país estão operando, alinhando as potências de transmissão às normas locais.
  • ssid=Debian-Hotspot-AX: O nome da rede que vai aparecer nos dispositivos.
• Socket de controle local (ctrl_interface, ctrl_interface_group):
  • ctrl_interface=/run/hostapd: Cria o socket UNIX para que utilitários como o hostapd_cli consultem métricas de sinal, modulação e estados de associação em tempo real sem precisar reiniciar o serviço.
  • ctrl_interface_group=0: Restringe o socket ao root para que nenhum processo não autorizado invente de mexer no rádio.
• Banda, canal deserto e corte de overhead (hw_mode, channel, preamble):
  • hw_mode=g: Define a operação na faixa de 2.4 GHz. Mesmo operando em Wi-Fi 6, o hostapd exige o modo base g para montar o mapa inicial de frequências antes de injetar as extensões modernas.
  • channel=13: Frequência central de 2472 MHz em 20 MHz de largura. No perfil country 00, a faixa alta de 2.4 GHz não possui a trava NO-IR. Enquanto os canais 1, 6 e 11 viviam engarrafados pelos vizinhos, o canal 13 revelou-se um refúgio totalmente limpo.
  • preamble=1: Força o preâmbulo curto na camada física (PLCP). O preâmbulo longo herdado do 802.11b consome 192 µs de sinalização a cada pacote; ao cortar para 96 µs, sobra mais tempo útil de ar (airtime) para transferir dados de verdade.

• WPA3-Personal puro e blindagem de enlace (wpa, wpa_key_mgmt, rsn_pairwise, ieee80211w, sae_pwe):
  • wpa_key_mgmt=SAE: Ativa o Simultaneous Authentication of Equals (RFC 7664), base do WPA3. Adeus PSK tradicional: o handshake Dragonfly usa prova de conhecimento zero, tornando capturas de ar totalmente imunes a ataques de dicionário offline com Hashcat ou Aircrack-ng.
  • sae_pwe=2: Força o método Hash-to-Element (H2E). Isso blinda a negociação contra os ataques de canal lateral conhecidos como Dragonblood, que exploravam variações de tempo no método antigo de caça-e-bicagem.
  • ieee80211w=2: Torna os Protected Management Frames (PMF, 802.11w) estritamente obrigatórios. Com ele, até os quadros de gerência da rede são assinados, neutralizando aqueles ataques clássicos de derrubar clientes injetando pacotes de desautenticação (deauth flood).
  • E o isolamento de clientes? Se o seu objetivo for um hotspot para visitantes, vale adicionar a diretiva ap_isolate=1 para impedir que os clientes se enxerguem na camada L2. Como no meu caso a rede atende exclusivamente os meus próprios aparelhos (e eu quero transferir arquivos locais entre celular e notebook sem intermediários), deixei o parâmetro de fora.
• Wi-Fi 6 High Efficiency e QoS (wmm_enabled, ieee80211n, ht_capab, ieee80211ax, he_*):
  • wmm_enabled=1: Habilita as filas de QoS (IEEE 802.11e). Parâmetro obrigatório: sem WMM, as especificações 802.11n e 802.11ax rebaixam compulsoriamente a conexão para o teto de 54 Mbps do jurássico 802.11g.
  • ht_capab=[SHORT-GI-20][TX-STBC][RX-STBC1]: Ativa o intervalo de guarda curto (400 ns) e o Space-Time Block Coding, que ajuda o sinal a contornar reflexões nas paredes do cômodo transmitindo cópias redundantes e ortogonais pelas antenas.
  • ieee80211ax=1: Aciona o motor do Wi-Fi 6 (High Efficiency), liberando o uso de subportadoras densas e a modulação 1024-QAM.
  • he_su_beamformer=1: Ativa a formação de feixe (beamforming). O AP analisa o estado do canal reportado pelo smartphone e ajusta a fase do sinal em cada antena para que as ondas se somem de forma construtiva exatamente onde o aparelho está.

Firewall moderno e roteamento com nftables

Com o rádio transmitindo e os endereços sendo distribuídos, o passo final é garantir que os pacotes da rede sem fio cheguem à internet pela placa cabeada enp0s31f6.

Primeiro, habilitamos o encaminhamento de pacotes no kernel criando o arquivo de persistência no sysctl:

# /etc/sysctl.d/99-ip-forward.conf
net.ipv4.ip_forward=1

Habilitação do roteamento IPv4 no kernel Linux.

Para aplicar imediatamente sem reiniciar:

sudo sysctl -p /etc/sysctl.d/99-ip-forward.conf

Antes, eu resolvia esse roteamento com três regras clássicas e imperativas de iptables:

sudo iptables -t nat -A POSTROUTING -s 192.168.100.0/24 -o enp0s31f6 -j MASQUERADE
sudo iptables -A FORWARD -i wlp0s20f3 -o enp0s31f6 -j ACCEPT
sudo iptables -A FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT

As três regras clássicas de iptables para NAT e encaminhamento de pacotes.

Essas três linhas resolvem o básico perfeitamente. No entanto, no Debian moderno o framework padrão do Netfilter é o nftables ⁸. Em vez de manter comandos soltos em scripts de inicialização ou depender de pacotes legados de persistência (iptables-persistent), o caminho mais limpo é consolidar essa tradução direta de forma declarativa e atômica no /etc/nftables.conf:

#!/usr/sbin/nft -f

flush ruleset

table inet filter {
    chain input {
        type filter hook input priority filter; policy accept;
    }
    chain forward {
        type filter hook forward priority filter; policy drop;
        ct state { established, related } accept
        iifname "wlp0s20f3" oifname "enp0s31f6" accept
    }
    chain output {
        type filter hook output priority filter; policy accept;
    }
}

table ip nat {
    chain postrouting {
        type nat hook postrouting priority srcnat; policy accept;
        ip saddr 192.168.100.0/24 oifname "enp0s31f6" masquerade
    }
}

Regras nativas do nftables com correspondência direta às três regras de iptables.

Note como a tradução entre os dois modelos é direta e sem rodeios:

1. ct state { established, related } accept: Substitui exatamente o -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT, permitindo que respostas de pacotes que saíram voltem sem impedimentos.
2. iifname "wlp0s20f3" oifname "enp0s31f6" accept: É a tradução de -i wlp0s20f3 -o enp0s31f6 -j ACCEPT, autorizando os pacotes que chegam pelo Wi-Fi a cruzarem em direção à interface cabeada. No nftables, a política padrão do chain forward foi definida como drop, fechando o encaminhamento para qualquer outro sentido.
3. ip saddr 192.168.100.0/24 oifname "enp0s31f6" masquerade: Faz exatamente o mesmo papel do -t nat -A POSTROUTING -s 192.168.100.0/24 -o enp0s31f6 -j MASQUERADE, reescrevendo o IP de origem dos pacotes para o IP da interface cabeada.

Para carregar o conjunto de regras e garantir persistência nos próximos boots:

sudo systemctl enable --now nftables

Telemetria real: 286 Mbps, 1024-QAM e WPA3 em 2.4 GHz

Com a pilha completa rodando, conectei um smartphone com suporte a Wi-Fi 6 à rede recém-criada. O aparelho associou-se no mesmo instante, exibindo o ícone de rede segura com o numeral 6 ao lado das barrinhas de sinal.

A ironia do momento é deliciosa: compramos uma placa batizada com pompa de Wi-Fi 6E, com suporte teórico a 6 GHz, canais nababescos de 160 MHz e promessa de gigabits por segundo, para no final do dia comemorar 286 Mbps cravados em 2.4 GHz no canal 13. É o equivalente exato a comprar uma Ferrari para rodar na primeira marcha em estrada de terra de condomínio rural. Mas hey: é uma Ferrari perfeitamente regulada, com WPA3 puro e sem bater na lataria dos vizinhos.

Para auditar o que estava acontecendo na camada física do rádio, consultei o subsistema de rede com a ferramenta iw:

sudo iw dev wlp0s20f3 station dump

A telemetria coletada no host confirmou a negociação das taxas:

Station 22:39:6c:xx:xx:xx (on wlp0s20f3)
    inactive time:  3448 ms
    rx bytes:       1442331
    rx packets:     8110
    tx bytes:       733731
    tx packets:     2580
    signal:         -29 [-29, -42] dBm
    tx bitrate:     286.7 MBit/s HE-MCS 11 HE-NSS 2 HE-GI 0 HE-DCM 0
    authorized:     yes
    authenticated:  yes
    associated:     yes
    preamble:       short
    WMM/WME:        yes
    MFP:            yes
    DTIM period:    2
    short preamble: yes
    connected time: 573 seconds

Os dados dessa captura merecem uma leitura honesta:

• Taxa de transferência teórica vs. prática: O link cravou em 286.7 MBit/s de TX. Na norma IEEE 802.11ax, um canal de 20 MHz com modulação 1024-QAM (MCS 11) e Guard Interval curto (0.8 µs) entrega 143.38 Mbps por stream. Multiplicado por dois fluxos espaciais (HE-NSS 2), batemos no teto físico absoluto de 286.8 Mbps. Só não confunda taxa física (PHY) com milagre: descontando o overhead de pacotes, colisões e confirmações do CSMA/CA, a vazão real utilizável (goodput em TCP medido via iperf3) fica na casa dos 180 a 200 Mbps. Para navegar no celular e rodar vídeos em 4K, é mais do que sobra.
• Preâmbulo curto ativo (preamble: short): A diretiva preamble=1 negociada com a estação poupou 96 µs de sinalização a cada pacote transmitido.
• Modulação no talo (HE-MCS 11): O rádio sustentou a modulação mais densa da norma: 1024-QAM, empacotando 10 bits por símbolo sob um sinal cristalino de -29 dBm.
• Proteção de quadros confirmada (MFP: yes): O hardware atestou o Management Frame Protection, garantindo que ninguém derruba o link com ataques bobos de desautenticação.

Para fechar o diagnóstico de segurança, consultei o estado da associação através do socket do hostapd_cli:

sudo hostapd_cli all_sta

O relatório retornou os detalhes da negociação criptográfica:

22:39:6c:xx:xx:xx
flags=[AUTH][ASSOC][AUTHORIZED][SHORT_PREAMBLE][WMM][MFP][HT][HE]
dot11RSNAStatsSelectedPairwiseCipher=00-0f-ac-4 (CCMP-128)
AKMSuiteSelector=00-0f-ac-8 (SAE / WPA3-Personal)
sae_group=19 (NIST P-256 Curve)

A negociação WPA3-Personal foi concluída com sucesso: o seletor AKM foi definido em 00-0f-ac-8 (SAE puro), com a curva elíptica NIST P-256 (sae_group=19) e cifras CCMP-128 para os dados em trânsito.

Conferindo o espectro com o WiFiman no celular

Para verificar o comportamento da rede do ponto de vista de quem está na ponta, abri o aplicativo WiFiman no próprio smartphone para auditar o espectro de radiofrequência ao redor.

A inspeção em campo trouxe resultados ainda mais interessantes:

• O oásis no espectro: No gráfico de densidade de radiofrequência, os canais 1, 6 e 11 aparecem tomados por uma sobreposição caótica de redes institucionais e corporativas competindo pelo meio (dezenas de SSIDs disputando espaço entre -50 dBm e -80 dBm). O canal 13 aparece como um platô isolado na borda direita (operando entre 2462 e 2482 MHz, com pico em 2472 MHz), registrando sinal estável de -30 dBm a -36 dBm sem qualquer outra rede sobreposta.
• Latência e estabilidade: No monitor de desempenho em tempo real, a latência do cliente até o gateway local (192.168.100.1) ficou em 8 ms (e 67 ms para a internet em 8.8.8.8), com 0% de perda de pacotes. Fugir da disputa de meio dos canais saturados praticamente zerou as filas de contenção.
• Simetria física em 286 Mbps: O monitor de enlace do aparelho registrou velocidade física simétrica: 286 Mbps de download e 286 Mbps de upload no enlace PHY do Wi-Fi 6 (MIMO 2x2 em 20 MHz).
• Proteção mandatória (MFPR): O smartphone identificou a rede como Wi-Fi 6 (802.11ax) com fabricante Intel Corporate e as flags [RSN-SAE-CCMP-128][ESS][MFPR][MFPC][SAE]. A presença da flag MFPR (Management Frame Protection Required) atesta que o aparelho móvel assumiu o modo estrito de segurança, descartando qualquer pacote não autenticado.

Conclusão: no fim das contas, valeu a pena?

O que começou como uma simples curiosidade prática, querendo saber se dava pra subir um ponto de acesso Wi-Fi 6 no Debian pro celular sem depender de mágicas quebradas de interface gráfica, acabou virando uma expedição arqueológica pelo subsistema de rede do Linux e pelas idiossincrasias do microcódigo da Intel.

Por trás da promessa sedutora do "criar hotspot em um clique", existe um abismo de detalhes. Os adaptadores da Intel foram paridos com a premissa de serem apenas clientes; tentar forçar a placa a virar um roteador 5 GHz autônomo sem entender o que a fabricante fez no silício só resulta em mensagens crípticas de assertiva no dmesg e muita frustração.

Mas jogando pelas regras do jogo e aproveitando a brecha limpa do canal 13 em 2.4 GHz, o resultado compensou: conexão estável como rocha, WPA3 moderno com SAE puro, preâmbulo curto e velocidade real de sobra pros meus aparelhos, tudo orquestrado de forma declarativa e atômica.

Agora, se formos honestos na ponta do lápis (e a nossa fatura de energia elétrica exige essa honestidade): vale a pena manter um computador desktop de 80W ligado direto na tomada só pra servir Wi-Fi pro celular? Por favor, não faça isso. Se você quer apenas internet estável sem inventar moda, compre um roteador Wi-Fi 6 dedicado de duzentos reais que consome 5W e vá viver a sua vida em paz. Mas se o seu objetivo era o prazer sádico de domar o hardware, entender como o rádio do Linux opera por baixo do capô e não deixar a Intel decidir o que você pode ou não rodar na sua própria máquina: aí sim, cada linha de log valeu a pena.

Referências

A tentação em tutoriais de automação é pular direto para a execução dos playbooks. Alguém escreve meia dúzia de tarefas com comandos shell soltos, define caminhos hardcoded nos scripts e torce para que nada mude no futuro. Quem já precisou atualizar a versão do Kubernetes em um ambiente desses sabe o pesadelo que isso representa: você precisa vasculhar cinquenta arquivos procurando por 1.36.2, torcendo para não esquecer um manifesto estático ou uma URL de download escondida em uma role secundária.

No k8s-in-a-box, tomamos uma direção oposta. Toda a inteligência da infraestrutura está desacoplada da execução. O arquivo inventario/group_vars/all.yml funciona como o mapa genético do laboratório, enquanto a estrutura de inventário dita quem é quem na topologia. Para provar o valor dessa separação, fizemos hoje uma atualização real no repositório do projeto: saltamos a versão base do Kubernetes de v1.36.2 para o Kubernetes v1.37.0 ¹, acompanhado do etcd 3.7.1, crictl v1.37.0, helm v3.22.0 e cilium v1.20.2.

Sabe quantos arquivos de automação ou manifestos de pods estáticos precisaram ser reescritos para suportar essa nova versão em todo o cluster? Apenas um.

O arquivo de configuração do Ansible e suas decisões

O ponto de entrada de qualquer automação com a ferramenta é o arquivo de configuração .ansible.cfg. No repositório, ele fica dentro do diretório ansible/ e define exatamente como eu escolhi configurar o Ansible para atender às necessidades desse laboratório:

[defaults]
interpreter_python=auto_silent
deprecation_warnings=False
nocows=True
forks = 5
inventory=../inventario/
host_key_checking=False
become=false
gather_facts=false
log_path=../artefatos/ansible_logs/ansible.log
fact_caching = jsonfile
fact_caching_connection = ../artefatos/ansible_cache/ansible_facts
fact_caching_timeout = 3600
callbacks_enabled = profile_tasks, timer

[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml
cache = yes
cache_connection = ../artefatos/ansible_cache/ansible_inventory

[ssh_connection]
ssh_args=-F ./ssh_config -o ControlMaster=auto -o ControlPersist=180s
control_path_dir = ../artefatos/ansible_cache/cp

Cada uma dessas linhas resolve um problema prático recorrente de automação local.

A diretiva inventory=../inventario/ aponta para um diretório inteiro em vez de um arquivo estático. Isso permite que o Ansible combine o arquivo de máquinas (hosts.yml) com o subdiretório de variáveis de grupo (group_vars/) de maneira orgânica.

A opção host_key_checking=False é uma concessão consciente para o fluxo de desenvolvimento. Como estamos destruindo e recriando máquinas virtuais frequentemente com Vagrant, o hash de chave pública de cada VM mudaria a cada recriação, causando erros de host key mismatch no SSH.

Outro ganho perceptível de fôlego vem da trinca gather_facts=false, forks = 5 e as opções de [ssh_connection]. Por padrão, toda vez que você pisca o olho, o Ansible quer passar um pente fino na VM para descobrir o endereço MAC de cada interface virtual, o tamanho do disco e até a fase da lua no sistema operacional. Para quem está rodando tudo localmente no notebook ou desktop, esperar esse interrogatório a cada play só serve para usar CPU à toa e testar a nossa paciência. Desativei essa coleta global por padrão: quando uma role realmente precisar de algum dado específico da máquina, ela que vá lá e colete pontualmente.

Com o ssh_args configurado com ControlMaster=auto e ControlPersist=180s, o cliente SSH reaproveita os sockets de conexão abertos com as VMs durante três minutos. Tarefas subsequentes na mesma máquina acontecem de forma quase instantânea, sem a latência de um novo handshake criptográfico a cada task.

Anatomia do inventário e topologias com symlinks

O diretório configs/ na raiz do projeto abriga três modelos de cluster distintos: hosts-nano.yml, hosts-mini.yml e hosts-completo.yml. Como discutimos na Parte 1, nem todo desenvolvedor tem uma máquina com recursos de sobra para rodar várias máquinas virtuais e manter um cluster etcd com quórum completo.

Quando executamos make init (ou definimos CLUSTER=mini no arquivo config.mk), o Makefile cria um link simbólico transparente:

inventario/hosts.yml -> ../configs/hosts-mini.yml

Essa abordagem garante que todo o restante do ferramental (Ansible, scripts de verificação e Vagrant) consuma sempre o mesmo caminho (inventario/hosts.yml), sem precisar reescrever parâmetros de linha de comando.

A estrutura de cada nó e o agrupamento inicial seguem este padrão (o arquivo completo com todas as VMs está no configs/hosts-mini.yml):

all:
  children:
    managers:
      hosts:
        manager1:
          ansible_host: 172.24.0.31
          fqdn: manager1.k8sbox.local
          memory: 3072
          cpus: 2

    # Agrupamento composto para orquestração
    cluster:
      children:
        managers: {}
        workers: {}

A composição de grupos simplifica a execução dos playbooks:

1. Grupos específicos: loadbalancers, nfs, managers, workers e clientes (kubox, nosso bastion host).
2. Grupo cluster: une managers e workers para tudo o que é comum aos nós Kubernetes (CRI-O, kubelet, CNI).
3. Grupo suporte: une loadbalancers (HAProxy e Keepalived) e nfs (armazenamento persistente).
4. Grupo todos: encapsula todo o ambiente para a preparação base do sistema operacional.

A simbiose entre Vagrant, Libvirt e o inventário

O inventário não serve apenas para o Ansible rodar tarefas. Ele funciona como a fonte única da verdade de toda a infraestrutura virtual:

• Vagrant alimentado pelo inventário: o Vagrantfile não tem máquinas hardcoded. Ele lê diretamente o inventario/hosts.yml e provisiona cada VM no hipervisor com as variáveis memory e cpus que declaramos lá. Ajustou no YAML, o hardware da VM acompanha.
• Libvirt (KVM) em vez de VirtualBox: KVM roda direto no kernel Linux, sem emulação pesada. Isso economiza RAM e CPU para aguentar várias VMs ligadas no mesmo computador sem fazer o sistema hospedeiro pedir socorro.
• Isolamento de redes com duas placas (Dual-NIC):
  • eth0 (net_vagrant): interface exclusiva para a gerência do Vagrant (vagrant ssh, triggers e provisioners). Configuramos com ipv4.never-default yes e métrica alta (500) justamente para ela nunca disputar rota padrão ou rota de saída.
  • eth1 (net_mgmt, 172.24.0.0/24): a placa de rede principal da VM. É ela que recebe os IPs estáticos do inventário, assume a rota padrão (metric 50) com o gateway 172.24.0.1 (NAT do Libvirt) e trafega tudo: comunicação interna do cluster (etcd, kube-apiserver, CNI, NFS) e saída externa controlada.

Com isso, o lab fica imune à sua rede física: você pode trocar de Wi-Fi, ligar VPN ou tirar o cabo de rede que as VMs continuam se falando sem quebrar o cluster.

O arquivo all.yml como mapa genético da stack

Se a topologia define onde as coisas rodam, o arquivo inventario/group_vars/all.yml define o que roda e em qual versão. No Ansible, variáveis colocadas dentro de group_vars/all.yml tornam-se visíveis automaticamente para todos os hosts do inventário.

Vamos dissecar os principais blocos do all.yml e examinar as decisões por trás de cada um.

Definição de redes e cálculo de IPs derivados

Um cluster Kubernetes possui pelo menos três domínios de rede distintos que nunca devem se sobrepor: a rede física ou dos hosts, a rede interna dos Pods e a rede virtual de Services (ClusterIPs).

Em vez de preencher manualmente endereços IP em dezenas de lugares, definimos as faixas CIDR principais e calculamos os endereços derivados utilizando o plugin ansible.utils.ipaddr:

# Trecho de inventario/group_vars/all.yml
rede_cidr_services: "172.25.128.0/17"
primeiro_ip_services: "{{ rede_cidr_services | ansible.utils.ipaddr('1') | ansible.utils.ipaddr('address') }}"
coredns_ip: "{{ rede_cidr_services | ansible.utils.ipaddr('10') | ansible.utils.ipaddr('address') }}"

O filtro ansible.utils.ipaddr('10') pega o décimo endereço utilizável dentro da sub-rede 172.25.128.0/17, resultando em 172.25.128.10. Esse endereço é repassado tanto para a configuração do service do CoreDNS quanto para o parâmetro --cluster-dns na inicialização de cada kubelet. Se você precisar mudar toda a faixa de Services do cluster para 10.96.0.0/12, altera apenas rede_cidr_services e todos os componentes convergem sem inconsistências.

Alternância de runtimes e plugins de rede

O projeto foi desenhado para permitir experimentação controlada. Queremos poder alternar o runtime de contêiner ou o plugin de rede CNI com uma flag no inventário:

# Trecho de inventario/group_vars/all.yml
container_runtime: "crio"  # crio ou containerd
plugin_cni: "cilium"       # cilium ou canal

A variável container_runtime é consumida pelas roles para definir quais repositórios habilitar, quais pacotes instalar e qual socket registrar na inicialização do kubelet (--container-runtime-endpoint).

Na rede, a variável plugin_cni: "cilium" seleciona a stack padrão moderna com eBPF nativo e suporte a Gateway API. Caso o leitor queira testar a stack tradicional com canal (Flannel + Calico) e kube-vip, basta alterar essa variável para canal.

O caso prático do upgrade para Kubernetes v1.37.0

Aqui chegamos ao coração da atualização que realizamos hoje no repositório. Em vez de espalhar versões em múltiplos manifestos, concentramos a versão base em uma única linha e deixamos o Ansible propagar o valor:

# Trecho de inventario/group_vars/all.yml
versao_kubernetes: "v1.37.0"

# O valor propaga automaticamente para imagens dos Static Pods:
control_plane_images:
  apiserver: "registry.k8s.io/kube-apiserver:{{ versao_kubernetes }}"

# E para os downloads oficiais com checagem de integridade:
download_artefatos:
  kubelet-bin:
    url: "https://dl.k8s.io/release/{{ versao_kubernetes }}/bin/linux/amd64/kubelet"
    arquivo: "kubelet"
    checksum: "sha256:https://dl.k8s.io/release/{{ versao_kubernetes }}/bin/linux/amd64/kubelet.sha256"

Ao alterar a linha versao_kubernetes: "v1.37.0", o Ansible automaticamente:

1. Calcula a nova URL oficial de download do binário do kubelet e seu hash SHA256 correspondente.
2. Faz o download do binário compilado do kubectl v1.37.0.
3. Atualiza os manifestos dos Static Pods em cada manager para apontar para as tags registry.k8s.io/kube-apiserver:v1.37.0, kube-controller-manager:v1.37.0 e kube-scheduler:v1.37.0.
4. Garante que os nós baixem a imagem correspondente do kube-proxy:v1.37.0.

A lista com todas as versões vinculadas da stack (como etcd 3.7.1, crictl v1.37.0, helm v3.22.0 e cilium v1.20.2) está documentada na íntegra no inventario/group_vars/all.yml. A versão do cluster torna-se um parâmetro puramente declarativo.

A tríade de playbooks e o sistema semântico de tags

A execução do Ansible no projeto está dividida em três playbooks complementares, com separação estrita de contexto:

ansible/
├── cluster.yml   # Orquestra infraestrutura base, PKI, nós e control plane
├── ops.yml       # Provisiona o bastion host (kubox), rede CNI e exemplos
└── addons.yml    # Instala aplicações de monitoramento e dashboards

O playbook principal: cluster.yml

O arquivo ansible/cluster.yml orquestra a subida do cluster desde a máquina física até os pods do control plane. Em vez de um script monolítico, ele organiza as etapas por grupos de nós:

# Trecho de ansible/cluster.yml
- name: Tarefas a serem executadas no host
  hosts: localhost
  connection: local
  become: false
  roles:
    - role: infra-artefatos
      tags: [cluster-artefatos, cluster]

- name: Configuração do kubelet
  hosts: cluster
  become: true
  serial: 1
  roles:
    - role: k8s-kubelet
      tags: [cluster-kubelet, cluster]

Note o uso da diretiva serial: 1 na role k8s-kubelet. Quando atualizamos ou configuramos os agentes dos nós, queremos que o Ansible processe uma máquina por vez, minimizando o impacto no cluster em execuções de manutenção.

A sequência completa, incluindo as plays para balanceadores de carga, servidor NFS e os Static Pods do control plane (etcd, apiserver, controller-manager e scheduler), pode ser conferida diretamente em ansible/cluster.yml.

O playbook operacional: ops.yml

O arquivo ansible/ops.yml opera em um plano diferente. Ele não roda contra os nós do cluster, mas sim contra a máquina kubox (grupo clientes), gerenciando a instalação da rede CNI por meio de condições dinâmicas:

# Trecho de ansible/ops.yml
- name: Instalação da Rede CNI e dependências
  hosts: clientes
  become: false
  roles:
    - role: cni-cilium
      when: plugin_cni == 'cilium'
      tags: [ops-cni-cilium, ops-cni, ops]
    - role: cni-canal
      when: plugin_cni == 'canal'
      tags: [ops-cni-canal, ops-cni, ops]

É o ops.yml que aplica os manifestos de CNI no cluster. Em vez de rodar o comando helm install ou kubectl apply na sua máquina de desenvolvimento local (o que exigiria instalar o Helm, o CLI do Cilium e o kubectl no seu próprio Linux), essas ferramentas são instaladas e executadas de dentro da VM kubox. Seu hospedeiro permanece limpo.

O playbook completo com a instalação das ferramentas operacionais (k9s, popeye, tailspin) e deploys de exemplo está em ansible/ops.yml.

O playbook de addons: addons.yml

Por fim, o arquivo ansible/addons.yml isola a implantação de serviços opcionais que não afetam o ciclo de vida do Kubernetes básico:

# Trecho de ansible/addons.yml
- name: Aplicação de addons independentes de CNI no cluster
  hosts: clientes
  become: false
  roles:
    - role: addon-apps-cluster
      tags: [addons]

Ele gerencia painéis e telemetria (Headlamp, Prometheus, Grafana) através da role addon-apps-cluster, permitindo ligar ou desligar essa camada a qualquer momento sem interferir no core do cluster.

Como o Makefile encapsula as tags

Ninguém quer memorizar comandos longos do Ansible com argumentos de configuração e dezenas de tags separadas por vírgula. O Makefile do repositório funciona como uma camada de abstração ergonômica:

# Trecho do Makefile
infra: garante-config
	ANSIBLE_CONFIG="$(CFG)" ansible-playbook "$(PLAYBOOK)" --tags cluster-artefatos,cluster-pki,cluster-sistema,cluster-balanceador,cluster-nfs

control-plane: garante-config
	ANSIBLE_CONFIG="$(CFG)" ansible-playbook "$(PLAYBOOK)" --tags cluster-kubernetes-base,cluster-kubelet,cluster-etcd,cluster-kube-apiserver,cluster-kube-controller-manager,cluster-kube-scheduler

Quando você digita make infra, o Makefile valida se a configuração ativa no config.mk corresponde ao symlink atual, define a variável de ambiente ANSIBLE_CONFIG e dispara exatamente as tags necessárias para preparar o terreno antes do Kubernetes.

Além disso, o Makefile traz utilitários essenciais de confiabilidade:

• Validação prévia de dependências (make check-deps): antes de subir qualquer máquina ou playbook, o script verifica se o processador tem suporte a KVM habilitado, se o seu usuário faz parte do grupo libvirt, e se o Ansible, o Vagrant e o plugin vagrant-libvirt estão presentes. Isso impede falhas frustrantes no meio do provisionamento por falta de permissão ou pacote esquecido.
• Ciclos rápidos de estudo (make cluster-etcd, make cluster-kubelet): durante o desenvolvimento ou depuração de um subsistema específico, essas tags executam apenas as tarefas da role designada. Você testa alterações em segundos sem ter que esperar a execução completa de todo o cluster.
• Limpeza e purga de estado (make clean): além de destruir as VMs no Vagrant, esse comando apaga completamente a pasta artefatos/, garantindo que certificados antigos e caches locais do Ansible (fact_caching e inventário) sejam purgados sem deixar resíduos.

A lista completa de alvos está disponível no Makefile.

Decisões de design no Ansible do projeto

Antes de avançarmos para os comandos práticos, vale a pena abrir o capô e entender por que a estrutura do Ansible neste projeto é organizada dessa maneira. Não se trata de convenção estética: tomamos decisões muito conscientes para garantir que o laboratório seja rápido, reproduzível e seguro.

Construção centralizada de certificados no host

Em muitas instalações manuais, a geração de certificados TLS é uma bagunça espalhada: comandos openssl ou cfssl rodam dentro de cada VM, autoridades certificadoras são copiadas de um lado para o outro e qualquer erro exige caçar chaves perdidas no sistema de arquivos.

No nosso projeto, a role ansible/infra-pki roda inteiramente em localhost. Todos os certificados (Root CA, intermediárias de etcd, kubernetes e front-proxy, além de certificados de nós, clientes e service accounts) são forjados uma única vez na máquina hospedeira e armazenados em artefatos/pki/.

As máquinas virtuais nunca chegam a ver a chave privada da Root CA: elas recebem por cópia SSH estritamente o par exato de chave e certificado que precisam para funcionar. Além disso, controlamos a regeração com a variável pki_regerar_certs: false. Se você destruir e recriar as VMs, não precisa regerar toda a infraestrutura criptográfica do zero.

Downloads atômicos e reaproveitamento de binários

A role ansible/infra-artefatos segue o mesmo princípio de eficiência. Em vez de várias máquinas virtuais baixarem os binários do kubelet, kubectl e plugins CNI simultaneamente da internet (disputando banda e correndo risco de throttling ou timeout), o Ansible baixa cada pacote uma única vez na máquina física, confere o hash SHA256 e guarda em artefatos/bin/. A partir dali, os binários são distribuídos localmente via SSH em segundos.

Cache local de imagens OCI com Skopeo e importação direta

O mesmo raciocínio dos binários aplica-se às pesadas imagens de contêiner da infraestrutura (pause, etcd, kube-apiserver, etc.). Baixar essas imagens repetidamente a cada nova criação de cluster desperdiça banda e tempo.

A role k8s-kubelet (tasks/07-download-imagens-sistema.yml) implementa um mecanismo de cache local no host:

1. Detecção: o Ansible verifica se os tarballs das imagens necessárias já existem na pasta imagens/ no host físico.
2. Download centralizado: se ausente, o primeiro nó manager (manager1) faz o download da imagem via skopeo copy direto do registro de contêineres para um tarball local e o transfere de volta para o host de desenvolvimento via ansible.builtin.fetch.
3. Distribuição e carga direta no runtime: para cada nó do cluster, o Ansible copia o tarball do host para a VM e o importa diretamente na camada de armazenamento do runtime configurado:
   • No CRI-O: a importação ocorre via skopeo copy diretamente para o containers-storage.
   • No Containerd: a importação ocorre via ctr -n k8s.io images import.

Esse fluxo viabiliza um ambiente "offline-ready": após o primeiro provisionamento, você pode destruir todas as VMs e recriar o laboratório completo sem depender de conexão externa com registries.

Extração dinâmica de ferramentas via OverlayFS

Outra solução prática do projeto está na forma como instalamos o utilitário etcdctl no bastion kubox. No passado, baixávamos da internet o arquivo compactado completo de lançamento do etcd (um tarball pesado para extrair um único binário).

Adiciona complexidade fazer isso direto do contêiner? Sim, admito que foi uma escolha arquitetural deliberada da minha parte: é um download pesado a menos da internet e uma garantia de paridade exata de versão entre o binário administrativo e o etcd que está rodando no cluster.

Aproveitamos o fato de que a imagem oficial do etcd já está rodando no cluster como Static Pod no manager1. O Ansible inspeciona o contêiner ativo com crictl inspect, localiza o caminho exato da camada mesclada no OverlayFS (merged layer) no disco do nó e copia o executável /usr/local/bin/etcdctl diretamente dessa montagem do Linux para o bastion. É economia de banda, eliminação de dependência externa e uso inteligente da infraestrutura que já está no ar.

Padronização semântica de roles e tasklists

No passado do projeto, as roles usavam prefixos numéricos herdados (00-artefatos, 01-pki, 02-sistema, etc.). Conforme o cluster cresceu e incorporou novos CNIs e opções de runtime, essa numeração rígida virou uma armadilha de manutenção: para inserir um componente intermediário, era preciso renomear pastas inteiras.

Fizemos uma transição para uma taxonomia puramente semântica:

1. infra-*: roles de fundação que preparam o terreno antes do Kubernetes existir (artefatos, PKI, balanceadores HAProxy e Keepalived, NFS e sistema operacional base).
2. k8s-*: componentes centrais do Kubernetes (nós base, agente kubelet e os manifests dos pods estáticos do control plane).
3. ops-*: ferramental administrativo e automações executadas a partir do bastion host kubox.
4. cni-* e addon-*: redes de sobreposição intercambiáveis e serviços auxiliares de valor agregado.

Cada role possui tasklists enxutas e focadas em uma única responsabilidade. As tarefas são agrupadas logicamente (instalação de pacotes, renderização de templates Jinja2 e ativação de serviços systemd), permitindo que qualquer pessoa leia a pasta tasks/ de uma role e entenda exatamente o que está acontecendo sem adivinhações.

Diagnóstico e validação rápida

Para validar se o seu inventário e suas variáveis estão configurados corretamente antes de rodar qualquer playbook, o Ansible oferece comandos de introspecção nativos.

Inspecionando a árvore de grupos

Para verificar como o Ansible enxerga a hierarquia de nós do cluster, execute a partir do diretório raiz:

$ ansible-inventory -i inventario/hosts.yml --graph

Esse comando renderiza a árvore completa de relações entre todos os grupos e nós. O ponto principal de atenção nessa inspeção é validar se os agrupamentos compostos (como @cluster unindo managers e workers, ou @suporte unindo balanceadores e NFS) estão aninhados corretamente. Se alguma máquina aparecer solta dentro de @ungrouped ou um grupo intermediário não for listado, significa que há um erro de indentação no seu arquivo hosts-*.yml.

Verificando variáveis resolvidas por nó

Para confirmar quais variáveis e valores chegam a uma máquina específica, use a flag --host:

$ ansible-inventory -i inventario/hosts.yml --host manager1 | grep -E 'versao_kubernetes|plugin_cni|memory'

A saída confirma a consolidação das variáveis de host com as variáveis de grupo:

    "memory": 3072,
    "plugin_cni": "cilium",
    "versao_kubernetes": "v1.37.0",

Testando variáveis ativas com o módulo debug

Caso você queira inspecionar o valor de uma variável em todos os nós simultaneamente sem rodar nenhum playbook longo, o módulo debug em modo ad-hoc é a ferramenta ideal. Lembre-se apenas de que essa checagem ad-hoc exige que as máquinas virtuais estejam ligadas e acessíveis na rede privada (make cluster-up):

$ ANSIBLE_CONFIG=./ansible/.ansible.cfg ansible -m debug -a "var=versao_kubernetes" cluster

Saída esperada:

manager1 | SUCCESS => {
    "versao_kubernetes": "v1.37.0"
}
worker1 | SUCCESS => {
    "versao_kubernetes": "v1.37.0"
}
worker2 | SUCCESS => {
    "versao_kubernetes": "v1.37.0"
}

Conclusão

Compreender o inventário e a estrutura de variáveis é a diferença entre operar automação como quem copia comandos cegamente e operar com controle total da arquitetura. No k8s-in-a-box, cada arquivo tem um propósito bem delimitado: o hosts-*.yml dimensiona e posiciona as peças, o all.yml dita as regras e versões da stack, e a tríade de playbooks executa as tarefas na ordem estrita de dependências.

Com o inventário compreendido e o nosso cluster configurado com o Kubernetes v1.37.0, estamos prontos para a próxima etapa: no próximo post (Parte 4: Preparação do Sistema Base), vamos entrar dentro das VMs e aplicar a role infra-sistema, configurando pacotes essenciais, módulos de kernel (br_netfilter, overlay), parâmetros de sysctl, desativação de swap e a política de SELinux para receber os binários do Kubernetes.

Referências

Numa conversa sobre Docker e Kubernetes, num desses papos técnicos que não tem hora pra acabar, ele fez uma observação que ficou martelando na minha cabeça. Disse que entendia a utilidade das ferramentas, mas que sentia que estava aprendendo conceitos novos. Que o mundo dos contêineres parecia um universo próprio, com vocabulário e princípios específicos que ele ainda estava assimilando.

Fiquei olhando pra ele por um segundo.

Eu mesmo não vim do nada. Passei por Mandrake, Conectiva e Kurumin nos anos das instalações que levavam três horas e uma reza. Depois Slackware, Gentoo, Arch. Fiz RHEL em ambiente corporativo. Hoje uso Debian. No meio do caminho, fui fundo o suficiente para montar um sistema do zero com o LFS e o BLFS, inclusive em contextos de sistemas embarcados, só para entender o que estava acontecendo debaixo do capô. chroot? Eu conhecia. Usava com menos frequência que meu amigo, que compila os próprios pacotes no Slackware dele até hoje, mas conhecia.

Ele estava começando a se aventurar pelo mundo dos contêineres agora. Experiências simples por aqui e por ali, e aquela conversa era parte do processo de entrar de cabeça no assunto. Eu já tinha um bom caminho percorrido nesse terreno: Docker, Compose, Kubernetes, o ecossistema todo.

A dúvida que ele trouxe era essa: com um hipervisor, um sistema operacional convidado e um contêiner rodando no topo, não seriam três camadas de indireção empilhadas? Não seria isso mais pesado do que simplesmente usar uma VM diretamente?

É exatamente o tipo de pergunta que faz sentido vir de quem pensa em termos de hardware real, latência e overhead. Não é ingenuidade. É um engenheiro de infraestrutura levantando uma objeção legítima com base no modelo mental que a indústria construiu em torno dos contêineres: o de que eles são VMs mais leves. Esse modelo é errado. E é esse erro que explica tudo.

A conversa que se seguiu foi a inspiração direta para essa série. Porque o que ficou evidente ali é que o problema não é falta de conhecimento técnico. É a narrativa da indústria que faz parecer que Docker caiu do céu em 2013 e inventou o isolamento de processos. Não inventou. Continuou uma história que começa muito antes.

O que o Docker realmente fez

Solomon Hykes não inventou o isolamento de processos. Não inventou namespaces, não inventou cgroups, não inventou sistemas de arquivos em camadas.

O que ele fez foi pegar uma série de tecnologias que existiam espalhadas no ecossistema Linux, que qualquer administrador de sistemas experiente conhecia individualmente mas que eram trabalhosas de configurar juntas, e empacotou tudo isso numa experiência de usuário tão fluida que mudou a maneira como a indústria pensa sobre entrega de software. É a diferença entre saber que existe motor a combustão, suspensão e sistema de freios e ter um carro na garagem pronto pra usar.

A história dos contêineres é, nesse sentido, uma história de convergência. Tecnologias desenvolvidas em contextos diferentes, por equipes sem coordenação direta, ao longo de décadas, que foram gradualmente se encontrando até o momento em que alguém teve o discernimento de perceber que elas podiam andar juntas.

1979: A Primeira Jaula

Tudo começa em 1979, durante o desenvolvimento da versão 7 do Unix. Bill Joy e outros pioneiros adicionaram ao sistema a chamada de sistema chroot ¹. A ideia era simples: alterar o diretório raiz aparente para um processo e todos os seus filhos. Se você rodasse um programa sob chroot /jail, para aquele programa a barra (/) passava a ser a pasta /jail.

O caso de uso original era pragmático. Compilar pacotes de software em um ambiente limpo sem riscos de afetar o sistema principal. Testar instalações sem estragar a máquina. A lógica faz sentido até hoje.

O problema é que o chroot isolava apenas o sistema de arquivos. A aplicação enjaulada ainda enxergava todos os processos do sistema operacional, abria conexões de rede sem restrição e consumia memória livremente até derrubar a máquina. E escapar de uma jaula chroot sendo root sempre foi, no Linux, um truque de entrada de manual: um passo, três linhas, pronto.

A primeira jaula existia. Mas as paredes tinham buracos por todos os lados.

2000: A Primeira Prisão de Verdade

A solução veio de fora do Linux, no ano 2000, quando o sistema FreeBSD introduziu as FreeBSD Jails ², desenvolvidas por Poul-Henning Kamp. Meu amigo do Slackware, se estiver lendo isso, está provavelmente assentindo nesse ponto.

As Jails foram a primeira tecnologia real de virtualização em nível de sistema operacional. Elas isolavam não só o sistema de arquivos, mas a árvore de processos completa, o endereço IP e os privilégios administrativos. Cada jail tinha seu próprio hostname, sua própria tabela de processos e seu próprio usuário root restrito ao escopo daquela jaula. O root da jail não era o root da máquina.

Isso era filosoficamente diferente do chroot. Não era uma pasta com paredes. Era um compartimento com porta, teto e vigilância.

O modelo influenciou o restante do ecossistema Unix. Se você usa *BSD por escolha técnica, sabe exatamente por quê essa abordagem é elegante: é isolamento sem hipervisor, sem emulação, sem overhead. É o sistema operacional fazendo o que deveria fazer desde o começo.

2001-2004: O Linux Tenta Acompanhar

O universo Linux não ficou parado. Em 2001 nasceu o projeto Linux-VServer, seguido pelo OpenVZ em 2005. Ambos entregavam virtualização leve com desempenho excelente, mas carregavam um defeito de origem que limitou sua adoção: exigiam patches pesados aplicados diretamente no código-fonte do kernel.

Como esses patches nunca foram aceitos na árvore oficial mantida por Linus Torvalds, usar contêineres em Linux exigia rodar kernels customizados mantidos por terceiros. Para uma equipe corporativa que precisa de suporte, atualização de segurança e previsibilidade, isso era um pesadelo logístico.

Em 2004, a Sun Microsystems deu um passo diferente com o Solaris 10 e as Solaris Zones ³. As Zones combinaram isolamento de processos com o inovador sistema de arquivos ZFS, permitindo criar clones e snapshots instantâneos de sistemas inteiros com custo ínfimo de disco. Foi a demonstração de que isolamento e gerenciamento de artefatos podiam andar juntos com elegância.

O Linux precisava de uma resposta que não exigisse patches externos. E ela viria de um lugar inesperado.

2006: O Google Resolve Seu Próprio Problema

Por volta de 2006, os engenheiros do Google enfrentavam um problema de escala que poucos outros times no mundo podiam compreender. Dezenas de milhares de servidores rodando a busca, o Gmail e outros serviços, todos competindo por recursos de CPU e memória sem nenhum mecanismo formal de governança. Um processo mal comportado podia afetar serviços vizinhos. A telemetria era imprecisa. A previsibilidade era uma ilusão bem disfarçada.

Paul Menage e Rohit Seth criaram uma solução interna chamada inicialmente de Process Containers ⁴. O nome era descritivo: um mecanismo para agrupar processos e aplicar limites rígidos de recursos sobre esse grupo. CPU, memória, operações de disco. Limites que o kernel respeitaria independentemente do que o processo tentasse fazer.

Para evitar confusão com o termo "contêineres" que estava surgindo em outros contextos, a tecnologia foi renomeada para cgroups (control groups). Em 2008, foi aceita na árvore principal do kernel Linux 2.6.24.

Diferente do Linux-VServer e do OpenVZ, os cgroups entraram no kernel oficial. Qualquer distribuição Linux que rodasse um kernel moderno tinha acesso a essa tecnologia sem patches, sem customização, sem dependência de repositórios externos.

A fundação estava pronta.

2008: LXC e o Problema da Ergonomia

Com os cgroups no kernel e os namespaces sendo gradualmente maturados, o LXC (Linux Containers) surgiu em 2008 combinando essas primitivas em um conjunto de utilitários de linha de comando. Era possível subir contêineres completos sem modificar o kernel, sem aplicar patches, sem depender de projetos externos.

O problema era que fazer isso funcionava, mas não era divertido. Configurar redes virtuais, pontos de montagem, permissões e limites de recursos no LXC exigia conhecimento profundo de administração de sistemas e uma dose generosa de paciência. Não era uma ferramenta que você recomendaria para um desenvolvedor que queria rodar sua aplicação localmente.

Era a tecnologia certa, mas ainda faltava a interface certa.

2013: Cinco Minutos que Mudaram a Indústria

Em março de 2013, uma pequena empresa de plataforma como serviço chamada dotCloud decidiu abrir o código de uma ferramenta interna. Solomon Hykes subiu ao palco da PyCon ⁵ para uma palestra relâmpago. Cinco minutos. Sem slides elaborados. Sem demo preparada com horas de ensaio.

A sala não era grande. O público não estava esperando uma revolução. Hykes mostrou como baixar uma imagem, rodar um processo isolado, destruir o contêiner e começar de novo. Tudo em segundos, com um único comando por vez.

A plateia entendeu imediatamente o que estava vendo. Não era magia. Era LXC com uma interface que qualquer pessoa conseguia usar, um formato de imagem baseado em camadas reutilizáveis e um repositório centralizado para compartilhamento. Mas a combinação dessas três coisas, apresentada com aquela fluência operacional, mudou o ponto de equilíbrio do mercado em tempo real.

O Docker não foi a tecnologia mais sofisticada. Foi a que chegou no momento certo, com a embalagem certa, para um mercado que já estava pronto para adotar contêineres mas não sabia como começar.

2015: A Indústria Faz as Pazes

O sucesso do Docker gerou um problema novo. Toda a cadeia de ferramentas de entrega de software começou a depender de um formato proprietário controlado por uma única empresa. Kubernetes, as grandes nuvens públicas, as ferramentas de CI/CD: tudo falava Docker.

Para evitar esse aprisionamento tecnológico, em 2015 as grandes empresas do ecossistema se uniram sob a Linux Foundation e criaram a Open Container Initiative (OCI) ⁶. Docker, Red Hat, Google, IBM, Microsoft. O objetivo era padronizar tanto o formato de imagem quanto o mecanismo de execução de contêineres em especificações abertas e neutras.

O Docker doou seu motor de execução central (libcontainer), que foi reescrito como a ferramenta independente runc. A especificação de imagem OCI garantiu que qualquer ferramenta que seguisse o padrão pudesse criar e consumir imagens compatíveis com qualquer outra.

A guerra de formatos que poderia ter fragmentado o ecossistema foi evitada antes de começar.

2017 em diante: O Ecossistema Adulto

Nos anos seguintes, a padronização abriu espaço para uma diversidade saudável de implementações. O projeto containerd foi doado para a Cloud Native Computing Foundation (CNCF) e virou o runtime de referência. A Red Hat desenvolveu o Podman e o CRI-O para ambientes corporativos e Kubernetes, resolvendo preocupações reais de segurança com o modelo de daemon centralizado do Docker.

Implementações alternativas de runtime de baixo nível surgiram com objetivos específicos: o crun em C puro, mais rápido e com menor pegada de memória; o youki em Rust, com garantias de segurança de memória; o gVisor da Google, interceptando chamadas de sistema em espaço de usuário para isolamento extremo. O Kata Containers integrou micro-máquinas virtuais para os casos onde o compartilhamento de kernel era inaceitável.

1979        2000        2004        2006-2008        2008        2013        2015        2017+
 │           │           │              │             │           │           │           │
 ▼           ▼           ▼              ▼             ▼           ▼           ▼           ▼
chroot    FreeBSD     Solaris        cgroups         LXC       Docker        OCI      containerd
(Unix)     Jails       Zones       (Google no      (Kernel    (dotCloud/   (Padrão     Podman
             │       (com ZFS)     mainline)       nativo)      Hykes)     aberto)     CRI-O
             │                                                   │
        Linux-VServer                                       libcontainer
           (2001)                                             -> runc

O que a história diz sobre como a indústria funciona

Existe um padrão aqui.

As tecnologias fundamentais raramente surgem prontas. Elas emergem em contextos distintos, resolvendo problemas específicos de suas épocas, e passam anos existindo em paralelo sem se encontrar. O chroot era uma ferramenta de build. As Jails eram uma resposta de segurança do ecossistema *BSD. Os cgroups nasceram de uma necessidade operacional do Google. Os union filesystems existiam para gerenciamento de sistemas de arquivos em live CDs.

O Docker não inventou nenhuma dessas coisas. O Docker percebeu que elas podiam funcionar juntas.

Meu amigo do Slackware conhecia chroot, conhecia jails, tinha até experimentado LXC em algum momento. O que ele não havia conectado era que o Docker era, essencialmente, uma interface para os mesmos conceitos que ele já dominava. A terminologia mudou. A experiência de uso ficou polida. A abstração ganhou uma camada de marketing pesada. Mas o kernel debaixo continuava fazendo o mesmo trabalho que sempre fez.

É uma lição que vale além do universo dos contêineres. A inovação real raramente é ex nihilo. Quase sempre é síntese, integração, timing.

E às vezes é uma palestra de cinco minutos na hora certa.

Conclusão

Na Parte 1 da série, vamos descer ao nível do kernel Linux para entender exatamente o que acontece quando você digita docker run: namespaces, cgroups v2, OverlayFS e a especificação OCI. Se você é o tipo de pessoa que prefere entender o mecanismo antes de usar a ferramenta, é pra lá que você vai querer ir.

Referências

Só que a sensação constante era a de morar de aluguel em uma casa mobiliada por outra pessoa. Você não pode pintar uma parede sem o reboco inteiro desabar sobre a sua cabeça.

A gota d'água não foi uma falha técnica repentina. Foi o acúmulo silencioso do tempo.

Conforme o blog foi crescendo, acumulando dezenas de artigos analíticos, tutoriais de infraestrutura, trilhas de Kubernetes e reflexões sobre engenharia, o contraste entre o conteúdo e o continente foi ficando incômodo. Eu passava horas polindo argumentos, formatando blocos de código e desenhando diagramas em ASCII, para no final ver tudo espremido em uma tipografia genérica de sistema, com espaçamentos desajeitados e uma paleta sem vida.

O invólucro não fazia justiça ao que estava dentro.

Tomei coragem, abri o terminal e decretei a reforma geral. Foram dias de faxina pesada: arranquei o tema Minima pela raiz, expurguei camadas acumuladas de CSS utilitário, adotei o Pico CSS v2 como fundação semântica, criei uma paleta própria com modos claro e escuro calibrados, trouxe fontes e scripts para dentro do repositório em modo 100% offline-first e validei cada link com o implacável HTMLProofer.

Se acomode na cadeira e pegue um café. A jornada teve tropeços divertidos, algumas teimosias e muita escovação de bytes.

O inventário do caos: a herança maldita do Minima e do Open Props

O ponto de partida de qualquer reforma honesta é olhar a bagunça de frente. Sem filtro e sem vergonha.

O ecossistema do Jekyll tem uma comodidade perigosa chamada theme-gem. Quando você declara theme: minima no seu arquivo _config.yml, o Jekyll não coloca nenhum arquivo de estilo dentro da sua pasta de trabalho. Ele busca os templates e os parciais de SCSS compilados dentro da instalação global da gem do Ruby, em um diretório oculto do sistema operacional.

A princípio, isso soa como mágica pura:

meu-blog/
├── _config.yml
├── _posts/
└── index.md

A ilusão da simplicidade: o repositório parece limpo porque toda a complexidade está oculta na gem.

O problema começa quando você decide customizar qualquer detalhe mínimo da interface.

Quer mudar a largura da coluna principal de leitura? Você precisa criar uma pasta _sass/, descobrir qual era o nome exato da variável que o tema original usava e torcer para que o seu arquivo seja importado na ordem correta. Quer alterar o comportamento do cabeçalho da página? Precisa copiar o template header.html original da gem para dentro de _includes/ e começar a fazer alterações cirúrgicas no código alheio.

Em pouco tempo, o repositório vira uma colcha de retalhos de arquivos sobrepostos.

Em uma tentativa anterior de modernizar a aparência do site sem ter o trabalho de reconstruir tudo do zero, cometi o clássico erro de empilhar soluções. Resolvi enxertar o Open Props, uma biblioteca moderna de variáveis CSS e tokens de design.

A intenção era nobre. O resultado prático foi uma guerra civil de especificidade.

No DevTools do navegador, inspecionar um simples título de postagem se transformou em uma sessão de arqueologia digital. Eram três camadas distintas de estilos disputando a prioridade de cada seletor: as regras padrão do Minima brigando com as variáveis do Open Props, que por sua vez eram atropeladas por declarações com !important que eu mesmo havia escrito na pressa meses antes para consertar alinhamentos tortos.

/* O cemitério de especificidade herdada que acumulamos */
.site-header .wrapper .site-title {
  color: var(--gray-9) !important;
  font-family: var(--font-sans);
  letter-spacing: -0.05em;
}

Guerra de especificidade no inspetor: seletores profundos brigando por atenção.

A manutenção virou um pesadelo constante. Mudar o tamanho de uma fonte no rodapé fazia o cabeçalho quebrar em telas de celular; ajustar a cor de um link na Home estragava o contraste das tags nos artigos.

A casa não era minha. Eu me sentia como um inquilino assustado com medo de ligar o chuveiro e queimar a fiação inteira do prédio.

Chega.

Fui até o Gemfile e deletei a linha gem "minima". Em seguida, passei a vassoura na pasta de estilos antigos e limpei os arquivos temporários com bundle exec jekyll clean.

Assumi a posse definitiva de cada linha de código que seria servida aos leitores deste blog: zero dependências ocultas e zero mágicas de bastidor.

A revelação semântica: por que o Pico CSS v2?

Quando você decide jogar fora um tema pronto, a primeira encruzilhada que aparece no caminho é a escolha do novo motor de CSS. Em pleno 2026, as opções disponíveis no mercado parecem caminhar para extremos opostos: de um lado, os gigantes utilitários corporativos liderados pelo Tailwind CSS; do outro, bibliotecas pesadas de componentes como Bootstrap e Bulma, carregando dezenas de estilos que fazem qualquer site parecer um painel administrativo de telecomunicações dos anos 2010.

Considerei o Tailwind por cerca de cinco minutos. Descartei logo em seguida.

Não me entenda mal: o Tailwind é uma ferramenta fantástica para construir aplicações web dinâmicas e reativas com React, Vue ou Svelte. Mas em um blog estático de artigos longos, centrado puramente em texto, a abordagem utilitária é um contra-senso desastroso.

O fluxo de escrita em um blog é abrir o editor de texto, criar um arquivo Markdown e redigir a postagem usando a sintaxe clássica e limpa do formato:

## Título da Seção

Este é um parágrafo normal de texto com um [link](https://exemplo.com).

> Uma citação relevante de algum autor histórico.

O processador do Jekyll (o Kramdown) converte esse arquivo diretamente para tags HTML5 puras: <h2>, <p>, <a> e <blockquote>, sem injetar classes utilitárias no meio do caminho. Para usar Tailwind nesse cenário, você seria obrigado a instalar o plugin @tailwindcss/typography, aceitar o conjunto opinativo de classes .prose, configurar um pipeline pesado de compilação em Node.js com PostCSS e vigiar constantemente o tamanho da saída gerada.

Eu não queria mais esteiras complexas de frontend para rodar um blog de texto. Eu queria simplicidade objetiva.

Foi nesse momento que o Pico CSS v2 ¹ entrou em cena como a resposta que eu procurava.

O Pico pertence aos chamados frameworks CSS semânticos (ou classless). A proposta central dele é de uma elegância desconcertante: em vez de exigir que você decore centenas de classes utilitárias proprietárias para aplicar no seu HTML, o Pico estiliza diretamente os elementos semânticos nativos do próprio HTML5.

Olhe a comparação estrutural entre os dois paradigmas:

┌─────────────────────────────────────────────────────────────┐
│                    O PARADIGMA UTILITÁRIO                   │
│                                                             │
│   Markdown  ──>  Kramdown  ──>  HTML Cru  ──>  ???          │
│                                                 │           │
│   (Exige plugins, wrappers e injeção de classes utilitárias │
│    como: class="text-xl font-bold mb-4 text-slate-800")     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    O PARADIGMA SEMÂNTICO                    │
│                                                             │
│   Markdown  ──>  Kramdown  ──>  HTML5 Nativo  ──>  Navegador│
│                                       │                     │
│                <article>, <header>, <h2>, <blockquote>      │
│                                       │                     │
│             Pico CSS v2 aplica tipografia, contraste        │
│             e ritmo vertical diretamente nas tags!          │
└─────────────────────────────────────────────────────────────┘

Diferença conceitual: a elegância da renderização semântica direta sem intermediários.

Se você escreve uma tabela em Markdown, o Kramdown cospe a tag <table>, e o Pico CSS intercepta essa tag nativa aplicando instantaneamente bordas sutis, tipografia alinhada, espaçamento interno proporcional e rolagem horizontal em telas estreitas, sem exigir uma única classe auxiliar. A mesma dinâmica acontece com caixas retráteis de <details>, formulários, cabeçalhos e citações.

O Markdown continua puro, o HTML gerado permanece limpo e o navegador recebe exatamente o que precisa.

Além disso, a versão 2 do Pico CSS foi reescrita inteiramente em SCSS modular, trazendo duas vantagens fundamentais que selaram a minha decisão: todas as escolhas estéticas são expostas por variáveis nativas de CSS com o prefixo --pico-*, e a alternância entre temas claro e escuro é controlada diretamente pelo atributo data-theme na tag raiz <html>.

O casamento foi perfeito. Conquistamos um design system limpo, responsivo e adaptável, com uma folha de estilos que pesa menos de 15 KB compactada e que respeita rigorosamente a semântica da web.

A alquimia das cores: construindo a paleta própria (Classic vs Dark)

Com a fundação semântica estabelecida, chegou o momento mais saboroso e arriscado de todo o projeto: escolher as cores do blog. Eu tinha um objetivo muito claro e intransigente em mente: fugir a todo custo dos dois erros capitais que dominam a maioria dos temas modernos na internet.

O primeiro erro é o Dark Mode amador, com fundo preto absoluto (#000000) e tipografia em branco puro (#ffffff). Esse contraste artificial extremo de 21:1 agride os olhos do leitor, causa fadiga visual rápida em ambientes escuros e deixa aquele efeito fantasma incômodo de pós-imagem na retina quando você desvia o olhar da tela.

O segundo erro é o Light Mode hospitalar: aquele fundo branco puro reflexivo que transforma a tela de um monitor grande de 27 polegadas em uma lâmpada fluorescente ligada a meio metro do seu rosto. Em ambos os casos, a leitura prolongada se torna um exercício de resistência física.

A inspiração para o visual não veio de nenhum tratado acadêmico de teoria das cores. Veio de um hábito muito simples e antigo meu: eu sempre adorei rabiscar e rascunhar ideias no papel com cores fortes e marcantes, do tipo que você encontra nas dezenas de canetas Stabilo ponta fina que acumulei pela mesa ao longo dos anos. Aquele contraste vivo de tinta pigmentada sobre folha de caderno pautado sempre me deu prazer na hora de pensar.

No mundo digital, as minhas referências de conforto visual sempre foram o Monokai Pro ² e o Solarized ³. Eu queria trazer essa mesma sensação para o blog: fundos que não agridem a vista, superfícies foscas e acentos de destaque que saltam aos olhos como marca-texto bem passado, sem transformar a página em um carnaval de neon.

Ajustei os valores hexadecimais no arquivo _sass/base/_variables.scss buscando equilíbrio prático.

Para os destaques primários (links e botões), definimos um ciano fechado (#007a8a) no tema claro para dar contraste firme sobre o fundo claro, e um ciano elétrico (#78dce8) no tema escuro. O restante dos acentos vibrantes segue a lógica das canetas coloridas: vermelho (#d62850 / #ff6188) para callouts de perigo e erros críticos, amarelo (#9c6f00 / #ffd866) para avisos e pontos de atenção, e verde (#46851b / #a9dc76) para confirmações e dicas práticas.

A tabela abaixo resume os pilares dessa arquitetura de cores em ambos os modos:

Para sustentar esses acentos coloridos, a fundação neutra cuida do conforto óptico contínuo durante a leitura longa.

No Tema Escuro (dark), a base usa um fundo escuro suave em #2d2a2e que não tenta fazer uma cirurgia de catarata nos olhos do leitor, com cards e painéis em #363337 e blocos de código em #221f22. O texto principal fica em #fcfcfa, enquanto bordas e textos secundários usam cinzas neutros para não poluir a leitura.

No Tema Claro (light), fomos no clássico limpo: fundo branco #ffffff, cartões em #f8f9fa e código em #f1f3f5. O texto principal usa o grafite #212529, garantindo leitura nítida e sem reflexos chatos de luz.

Essas variáveis alimentam os seletores nativos do Pico CSS diretamente no SCSS, unificando links, botões e âncoras sob a mesma identidade.

/* Mapeamento semântico no _sass/base/_variables.scss */
:root:not([data-theme="dark"]),
[data-theme="light"] {
  color-scheme: light;
  --pico-background-color: #{$theme-light-bg};
  --pico-color: #{$theme-light-fg};
  --pico-card-background-color: #{$theme-light-panel};
  --pico-code-background-color: #{$theme-light-code};
  --pico-primary: #{$theme-light-cyan};
}

[data-theme="dark"] {
  color-scheme: dark;
  --pico-background-color: #{$theme-dark-bg};
  --pico-color: #{$theme-dark-fg};
  --pico-card-background-color: #{$theme-dark-panel};
  --pico-code-background-color: #{$theme-dark-code};
  --pico-primary: #{$theme-cyan};
}

Vinculação elegante: o SCSS alimenta as variáveis CSS nativas que o Pico consome.

Com a paleta pronta, restava resolver um detalhe técnico clássico: alternar entre os temas sem causar o temido FOUC (Flash of Unstyled Content).

Sabe quando você entra em um site à noite com o modo escuro ativado no sistema operacional, mas durante meio segundo a página dá aquele clarão branco cegante antes de carregar o estilo correto? Isso acontece quando o script de chaveamento é posicionado no final do arquivo HTML ou dentro de um evento assíncrono DOMContentLoaded.

A nossa solução foi um script síncrono enxuto de vinte linhas, posicionado diretamente dentro da tag <head> no template _includes/head.html:

<script>
  (function() {
    var stored = localStorage.getItem('theme');
    var theme = stored || (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
    document.documentElement.setAttribute('data-theme', theme);
  })();
</script>

Script síncrono anti-clarão: executa antes mesmo do primeiro pixel ser desenhado na tela.

O navegador interpreta esse bloco antes de começar a desenhar o corpo da página. Se o leitor já escolheu um tema anteriormente clicando no botão do cabeçalho, a preferência gravada no localStorage é respeitada de imediato; se for a primeira visita, o script consulta a preferência do sistema via prefers-color-scheme.

O resultado é uma transição suave: zero piscadas na tela e zero surpresas desagradáveis no meio da noite.

A faxina dos ativos: a paranóia saudável do 100% offline-first

Se tem uma coisa que me incomoda profundamente na web contemporânea é a dependência cega de CDNs externas para carregar qualquer elemento básico. Você inspeciona um blog simples e encontra chamadas para servidores do Google Fonts, links para scripts do Cloudflare, folhas de estilo puxadas do unpkg e ícones baixados do jsDelivr.

Parece prático no primeiro dia de desenvolvimento, mas na vida real representa uma dívida técnica e ética pesada.

Existem três razões muito sólidas para você exterminar chamadas externas do seu site: privacidade, resiliência e autonomia. Cada vez que o navegador de um leitor faz uma requisição para carregar uma fonte nos servidores de uma Big Tech, ele envia no pacote o endereço IP, detalhes do dispositivo e a página exata que está sendo lida. Além disso, se a CDN sofrer instabilidade ou bloqueio de rotas, o seu site inteiro congela esperando o timeout da conexão.

Por fim, eu adoro escrever e revisar textos enquanto estou viajando de avião ou em locais remotos. Um blog que depende da internet para carregar o próprio visual localmente é um produto quebrado por concepção.

Comecei a faxina pelas fontes tipográficas, eliminando as chamadas remotas do Google Fonts e baixando diretamente da fundição de código aberto da Adobe as famílias Source Serif 4 (para o corpo do texto) e Source Code Pro (para código e terminais). Ao descompactar os pacotes originais, me deparei com a clássica floresta de formatos legados da web: dezenas de arquivos com extensões .ttf, .otf, .eot e .woff.

Perguntei a mim mesmo se precisávamos de todo esse entulho histórico. A resposta foi um sonoro não.

O formato .woff2 (Web Open Font Format 2.0) utiliza o algoritmo de compressão Brotli nativo e é suportado por praticamente 100% dos navegadores modernos em circulação no mundo há muitos anos. Apaguei todos os formatos antigos da pasta de fontes e deixei exclusivamente os arquivos .woff2 leves, mantendo as declarações limpas em _sass/base/_typography.scss:

/* Declaração enxuta em _sass/base/_typography.scss */
@font-face {
  font-family: 'Source Serif 4';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('/assets/fonts/source-serif-4-regular.woff2') format('woff2');
}

@font-face {
  font-family: 'Source Code Pro';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('/assets/fonts/source-code-pro-regular.woff2') format('woff2');
}

Fontes 100% locais: carregamento ultra-rápido sem depender de servidores alheios.

A mesma postura rigorosa foi aplicada aos ícones do FontAwesome: nada de carregar folhas de estilo mastodônticas de meio megabyte com milhares de ícones que o blog jamais usaria. Isolamos apenas os vetores e classes essenciais para as redes sociais e marcadores em assets/fonts/ e _sass/.

Hoje, se você desligar o cabo de rede ou ativar o modo avião, o blog compila perfeitamente, renderiza com fidelidade absoluta no navegador e não dispara uma única requisição para fora do servidor local.

Autonomia de verdade é isso.

Tipografia e ritmo vertical: o design para leitura imersiva

Se o layout do site é o seu esqueleto, a tipografia é a sua respiração. Você pode ter a melhor arquitetura do mundo, mas se a tipografia for apertada, o contraste for deficiente ou a largura das linhas for exagerada, o leitor vai cansar os olhos e fechar a aba em menos de três minutos de leitura.

Para um blog focado em ensaios e artigos aprofundados com milhares de palavras, a legibilidade é uma prioridade inegociável.

A escolha da serifa (Source Serif 4) para o corpo do texto foi uma decisão consciente contra a tendência contemporânea de colocar fontes sem serifa em tudo quanto é canto. Fontes serifadas clássicas bem desenhadas criam uma linha de base imaginária sutil que guia o olhar com suavidade ao longo dos períodos, reduzindo o esforço cognitivo em leituras longas.

Para acompanhar, travamos o contêiner do post em 760px, garantindo uma média saudável entre 65 e 75 caracteres por linha (a zona áurea do design editorial clássico) com um entrelinhas generoso de 1.75.

A hierarquia de títulos também foi aliviada: no tema antigo, os títulos H1 vinham em negrito ultrapesado (font-weight: 800), parecendo uma manchete gritada de tabloide sensacionalista. Reduzimos o peso do H1 para 500 com um leve ajuste de aproximação de caracteres (letter-spacing: -0.5px), complementando com o subtítulo em <p class="post-subtitle"> logo abaixo para contextualizar o tom do artigo sem competir com o cabeçalho.

Outro ajuste detalhado foi a calibração dos blocos de código Rouge em _sass/_syntax.scss. O realce de sintaxe herdado embutia regras que aplicavam negrito em quase todas as palavras-chave de linguagens como Java, Python e Rust, transformando trechos longos em festivais de manchas escuras.

Nivelamos palavras-chave, variáveis, funções e operadores no peso regular (font-weight: 400), fazendo o código renderizar de forma plana, limpa e confortável, exatamente como nos editores modernos.

Na página Sobre (about.md), preservamos a nossa tradicional marca visual: o caractere em escrita vertical japonesa flutuando na lateral direita da tela. Ajustamos o elemento .jp-float com opacidade suave para atuar como textura visual sem obstruir o texto corrido, e adicionamos aria-hidden="true" para garantir acessibilidade e evitar que leitores de tela tentem pronunciar o caractere decorativo.

/* O kanji vertical na página Sobre */
.jp-float {
  writing-mode: vertical-rl;
  text-orientation: upright;
  opacity: 0.15;
  user-select: none;
}

Tipografia vertical japonesa com acessibilidade: atributo aria-hidden garante silêncio aos leitores de tela.

Por fim, resolvemos o clássico bug do rodapé flutuante (o famoso Sticky Footer).

Em páginas curtas, como a de erro 404 ou em listagens de tags com apenas um post, o rodapé teimava em subir e ficar flutuando no meio da tela como uma faixa perdida. A cura veio em dez linhas de Flexbox moderno em _sass/layout/_footer.scss:

/* A cura definitiva para rodapés flutuantes */
body {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
}

main.container {
  flex: 1 0 auto;
}

.site-footer {
  margin-top: auto;
}

Comportamento de mola: o container principal empurra o rodapé para o piso em qualquer resolução.

O body assume altura mínima de 100vh, o contêiner principal preenche todo o espaço vertical livre com flex: 1 0 auto, e o rodapé recebe margin-top: auto. Seja em uma página com vinte parágrafos ou em uma tela com uma única frase de aviso, o rodapé repousa com firmeza no chão da janela, sem uma linha sequer de JavaScript.

A saga da matemática: KaTeX local sem nós cegos

Para quem escreve sobre ciência da computação, criptografia, sistemas distribuídos e física, ter suporte de primeira classe à renderização de equações matemáticas em LaTeX é mandatório. Mas aqui mora uma das maiores armadilhas de performance da web técnica: o MathJax.

Embora venerável e completo, o MathJax é colossal. Ele despeja megabytes de scripts no navegador do leitor, demora preciosos segundos para inicializar e redesenha a árvore DOM várias vezes até conseguir formatar uma fórmula simples. Em conexões móveis, a página inteira engasga.

A alternativa consagrada é o KaTeX, mantido pela equipe do Khan Academy, que desenha equações de forma síncrona, leve e sem refazer o layout da página.

Nossa primeira ideia foi tentar a gem kramdown-math-katex, que prometia interceptar os delimitadores $$ durante a compilação do site e gerar o HTML estático das equações diretamente no servidor. No papel soava perfeito, mas na prática foi um desastre silencioso.

A gem depende de uma ponte de comunicação com o Node.js no sistema operacional via ExecJS, e no meu ambiente essa amarração falhou de forma opaca: o build do Jekyll passava sem acusar erro no terminal, mas as fórmulas apareciam na página como blocos de texto cru com barras invertidas escapadas (\[ \mathcal{F} ... \]).

Parei de brigar com a compilação no servidor e adotei a abordagem pragmática: o KaTeX oficial rodando no client-side sob demanda.

Criamos um include inteligente no arquivo _includes/head.html que injeta os scripts e folhas de estilo exclusivamente se o post declarar math: true no front matter:

{% if page.math %}
  <link rel="stylesheet" href="{{ '/assets/katex/katex.min.css' | relative_url }}">
  <script defer src="{{ '/assets/katex/katex.min.js' | relative_url }}"></script>
  <script defer src="{{ '/assets/katex/contrib/auto-render.min.js' | relative_url }}"
          onload="renderMathInElement(document.body);"></script>
{% endif %}

Injeção condicional por demanda: quem lê tutoriais sem fórmulas baixa zero bytes de matemática.

Se o artigo que você está lendo é uma crônica ou um tutorial de Linux, a variável page.math não existe e o Jekyll nem sequer inclui essas tags no HTML compilado; zero scripts adicionais são trafegados.

E na pasta de fontes da biblioteca, aplicamos a mesma faxina: deletamos todos os formatos legados .ttf e .woff, deixando estritamente os vinte arquivos .woff2 necessários para símbolos AMS e alfabetos gregos. A pasta de fontes despencou de 1.2 MB para meros 250 KB, garantindo a renderização instantânea de fórmulas matemáticas como esta:

O resultado é uma matemática com nitidez vetorial absoluta, sem atrasos de carregamento e sem saltos de layout na rolagem da página. Rápido, previsível e leve como deve ser.

Sumários dinâmicos e componentes modulares: o poder do Kramdown nativo

Quem escreve artigos extensos sabe que um sumário funcional no início do texto não é um luxo decorativo, mas uma ferramenta essencial de navegação para o leitor. No meu artigo sobre a História da Internet, por exemplo, o texto é tão longo que navegar sem um índice de seções é como viajar em uma rodovia sem placas.

Durante muito tempo eu mantinha uma lista manual de tópicos no começo dos artigos, o que invariavelmente gerava links quebrados toda vez que eu renomeava um subtítulo.

Quando pesquisei como automatizar a geração do índice de seções (TOC - Table of Contents), a recomendação habitual da comunidade foi instalar o plugin jekyll-toc. Em vez de adicionar mais uma dependência ao Gemfile, fui consultar a documentação do Kramdown ⁴, o conversor padrão de Markdown do Jekyll.

Descobri que o Kramdown já possui um gerador nativo de sumários integrado desde as suas primeiras versões, dispensando qualquer gem auxiliar. Basta configurar o comportamento dos níveis de captura no arquivo _config.yml para ignorar o H1 do título principal e capturar estritamente os subtítulos H2 e H3:

# Configuração nativa no _config.yml
kramdown:
  input: GFM
  smart_quotes: ["apos", "apos", "quot", "quot"]
  toc_levels: 2..3

Ajuste do Kramdown: o índice ignora o H1 do título e captura estritamente os subtítulos H2 e H3.

No corpo do artigo, envolvemos a diretiva semântica {:toc} dentro de uma tag nativa <details class="toc-box" markdown="1" open>. O atributo markdown="1" é fundamental para que o Kramdown processe o conteúdo interno da tag HTML, varrendo os cabeçalhos do documento e gerando uma lista aninhada com identificadores de âncora funcionais automaticamente.

Para completar, estilizamos a caixa retrátil no arquivo _sass/components/_toc.scss:

/* Estilo semântico da caixa de sumário */
.toc-box {
  background-color: var(--pico-card-background-color);
  border: 1px solid var(--pico-muted-border-color);
  border-radius: 6px;
  padding: 1rem 1.25rem;
  margin: 2rem 0;

  summary {
    cursor: pointer;
    font-size: 1.05rem;
    color: var(--pico-color);
  }

  ul {
    margin-top: 0.75rem;
    padding-left: 1.5rem;

    li a {
      color: var(--pico-primary);
      text-decoration: none;

      &:hover {
        text-decoration: underline;
      }
    }
  }
}

Sumário dinâmico, elegante e retrátil sem uma linha sequer de JavaScript.

A mesma disciplina de modularidade e reaproveitamento de código (DRY - Don't Repeat Yourself) guiou a reconstrução dos demais componentes do blog. O include _includes/card.html unificou a renderização dos cartões de categorias e trilhas com contadores dinâmicos de posts; o _includes/post-list.html centralizou a exibição de metadados e paginação entre a Home e as taxonomias; o modal de apoio ao criador (_includes/pix-modal.html) foi reconstruído com travamento suave de scroll; e os diagramas dinâmicos do Mermaid.js foram desacoplados em um componente próprio (_sass/components/_mermaid.scss e _includes/mermaid.html), renderizando fluxogramas e diagramas de sequência com adaptação automática aos temas claro e escuro.

Menos código duplicado, mais coerência visual em cada recanto do site.

O teste de fogo: compilando 101 páginas e domando o HTMLProofer

Depois de mexer na fundação inteira do blog, renomear variáveis de ponta a ponta, excluir centenas de linhas de código antigo e refatorar cada template HTML, qualquer desenvolvedor é assaltado pela dúvida natural: o que foi que quebrou sem que eu percebesse?

Em um site pessoal com mais de cem páginas publicadas ao longo de anos, fazer uma checagem visual clicando em cada link pelo navegador é humanamente inviável. Fatalmente você esquecerá um link antigo, deixará uma âncora órfã ou esquecerá de fechar uma tag semântica.

Para auditar o site com rigor de engenharia, convoquei o auditor definitivo: o HTMLProofer ⁵, adicionando a ferramenta ao Gemfile dentro do grupo de testes. O utilitário compila o site estático completo e realiza uma varredura minuciosa em cada arquivo gerado na pasta _site, inspecionando links internos, imagens ausentes, scripts inexistentes e marcações malformadas.

Ao disparar o teste pela primeira vez, tomei de cara um erro seco de biblioteca C ausente:

/home/debian/.gem/ruby/3.3.0/gems/ffi-1.17.4/lib/ffi/dynamic_library.rb:94:in `load_library':
Could not open library 'libcurl': libcurl: cannot open shared object file: No such file or directory. (LoadError)
Could not open library 'libcurl.so.4': libcurl.so.4: cannot open shared object file: No such file or directory.

O susto clássico de ambiente Linux: dependência C dinâmica ausente no host.

O HTMLProofer utiliza a gem typhoeus para disparar verificações HTTP paralelas de alta velocidade, conversando diretamente com a biblioteca nativa libcurl do sistema via FFI em linguagem C. Em instalações limpas e minimalistas do Debian no WSL, a biblioteca libcurl4 não vem pré-instalada.

Um rápido sudo apt update && sudo apt install -y libcurl4 resolveu a pendência no host, mas ao reexecutar o comando esbarrei nas mudanças arquiteturais da versão 5.2.2 do auditor.

As antigas flags --check-html e --check-images foram descontinuadas porque no v5 essas checagens rodam ativadas por padrão em todas as execuções. Além disso, a versão 5 força a validação estrita de HTTPS em links externos, o que quebrava a auditoria em posts históricos antigos que citam papers acadêmicos e repositórios de universidades que ainda operam sob HTTP tradicional.

Com as opções ajustadas para o nosso cenário, o terminal processou todo o acervo sem travar em servidores acadêmicos externos:

$ bundle exec htmlproofer ./_site --disable-external --no-enforce-https
Running 3 checks (Images, Links, Scripts) in ["./_site"] on *.html files ...

Checking 287 internal links
Checking internal link hashes in 41 files
Ran on 104 files!

HTML-Proofer finished successfully.
Finished in 12.34 seconds

Certidão de nascimento do novo tema: 104 páginas auditadas e zero inconsistências.

Cento e quatro páginas estáticas compiladas, duzentos e oitenta e sete links internos auditados e quarenta e um arquivos com sumários e âncoras validados em profundidade com zero falhas. A nova arquitetura estava oficialmente homologada e pronta para produção.

Conclusão e o prazer do jardim digital

Existe uma satisfação indescritível e genuína em abrir o próprio blog no navegador e conhecer o motivo de cada pixel desenhado na tela. Saber exatamente por que cada margem foi posicionada daquela forma, entender por que cada família tipográfica foi escolhida e ter a certeza de que nenhuma requisição secreta está sendo feita pelas costas do leitor para servidores de publicidade ou telemetria é uma forma rara de paz de espírito.

Este blog deixou de ser um inquilino assustado morando de favor em um tema genérico do GitHub Pages. Ele se transformou naquilo que a cultura do software livre convencionou chamar de digital garden ⁶: um pedaço acolhedor de terra na internet que você cultiva com as suas próprias mãos, com as suas preferências estéticas, cuidando das podas, adubando a tipografia e garantindo que quem passe por aqui tenha uma experiência de leitura confortável, leve e segura.

Há uma importância quase terapêutica em cuidar do seu espaço digital como quem cuida de um jardim (afinal de contas, como já defendi por aqui, não somos todos jardineiros de software ⁷?).

Se você ficou curioso para ver como todos esses elementos visuais se comportam juntos na prática, convido você a visitar o nosso laboratório vivo no Showcase de Elementos & Design System. Lá você encontrará a escala tipográfica completa, os cinco tipos de callouts personalizados, as amostras de código em múltiplas linguagens de programação, as matrizes matemáticas do KaTeX e os detalhes expansíveis reunidos em uma única página de testes.

A casa está arrumada. O chassi está calibrado. As ferramentas estão no lugar.

Agora, o único trabalho restante é o mais prazeroso de todos: sentar na cadeira e voltar a escrever.

Referências

A manhã começou na lentidão habitual de uma instituição federal.

Entre conferir se os sistemas corporativos decidiram funcionar, tentar bater o ponto eletrônico sem receber uma mensagem críptica de erro e descobrir quem foi a alma sebosa que deixou o bule de café com um dedo de borra fria, o expediente tentava se equilibrar na sua rotina anestesiada. Era uma sexta-feira típica.

Até que alguém compartilhou no grupo uma reportagem sobre operações policiais investigando fraudes bilionárias, desvios em fundos de pensão de aposentados e a promiscuidade explícita entre figurões de terno, banqueiros e a bancada mais reacionária do Congresso.

Um assunto indigesto, mas corriqueiro.

O tipo de notícia que a maioria lê em silêncio, balança a cabeça com o cinismo resignado de quem já viu esse mesmo enredo se repetir cinquenta vezes e volta para as suas planilhas. Mas o grupo da repartição não é composto apenas por almas resignadas. Há sempre aquele indivíduo que enxerga em cada notícia desconfortável uma afronta pessoal à sua visão de mundo.

Foi aí que Josafá decidiu entrar em cena.

Para não dar nome ao coleguinha, resolvi batizá-lo de Josafá simplesmente porque sim. Tem aquela sonoridade bíblica empoeirada do Antigo Testamento, carrega um peso de cartório do século retrasado e casa sob medida com a solenidade arcaica com que ele tenta justificar o injustificável.

A figura é uma entidade sociológica fascinante.

Ele jura de pés juntos que não tem partido, que abomina a política e que suas opiniões brotam de uma razão límpida e desinteressada. Mas basta qualquer manchete arranhar a lataria da extrema-direita que o alarme interno do homem dispara como sirene de quartel.

Em menos de três minutos, ele já estava na arena digital: dedos frenéticos no teclado, pontuação errática, caixa alta para simular autoridade moral e aquele tom condescendente de quem se julga o último adulto sóbrio numa creche de funcionários públicos iludidos.

A teologia freestyle de Josafá e o aviso ignorado de Samuel

O primeiro número circense do colega foi nos brindar com um tratado improvisado sobre regimes políticos no Antigo Testamento.

Diante da crítica de colegas sobre a escalada teocrática que sequestra o debate público no país, em que clérigos milionários ditam votações orçamentárias e impõem agendas medievais, o homem não vacilou. Soltou no grupo que governos teocráticos, na verdade, não existem.

A tese era de uma audácia estarrecedora: para que houvesse uma teocracia, o próprio Deus precisaria estar sentado na cadeira presidencial assinando atos no Diário Oficial.

Como isso só teria ocorrido com o povo hebreu no deserto até o profeta Samuel ungir o Rei Saul há mais de três mil anos, a conclusão dele foi direta: qualquer líder religioso ocupando ministérios, operando emendas secretas ou usando púlpito de igreja como comício partidário é apenas um cidadão exercendo sua legítima vocação civil.

O delírio semântico foi tamanho que uma colega do setor não aguentou e jogou no chat a captura de tela de uma busca no Google: o significado literal de teocracia segundo o dicionário, com o texto grifado para não deixar margem a dúvidas.

O verbete explicava com a paciência didática que faltava ao expediente: sistema de governo em que o poder político é exercido por líderes religiosos, unindo a autoridade espiritual à do Estado. E trazia logo abaixo a constatação óbvia que desmontava a tese do iluminado em duas linhas: na prática, como uma divindade não governa diretamente, o poder fica nas mãos de sacerdotes, clérigos ou líderes que se dizem representantes de Deus na Terra.

Bastou uma consulta elementar de três segundos para implodir o castelo de cartas.

Mas para quem opera na trincheira do alinhamento cego, nem o dicionário tem autoridade. O sujeito simplesmente ignorou a definição formal da língua portuguesa. Pouco importava se colegas lembravam que o operador financeiro do esquema sob investigação era frequentador assíduo dos mesmos templos reluzentes que vendem prosperidade aos fiéis e sangram fundos de pensão de velhinhos; para o nosso profeta de repartição, admitir o fato significaria admitir a hipocrisia da própria bancada de estimação.

Diante de formulações desse calibre, é impossível não lembrar de Harry Frankfurt e de seu clássico ensaio sobre a natureza do bullshit ¹. Frankfurt estabelece uma distinção preciosa entre a mentira deliberada e a conversa fiada institucionalizada.

O mentiroso conhece a verdade e se esforça para escondê-la; ele respeita, pelo menos no plano conceitual, a autoridade dos fatos. O propagador de bullshit, por outro lado, opera num vácuo de total indiferença factual. Ele não está preocupado se sua afirmação é verdadeira ou falsa: sua única meta é produzir um ruído sonoro conveniente que o tire da defensiva e proteja sua imagem perante o público.

Essa ginástica hermenêutica é o suprassumo do bullshit. Ele inventou uma definição absurda de teocracia para neutralizar o perigo visível de um Estado confessional paralelo.

Mas a ironia maior foi o coleguinha ter evocado o livro de Samuel confiando que ninguém no grupo se daria ao trabalho de abrir o texto bíblico.

Se tivesse lido o oitavo capítulo do primeiro livro de Samuel, teria descoberto que a transição para a monarquia de Saul foi descrita nas escrituras como uma desgraça consentida ². Quando os anciãos de Israel imploraram por um monarca para "serem como todas as outras nações", a versão arcaica de clamar por um salvador da pátria autoritário, Deus ordenou que o profeta Samuel advertisse o povo com todas as letras sobre o que um governante forte faria com eles.

Samuel avisou que o rei tomaria os filhos do povo para comandar seus carros de guerra, confiscaria as filhas para serem criadas do palácio, desapropriaria os melhores campos, vinhas e olivais para enriquecer seus asseclas e cobraria um dízimo sobre as sementes para sustentar a corte dos seus oficiais.

O texto bíblico é a dissecação mais violenta da natureza predatória de um autocrata na literatura antiga.

Ele citou o Rei Saul como álibi teológico sem perceber que a Bíblia estava descrevendo com séculos de antecedência o perfil exato do projeto político que venera: a pilhagem do Estado em benefício de uma oligarquia armada.

Entra Feuerbach, sai Bela Gil

Quando encurralado pelas próprias contradições, o roteiro do mártir de repartição nunca falha: ele veste o manto do injustiçado, acusa os colegas de intolerância e solta no grupo que os outros é que estão de "mimimi" e que ninguém ali sabe dialogar.

É a clássica inversão de papéis do debatedor de aplicativo: passa a manhã inteira relativizando roubo de aposentadorias, mas na primeira contestação firme se faz de vítima da agressividade alheia.

A minha reação imediata não foi de indignação, foi de puro, cristalino e destilado deboche.

A vontade real era soltar uma daquelas frases que encerram qualquer diálogo, do tipo perguntar se o sujeito estava digitando com os cascos ou se alguém precisava esconder o vermífugo do rebanho. Mas eu tenho desconfiômetro, amor à minha paz de espírito e apego suficiente ao meu contracheque para não dar munição de graça a quem adora bancar o perseguido. O deboche precisava caber dentro de uma margem segura.

A saída foi recorrer à mais refinada diplomacia visual da internet: soltei uma figurinha da cantora Sabrina Carpenter com a mão no fone de ouvido e a legenda direta que dispensa qualquer contestação: se for chorar, manda áudio.

Há momentos na vida corporativa em que nenhuma trégua formal é capaz de traduzir a preguiça cósmica que uma lamúria dessas provoca. A figurinha operou o milagre da elegância: desarmou o coitadismo do sujeito sem deixar rastro para melindres burocráticos.

Mas a provocação teológica continuava no ar.

Assistir à fé ser domesticada e torcida como pano de chão para blindar esquema de colarinho branco em plena sexta-feira de manhã é uma provação física. O cinismo era tamanho que precisei quebrar de vez a quarta parede do expediente e soltar no chat a máxima com a qual Ludwig Feuerbach implodiu a teologia conservadora no século XIX: não foi Deus quem criou o homem à sua imagem e semelhança; foi o homem quem esculpiu Deus à sua própria imagem, projetando na divindade suas próprias fraquezas, seus preconceitos, seus interesses econômicos e seu pavor da liberdade ³.

Ou, parafraseando a apresentadora Bela Gil naquele clássico meme sobre substituições cotidianas: você pode substituir a palavra "Deus" por "Ninguém" em praticamente qualquer frase que o sentido continua rigorosamente intacto.

Quando o colega invoca a Bíblia para justificar a promiscuidade entre religião e corrupção no poder, a mecânica é rigorosamente essa. Ele não está prestando contas a uma entidade transcendental. Está conversando com o próprio eco e reverenciando suas próprias obsessões ideológicas.

O deus dessa turma é um burocrata reacionário que odeia direitos sociais, abençoa o enriquecimento de pastores inescrupulosos e se preocupa muito mais com a moral alheia do que com a justiça distributiva.

A hipocrisia ganha contornos trágicos quando confrontada com a tradição profética das próprias escrituras judaico-cristãs.

O profeta Amós registrou a aversão divina contra quem usa a liturgia como biombo para esconder a podridão social: "Odeio, desprezo as vossas festas religiosas, e não suporto as vossas assembleias solenes… Afastai de mim o ruído dos vossos cânticos; corra, porém, a justiça como as águas, e a retidão como um ribeiro perene!" ⁴.

No mesmo tom, o profeta Isaías pronunciou a sentença definitiva sobre a politicagem que assalta os desprotegidos: "Ai daqueles que fazem leis injustas e decretos de opressão para privar os pobres dos seus direitos e negar justiça aos aflitos do meu povo, fazendo das viúvas a sua presa e roubando os órfãos!" ⁵.

Roubar fundo de previdência de velhinho aposentado e esmagar a renda de quem trabalhou a vida inteira é precisamente o que Isaías condenou sob o fogo profético.

Não há um milímetro de consonância entre o texto bíblico e o projeto de desmonte social que seduz o rebanho. Mas o homem prefere ignorar Isaías e Amós. Encarar os profetas exigiria encarar a própria cumplicidade.

O teorema da caneta BIC e os fariseus do mosquito

Encurralado pelas contradições teológicas e pelos dados factuais sobre o escândalo financeiro do momento, o coleguinha recorreu ao último refúgio de quem perdeu o chão argumentativo: a falsa equivalência moral universal.

Ele digitou no grupo, com o ar compungido de quem distribui sabedoria do alto de uma montanha moral, a seguinte pérola: "só queria saber quem aqui nunca cometeu nenhum ato de corrupção… até levar uma caneta fornecida pela instituição pra casa ou imprimir uma folha pessoal na impressora do setor tá valendo. Dá pra juntar todo mundo no mesmo saco".

É o que passei a chamar de o Teorema da Caneta BIC.

Saboreie a monstruosidade dessa lógica por alguns instantes.

Na cabeça do cidadão, desviar centenas de milhões de reais de pensões públicas em conluio com banqueiros e esquecer uma caneta esferográfica de cinquenta centavos no fundo da mochila pertencem rigorosamente à mesma gaveta penal e ética. Imprimir uma folha de papel com um comprovante de residência exigido pelo próprio órgão empregador faz de você um criminoso com a mesma gravidade moral de quem lava dinheiro de milícia em contas no exterior.

Jesus de Nazaré, ao confrontar os religiosos hipócritas do seu tempo no Evangelho de Mateus, cravou uma imagem que desmonta essa falácia com quase dois mil anos de antecedência: "Guias cegos! Coais um mosquito e engolis um camelo!" ⁶.

O colega e seus semelhantes são os coadores de mosquitos do serviço público.

Eles passam o dia fiscalizando se alguém levou o clipe de papel para prender o contracheque, mas engolem, com um sorriso de aprovação e sem engasgar, o camelo inteiro da pilhagem orçamentária patrocinada por seus ídolos políticos.

Peter Sloterdijk, em sua obra monumental sobre a razão cínica, descreve com exatidão esse estado de espírito da modernidade ⁷. O cinismo contemporâneo não é a ingenuidade do ignorante que não sabe o que faz; é a postura daquele que sabe perfeitamente o que faz e, mesmo assim, continua fazendo.

A falsa equivalência não nasce de um erro honesto de proporção. Ela é um mecanismo psicológico deliberado para dissolver a responsabilidade: se todo mundo é corrupto porque todo mundo já pegou uma caneta emprestada, então ninguém é culpado por nada. A corrupção sistêmica é normalizada, o grande larápio é anistiado no imaginário coletivo e o debate público é nivelado por baixo num pântano de cinismo generalizado.

A sordidez desse argumento se torna ainda mais berrante quando olhamos para a realidade material das instituições públicas brasileiras.

Nenhum trabalhador dessas casas enriquece às custas do Estado.

O fluxo cotidiano é o exato inverso: quem atua na linha de frente do serviço público frequentemente tira dinheiro do próprio contracheque para comprar pó de café, açúcar, régua de tomadas, cabo de rede, fita adesiva e canetas, simplesmente porque os sucessivos cortes orçamentários evaporaram as verbas de custeio mais básicas.

O trabalhador subsidia o funcionamento precário da máquina pública para não deixar a população desassistida. E, ao final da jornada, ainda tem que engolir o colega de setor insinuando que ele é sócio de quadrilha financeira porque levou para casa a caneta que muitas vezes ele mesmo comprou na papelaria da esquina.

A servidão voluntária e a Síndrome de Estocolmo funcional

Chegamos então ao nó górdio da questão: por que tanta gente se comporta assim?

O que leva um servidor público, cuja estabilidade, subsistência e plano de aposentadoria dependem integralmente da higidez do Estado e da força do trabalho coletivo, a aplaudir com tanto fervor os coveiros da sua própria carreira?

Em 1548, com apenas dezoito anos de idade, o jovem francês Étienne de La Boétie formulou a pergunta que ecoa através dos séculos: qual é o vício misterioso que faz com que milhares de indivíduos suportem um tirano que não possui outro poder além daquele que eles mesmos lhe conferem ⁸?

La Boétie chamou essa aberração de servidão voluntária. Os povos, escreveu ele, deixam-se engolir e oprimir porque se acostumaram a lamber as mãos que os acorrentam. Eles próprios fornecem as armas ao tirano e sustentam o capataz que depois usará o açoite sobre suas costas.

A figura é a encarnação burocrática da servidão voluntária descrita por La Boétie.

Ele é vítima, sim, mas de uma Síndrome de Estocolmo institucional tão arraigada que chega a ser patológica.

Quando o projeto político da extrema-direita sobe ao palanque prometendo congelar salários por quase uma década, extinguir adicionais de carreira, sucatear prédios públicos, terceirizar serviços essenciais e tratar o funcionalismo como um antro de "parasitas", o coração do servidor patriota palpita de emoção.

Ele admira a truculência do capataz. Enxerga no corte de direitos alheios uma demonstração de força, sem perceber que o pescoço que repousa na lâmina da guilhotina é o seu próprio.

O escárnio atinge o ápice na contradição prática do dia a dia.

Essa trupe passou mais de cem dias assistindo seus colegas enfrentarem piquetes de greve debaixo de sol escaldante para arrancar negociações salariais e reestruturar a carreira. Eles nunca foram a uma assembleia, nunca seguraram uma faixa, nunca perderam o sono com a possibilidade de corte de ponto. Ao contrário: murmuravam pelos cantos que a paralisação era baderna de desocupados.

No entanto, quando os acordos foram firmados e os novos direitos foram homologados, quem foram os primeiros a abrir processo eletrônico para solicitar os adicionais de qualificação por competência?

Quem correu para cadastrar plano de trabalho e usufruir do regime de teletrabalho flexível?

Quem olhou o contracheque com o reajuste nos auxílios e comemorou em silêncio a aceleração dos padrões de vencimento?

Eles mesmos.

Eles usufruem avidamente de cada centavo arrancado pela luta coletiva dos trabalhadores, mas votam com orgulho no carrasco que prometeu queimar a CLT e aniquilar o serviço público. Eles querem o socialismo dos benefícios e o anarcocapitalismo do WhatsApp.

Paulo Freire decifrou esse mecanismo psíquico com a precisão dos grandes mestres: quando a formação crítica é amputada, o oprimido não sonha em libertar a si mesmo e aos seus pares; seu sonho secreto é se transformar no opressor ⁹. O oprimido hospeda a ideologia do dominador dentro da sua própria mente. Ele passa a odiar os seus semelhantes e a enxergar a si mesmo pelos olhos de quem o despreza.

Theodor Adorno e os pesquisadores de Frankfurt aprofundaram essa ferida ao mapearem a chamada personalidade autoritária ¹⁰.

O indivíduo autoritário é marcado por uma covardia estrutural: ele curva a espinha e beija o anel de quem está acima dele na hierarquia social, mas descarrega todo o seu ressentimento e fúria sobre quem está abaixo ou ao seu lado. A pessoa não tem coragem de enfrentar os grandes potentados que fraudam o sistema financeiro e expropriam a riqueza da nação; sua fúria é reservada para a caneta BIC do colega de mesa e para o sindicato que luta pelo seu próprio salário.

O simulacro de independência e o abismo cognitivo

O aspecto mais melancólico desse espetáculo é a capa de isenção sob a qual essa turma se esconde.

O bordão do "não tenho político de estimação" virou o salvo-conduto da covardia retórica. É a blindagem perfeita: permite atacar sem trégua todas as conquistas do campo progressista enquanto se mantém uma condescendência infinita com a barbárie, a milícia e a destruição ambiental.

Se questionado, o sujeito levanta as mãos fingindo santidade: "ora, eu cobro de todos igualmente".

Não cobra. A indignação do coleguinha tem endereço fixo, CEP e lado ideológico.

E quando a máscara cai, vem a chantagem moral preferida do extremismo disfarçado de virtude: a exigência de que a democracia seja infinitamente tolerante com quem trabalha dia e noite para destruí-la. O cidadão apela para a liberdade de expressão como quem saca um salvo-conduto para propagar desinformação e violência, exigindo que qualquer contestação seja recebida com tapete vermelho em nome do "respeito à divergência".

É a armadilha clássica que Karl Popper batizou de o paradoxo da tolerância em 1945 ¹¹.

A tese de Popper é cristalina e não admite relativismos: a tolerância ilimitada leva necessariamente ao desaparecimento da tolerância. Se uma sociedade aberta for complacente com quem prega a intolerância, se não estiver disposta a defender as instituições contra o assalto de quem rejeita o pacto democrático, os tolerantes serão destruídos, e a tolerância desaparecerá com eles.

Ele quer a garantia da imunidade diplomática da democracia para poder roer as suas vigas de sustentação.

Ele quer o direito irrestrito de defender a barbárie, o golpismo e o desmonte do bem comum no grupo da firma, mas exige que qualquer reação contrária seja recebida com flores e reverência. Não há pluralidade no autoritarismo. A exigência de civilidade vinda de quem apoia a truculência não é um apelo democrático: é apenas a tática do predador que exige que os outros respeitem as regras enquanto ele as rasga em praça pública.

Hannah Arendt, ao dissecar a gênese do totalitarismo moderno, alertou que o sujeito ideal para a dominação autoritária não é o fascista convicto ou o militante fanático, mas o homem comum para quem a distinção entre fato e ficção, entre verdade e mentira, simplesmente deixou de importar ¹².

Quando a realidade material é substituída pela narrativa tribal, o tecido do senso comum se rompe. Fatos perdem a relevância. Dados estatísticos são descartados como conspirações. A realidade concreta é substituída pelo que Jean Baudrillard chamou de simulacro: uma representação hiper-real construída por algoritmos e propaganda que se descola totalmente do mundo físico ¹³.

Essa mente habita o simulacro.

Para ele, as evidências de esquemas financeiros envolvendo sua turma política não passam de perseguição injusta, enquanto qualquer boato apócrifo recebido em grupos fechados é tratado como revelação divina. Não há ponte de diálogo com quem abandonou o princípio da realidade em favor de uma alucinação digital compartilhada.

O canário na mina de carvão

Por volta das dez da manhã, o grupo de WhatsApp silenciou.

Após o confronto sobre Feuerbach, o Rei Saul e a fábula da caneta BIC, o alecrim dourado, que nasceu sem ser semeado, aplicou uma manobra de saída à francesa. Soltou um evasivo "bom, vou trabalhar porque preciso produzir, ao contrário de uns e outros", colocou um emoji de joinha e desconectou.

O expediente então logo voltou à sua lentidão cinzenta.

A tentação imediata seria reduzir todo esse episódio a uma anedota de escritório, mais um causinho hilário de repartição para contar numa mesa de bar. Mas a verdade é infinitamente mais sombria.

O funcionalismo público federal, com toda a sua estabilidade e acesso privilegiado ao conhecimento, não é uma bolha desconectada da realidade nacional. Pelo contrário: ele funciona como um microcosmo privilegiado da fratura moral e cognitiva que está apodrecendo a sociedade brasileira por dentro.

Se os indivíduos que deveriam guardar o pensamento crítico se tornaram reféns voluntários da servidão e do cinismo, o que resta para o restante de um país bombardeado vinte e quatro horas por dia por algoritmos de ódio e púlpitos de extorsão?

O debate no WhatsApp não foi um desentendimento passageiro entre colegas de setor. Foi o sintoma microscópico de um país que perdeu a vergonha do absurdo, que trocou a solidariedade de classe pelo fetiche do chicote e que continua cavando o próprio abismo, convicto de que a culpa pela escuridão é da caneta que alguém esqueceu no bolso.

Referências

Se você já perdeu horas tentando entender por que as VMs do Vagrant conseguiam pingar a internet mas não se enxergavam entre si, ou por que um vagrant up subia seis máquinas idênticas com a mesma rota padrão apontando pro lugar errado, esse post é pra você. Vamos resolver cada um desses problemas, explicar as decisões por trás de cada linha de configuração e, no final, ter um ambiente local completamente funcional com VMs prontas para receber o cluster nas próximas partes.

O que você precisa ter instalado

Antes de qualquer coisa, seu hospedeiro Linux precisa de cinco ferramentas. Essas são as únicas instalações manuais que você vai fazer em todo o processo: tudo o que acontece dentro das VMs (chaves SSH, configuração de rede, pacotes, provisionamento) é gerenciado automaticamente pelo Vagrantfile e pelo Ansible quando você roda make up.

A forma de instalar cada uma varia conforme a sua distribuição, então não vou prescrever comandos aqui. O importante é que todas estejam disponíveis no PATH do seu usuário. Uma coisa que pode pegar desprevenido: o KVM precisa de permissões de grupo. Sem elas, o Vagrant vai pedir senha de root a cada operação ou simplesmente falhar silenciosamente. Garanta que o seu usuário pertence aos grupos libvirt e kvm (e faça logout/login depois de adicioná-los).

A saída do check-deps é direta ao ponto:

$ make check-deps
Verificando dependências do host...
  - Ansible: OK
  - Vagrant: OK
  - KVM (/dev/kvm): OK
  - Conexão Libvirt (virsh): OK
  - Vagrant Libvirt Plugin: OK
  - Porta 6443 (Conflitos locais): LIVRE
Tudo OK! Pronto para iniciar o provisionamento.

Se alguma linha aparecer como NÃO ENCONTRADO ou SEM PERMISSÃO, o comando aborta a execução e te diz exatamente o que falta. Sem surpresas no meio do provisionamento.

Por que KVM e não VirtualBox

A decisão de usar LibVirt ¹ com KVM ² em vez do VirtualBox foi, antes de tudo, uma questão de manter a stack o mais open source possível. O KVM é um módulo nativo do kernel Linux, mantido no mainline pela própria comunidade do kernel. O libvirt é LGPL. Tudo roda com ferramentas que vêm nos repositórios da sua distribuição, sem precisar baixar pacotes proprietários ou aceitar licenças de uso restritivo.

Sim, o VirtualBox também usa um módulo de kernel (vboxdrv) para acessar as extensões de virtualização do processador, então não é uma questão de "um usa hardware e o outro não". Ambos fazem virtualização assistida por hardware. Mas o módulo do VirtualBox é mantido fora da árvore do kernel, distribuído pela Oracle sob uma licença que mistura GPLv3 com componentes proprietários no Extension Pack, e precisa ser recompilado a cada atualização de kernel. Com KVM, esse atrito simplesmente não existe.

Na prática, pra um cluster Kubernetes com cinco a nove VMs rodando simultaneamente e disputando CPU, memória e disco, tanto KVM quanto VirtualBox vão entregar performance razoável. A diferença real é filosófica e operacional: com KVM você está usando a infraestrutura nativa do seu sistema operacional, sem dependências externas.

O Vagrant ³ funciona como uma camada de abstração sobre o hipervisor. Ele não cria VMs sozinho: ele precisa de um provider que saiba efetivamente gerenciar o ciclo de vida das máquinas. O plugin vagrant-libvirt ⁴ faz essa ponte, traduzindo as instruções do Vagrantfile para chamadas à API do libvirt, que por sua vez comanda o KVM.

AlmaLinux 10: a distro das VMs

Para as máquinas virtuais do laboratório, escolhemos o AlmaLinux 10 ⁵ como sistema operacional base. Essa escolha não é um capricho estético.

O AlmaLinux é uma distribuição binariamente compatível com o Red Hat Enterprise Linux (RHEL), o que significa que tudo o que funciona no RHEL funciona aqui sem adaptação. Isso é relevante porque a maior parte da documentação corporativa de Kubernetes e os guias de hardening de segurança assumem um ecossistema RHEL-like (CentOS, Rocky, AlmaLinux). Do ponto de vista prático, a versão 10 traz o NetworkManager como gerenciador de rede padrão com o nmcli já integrado, systemd atualizado, e boxes oficiais para Vagrant publicados e mantidos ativamente no Vagrant Cloud.

Se você preferir usar outra distribuição (Ubuntu, Debian, openSUSE), o conceito por trás de cada etapa será idêntico, mas os comandos de pacote, os caminhos de configuração e o gerenciador de rede podem ser diferentes. No nosso caso, o nmcli é protagonista absoluto na configuração de rede das VMs, e ele é cidadão de primeira classe no ecossistema RHEL.

O Vagrantfile dissecado

Agora vamos ao arquivo que orquestra toda a criação das máquinas virtuais. O Vagrantfile do k8s-in-a-box não é um arquivo estático com meia dúzia de VMs hardcoded. Ele é um programa Ruby que lê dinamicamente o inventário do Ansible e constrói as VMs a partir das definições que encontra ali.

Leitura dinâmica do inventário

A mágica começa logo nas primeiras linhas:

require 'yaml'

inventario = YAML.load_file("inventario/hosts.yml")
grupos = inventario["all"]["children"]

nodes = {}

grupos.each do |grupo, dados|
  next unless dados["hosts"]

  dados["hosts"].each do |nome, props|
    nodes[nome] = {
      "ip"        => props["ansible_host"],
      "memory"    => props["memory"],
      "cpus"      => props["cpus"],
      "autostart" => props.fetch("autostart", true)
    }
  end
end

O Vagrant carrega o arquivo inventario/hosts.yml (que é um symlink para a topologia ativa), percorre todos os grupos do inventário e extrai IP, memória, CPUs e a flag de autostart de cada host.

A beleza desse mecanismo é que o Vagrantfile nunca precisa ser editado. Quer adicionar um worker? Bota no inventário YAML. Quer trocar a topologia inteira? Muda o symlink. A mesma lógica em Ruby vai gerar as VMs corretas independente de quantas máquinas estejam definidas no inventário.

O hash nodes resultante é um dicionário simples onde a chave é o nome da VM e o valor contém as especificações de hardware. Pra topologia mini, por exemplo, ele vai conter seis entradas: loadbalancer1, nfs1, manager1, worker1, worker2 e kubox.

Geração automática de chaves SSH

Um dos objetivos do projeto é que você não precise configurar nada manualmente dentro das VMs. Isso inclui o acesso SSH: antes de criar qualquer máquina, o Vagrantfile gera um par de chaves ed25519 caso elas ainda não existam:

unless ARGV.include?("destroy")
  unless File.exist?('id_ed25519') && File.exist?('id_ed25519.pub')
    system('ssh-keygen -t ed25519 -f id_ed25519 -N "" >/dev/null 2>&1')
    puts "Nova chave SSH gerada."
  end
end

Gera uma chave ed25519 sem passphrase, apenas se ela não existir e se o comando não for vagrant destroy.

Durante a criação de cada VM, essa chave pública é automaticamente injetada no authorized_keys do usuário vagrant. É com ela que o Ansible vai se conectar às máquinas depois, sem que você precise copiar chaves manualmente, editar authorized_keys ou configurar qualquer coisa. O config.ssh.insert_key = false logo adiante desativa a inserção da chave padrão do Vagrant, garantindo que a única chave de acesso seja a do projeto. O arquivo ssh_config na raiz do repositório já aponta para essa chave e desabilita a verificação de host keys, fechando o ciclo: Vagrant gera, injeta e o Ansible usa.

E quando o cluster é destruído? Um trigger pós-destruição cuida da limpeza:

config.trigger.after :destroy do |trigger|
  trigger.ruby do |env, machine|
    arquivos = ['id_ed25519', 'id_ed25519.pub']
    if arquivos.any? { |f| File.exist?(f) }
      arquivos.each { |f| File.delete(f) if File.exist?(f) }
      puts "Chaves SSH removidas."
    end
  end
end

Remove as chaves SSH quando todas as VMs são destruídas. Ciclo de vida limpo.

Configuração global do provider LibVirt

A configuração do provider KVM é definida uma única vez e aplicada a todas as VMs:

config.vm.provider :libvirt do |libvirt|
  libvirt.driver = "kvm"
  libvirt.memorybacking :source, :type => "memfd"
  libvirt.memorybacking :access, :mode => "shared"

  libvirt.cpu_mode = "host-model"
  libvirt.nested = true

  libvirt.nic_model_type = "virtio"
  libvirt.management_network_name = "vagrant"
  libvirt.management_network_address = "192.168.250.0/24"
  libvirt.management_network_mode = "none"
  libvirt.management_network_autostart = true
end

Configuração do hipervisor: KVM com virtio, CPU passthrough em modo host-model, e rede de gerenciamento do Vagrant em 192.168.250.0/24 sem NAT.

Duas decisões chamam atenção aqui. Primeiro, o cpu_mode = "host-model" expõe os flags da CPU do hospedeiro diretamente para as VMs, o que é essencial para o eBPF do Cilium funcionar corretamente. Segundo, a rede de gerenciamento do Vagrant (192.168.250.0/24) é configurada com mode = "none", sem NAT e sem DHCP. Essa é a rede eth0 que o Vagrant usa internamente pra comunicação via SSH. O cluster não usa essa rede pra nada.

Criação das VMs e a rede privada

O loop principal itera sobre cada nó do hash nodes e cria uma VM correspondente:

nodes.each do |nome_no, specs|
  config.vm.define nome_no, autostart: specs["autostart"] do |node|
    node.vm.hostname = nome_no
    node.vm.network "private_network", ip: specs["ip"],
      libvirt__network_name: "k8sbox_mgmt",
      libvirt__forward_mode: "nat",
      libvirt__dhcp_enabled: false

    node.vm.provider :libvirt do |libvirt_host|
      libvirt_host.default_prefix = "k8sbox_"
      libvirt_host.memory = specs["memory"]
      libvirt_host.cpus = specs["cpus"]
    end
    # ... provisionamento de rede (próxima seção)
  end
end

Para cada host no inventário, cria uma VM com o IP fixo definido, conecta à rede k8sbox_mgmt em modo NAT sem DHCP, e aplica as configurações de memória e CPU.

Aqui o detalhe crucial: a rede k8sbox_mgmt é criada com forward_mode: "nat" e dhcp_enabled: false. Isso significa que as VMs terão acesso à internet (via NAT do host) mas sem servidor DHCP atribuindo IPs automaticamente. Os IPs são estáticos e definidos pelo inventário. Essa rede será a eth1 dentro das VMs e é por onde todo o tráfego do cluster vai transitar.

Note também o autostart: specs["autostart"]. No inventário, o kubox é definido com autostart: false. Ele não sobe junto com as demais VMs quando você roda vagrant up, porque durante a construção do cluster ele ainda não é necessário. O Makefile cuida de subi-lo separadamente no momento certo.

As duas placas de rede (e a armadilha do eth0)

Toda VM criada pelo nosso Vagrantfile recebe duas interfaces de rede. Isso é proposital, mas causa um problema que se você não tratar, vai quebrar todo o funcionamento do cluster.

A eth0 é a rede de gerenciamento do Vagrant. Ela existe porque o Vagrant precisa de uma forma de se comunicar com a VM via SSH para provisionamento e comandos como vagrant ssh. Mas essa rede é completamente inútil para o cluster Kubernetes. Pior: se deixada sem tratamento, ela se torna a rota padrão da VM, e todo o tráfego de saída vai por ela em vez de ir pela eth1 onde o cluster mora.

A eth1 é a rede privada 172.24.0.0/24, que é o verdadeiro sistema circulatório do laboratório. Todo tráfego do etcd, do kube-apiserver, dos pods e dos serviços transita por essa interface.

A guerra dos gateways via nmcli

Aqui entra o trecho mais importante do Vagrantfile: o provisionamento de rede via shell que resolve a prioridade entre as interfaces. Esse script foi resultado de bastante experimentação, especialmente na migração do AlmaLinux 9 para o 10, onde o comportamento do NetworkManager ⁶ mudou significativamente.

No AlmaLinux 9, os nomes das conexões eram previsíveis (eth0, System eth1). Na versão 10, o NetworkManager passou a nomear as conexões de forma genérica (Wired connection 1, Wired connection 2), o que quebrou todas as referências estáticas que eu tinha no Vagrantfile. A solução foi implementar uma detecção dinâmica dos nomes das conexões por dispositivo:

# --- Ajustes de nomenclatura dinâmicos ---
CON_VAGRANT=$(nmcli -t -f NAME,DEVICE connection show \
  | grep ':eth0$' | cut -d: -f1 | head -n1)
CON_MGMT=$(nmcli -t -f NAME,DEVICE connection show \
  | grep ':eth1$' | cut -d: -f1 | head -n1)

if [ -n "$CON_VAGRANT" ]; then
  nmcli con mod "$CON_VAGRANT" connection.id net_vagrant ifname eth0
fi
if [ -n "$CON_MGMT" ]; then
  nmcli con mod "$CON_MGMT" connection.id net_mgmt ifname eth1
fi
nmcli con reload

Descobre dinamicamente qual conexão está associada a cada dispositivo físico (eth0, eth1) e renomeia para nomes previsíveis (net_vagrant, net_mgmt).

Depois de renomear, o script trata cada interface individualmente:

# --- Configurações net_vagrant ---
nmcli con mod net_vagrant \
  connection.autoconnect yes \
  connection.autoconnect-priority -999  \
  ipv4.route-metric 500 \
  ipv4.ignore-auto-dns yes \
  ipv4.never-default yes \
  ipv6.method ignore

nmcli con reload && nmcli con up net_vagrant

Rebaixa a eth0: métrica 500 (baixa prioridade), ignora DNS do DHCP, never-default impede que ela se torne gateway. IPv6 desabilitado.

# --- Configurações net_mgmt ---
nmcli con mod net_mgmt \
  ipv4.method manual \
  ipv4.addresses "172.24.0.31/24" \
  ipv4.gateway "172.24.0.1" \
  ipv4.route-metric "50" \
  ipv4.dns "1.1.1.1,8.8.8.8" \
  ipv6.method ignore \
  ipv4.dns-search "k8sbox.local"

nmcli con reload && nmcli con up net_mgmt

Configura a eth1 como interface principal: IP manual, gateway apontando para o NAT do libvirt, métrica 50 (alta prioridade), DNS públicos e domínio de busca do cluster.

A jogada é a combinação de never-default yes na eth0 com route-metric 50 na eth1. O never-default diz ao NetworkManager que a eth0 nunca deve ser usada como gateway padrão, independente do que o DHCP sugira. E a métrica 50 na eth1 garante que, se por qualquer motivo ambas as rotas existirem na tabela, a eth1 vence.

Antes da migração para o AlmaLinux 10, o provisionamento de rede usava referências estáticas como nmcli con mod eth0 e criava conexões novas do zero com nmcli con add. A versão 10.1 mudou o esquema de nomenclatura das conexões e exigiu a abordagem dinâmica com detecção por dispositivo. Se você estiver portando o projeto para outra distro, esse é um dos trechos que pode precisar de ajustes.

E pra fechar o script de provisionamento: tem um trecho crucial que lida com o xerife do sistema operacional:

# --- Configura o SELinux como Permissive ---
setenforce 0
sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config

# --- Corrige rotulos de SELinux dos arquivos criados pelo Vagrant ---
restorecon -R /etc/NetworkManager/system-connections/

Coloca o SELinux em modo permissivo e restaura os rótulos dos arquivos de conexão do NetworkManager criados pelo Vagrant.

O Vagrant cria arquivos de configuração de rede dentro da VM durante o processo de boot, mas esses arquivos nascem sem os rótulos de SELinux corretos. O NetworkManager simplesmente recusa processar conexões com rótulos inválidos quando o SELinux está ativo. Esse restorecon corrige o problema silenciosamente.

O sistema de topologias: três clusters, um repositório

Na Parte 1, apresentamos as três configurações de cluster disponíveis: nano, mini e completo. Agora vamos ver como esse sistema funciona por dentro.

A engrenagem é simples e elegante: um arquivo de configuração (config.mk), um diretório com os inventários pré-definidos (configs/) e um symlink que conecta os dois.

k8s-in-a-box/
├── config.mk                        <-- Escolha da topologia
├── configs/
│   ├── hosts-nano.yml               <-- 5 VMs (~6.5GB RAM)
│   ├── hosts-mini.yml               <-- 6 VMs (~11GB RAM)
│   └── hosts-completo.yml           <-- 9 VMs (~19.5GB RAM)
└── inventario/
    └── hosts.yml -> ../configs/hosts-mini.yml  <-- Symlink ativo

O config.mk é um fragmento de Makefile que define uma única variável:

CLUSTER = mini

O arquivo inteiro. Uma linha. Altera esse valor para nano ou completo e rode make init.

Quando você executa make init, o Makefile verifica se o arquivo de inventário correspondente existe e cria o symlink:

$ make init
Configuração mini ativada

O make status mostra qual configuração está ativa em qualquer momento:

$ make status
Configuração ativa: mini

Anatomia de um inventário

Cada arquivo de topologia é um inventário YAML do Ansible padrão. Vamos olhar o hosts-mini.yml como exemplo:

all:
  vars:
    ansible_user: vagrant

  children:
    loadbalancers:
      hosts:
        loadbalancer1:
          ansible_host: 172.24.0.21
          fqdn: loadbalancer1.k8sbox.local
          memory: 384
          cpus: 1

    managers:
      hosts:
        manager1:
          ansible_host: 172.24.0.31
          fqdn: manager1.k8sbox.local
          memory: 3072
          cpus: 2

    workers:
      hosts:
        worker1:
          ansible_host: 172.24.0.41
          fqdn: worker1.k8sbox.local
          memory: 3072
          cpus: 2
        worker2:
          ansible_host: 172.24.0.42
          fqdn: worker2.k8sbox.local
          memory: 3072
          cpus: 2

    clientes:
      hosts:
        kubox:
          ansible_host: 172.24.0.254
          fqdn: kubox.k8sbox.local
          memory: 1024
          cpus: 1
          autostart: false

Topologia mini: 1 LB, 1 NFS, 1 manager, 2 workers e o bastion host. Total de 6 VMs.

Cada host carrega quatro campos obrigatórios: ansible_host (o IP na rede 172.24.0.0/24), fqdn (o nome completo no domínio k8sbox.local), memory (RAM em MB) e cpus (número de vCPUs). Esses são os mesmos campos que o Vagrantfile lê para criar as VMs.

A estrutura de grupos (loadbalancers, managers, workers, clientes) não é cosmética. O Ansible usa esses grupos para decidir quais roles aplicar em quais máquinas. Os managers recebem etcd e control plane. Os workers recebem apenas o kubelet. Os load balancers recebem HAProxy e Keepalived. E o kubox recebe as ferramentas de operação.

Comparando as três topologias em números:

A configuração completo é a única que viabiliza testes reais de alta disponibilidade: com três managers, o etcd forma quorum e tolera a perda de um nó. Com dois load balancers, o Keepalived faz failover do VIP. Mas ela exige quase 20 GB de RAM livre no host, o que nem todo mundo tem à disposição.

O Makefile como interface de comandos

Rodar o Ansible manualmente para testar uma única role envolve montar um comando com variáveis de ambiente, caminho do arquivo de configuração, caminho do playbook, flags de tags e eventuais opções de verbosidade. É o tipo de coisa que você digita uma vez, erra um caractere no meio e perde cinco minutos descobrindo por quê. O Makefile ⁷ do projeto encapsula toda essa complexidade em targets legíveis:

════════════════════════════════════════════════════════════
  K8s in a Box - Makefile
════════════════════════════════════════════════════════════

Uso:
  make init                 # Ativa a configuração definida no config.mk
  make k8s-in-a-box         # Executa a esteira completa (ou 'make build')
  make status               # Mostra o tamanho de cluster ativo

Lista de targets:
  make init                  Ativa uma configuração de cluster
  make status                Mostra a configuração de cluster ativa
  make check-deps            Verifica se todas as dependências locais estão instaladas
  make up                    Sobe todas as VMs do cluster
  make down                  Interrompe todas as VMs do cluster
  make destroy               Exclui permanentemente todas as VMs
  make clean                 Deleta as VMs e limpa todos os artefatos
  make infra                 Prepara infraestrutura pré-k8s (PKI, SO, Balanceador, NFS)
  make control-plane         Instala o Kubernetes core (Kubelet, Etcd, Static Pods)
  make cluster               Executa o provisionamento do cluster completo
  make ops                   Provisiona completamente a VM de operações
  make addons                Instala ferramentas operacionais adicionais
  make exemplos              Faz deploy das aplicações de demonstração
  make snapshot              Cria uma snapshot única de todas as VMs
  make restore               Restaura o cluster para a última snapshot criada

Os targets são organizados em camadas que refletem a ordem de dependência do cluster:

1. Configuração: init, status, check-deps
2. Ciclo de vida das VMs: up, down, destroy, clean
3. Provisionamento do Kubernetes: infra, control-plane, cluster
4. Operações e rede: ops, cni
5. Aplicações: addons, exemplos
6. Snapshots: snapshot, restore

O target k8s-in-a-box (aliás de build) é o comando de esteira completa. Ele executa toda a cadeia na ordem correta:

build: up cluster ops addons exemplos

Um target, cinco etapas em sequência: sobe VMs, provisiona cluster, configura operações e rede, instala addons e deploya exemplos.

O mecanismo garante-config

Todo target que interage com o Vagrant ou o Ansible depende do target interno garante-config:

garante-config:
	@CURRENT_LINK=$$(readlink "$(CLUSTER_LINK)" 2>/dev/null || echo ""); \
	EXPECTED_LINK="../$(CLUSTER_SOURCE)"; \
	if [ "$$CURRENT_LINK" != "$$EXPECTED_LINK" ]; then \
		echo "Sincronizando configuração do inventário para $(CLUSTER)..."; \
		$(MAKE) init; \
	fi

Verifica se o symlink atual corresponde à topologia definida no config.mk. Se estiver dessincronizado, re-executa o make init automaticamente.

Esse mecanismo evita um cenário traiçoeiro: você edita o config.mk para mudar de mini para completo, esquece de rodar make init, e acaba provisionando o cluster com a topologia errada. Com o garante-config, esse desalinhamento é corrigido automaticamente antes de qualquer operação.

Snapshots: seu seguro contra desastres

Quando o cluster está funcionando e você quer experimentar uma mudança arriscada (trocar o CNI, rotacionar certificados, testar uma versão diferente do Kubernetes), as snapshots salvam a sua vida:

make snapshot    # Salva o estado atual de todas as VMs
make restore     # Restaura todas as VMs para o último snapshot

Cada make snapshot sobrescreve o snapshot anterior (não é um sistema de múltiplos pontos de restauração). A ideia é simples: antes de uma operação potencialmente destrutiva, salva. Se deu errado, restaura. Sem precisar reconstruir o cluster inteiro do zero, que dependendo da topologia leva de dez a trinta minutos.

Do zero ao ambiente funcional: o fluxo completo

Pra quem quer ver tudo funcionando de uma vez, o caminho mínimo é:

git clone https://github.com/vndmtrx/k8s-in-a-box.git
cd k8s-in-a-box
make check-deps
make init
make up

O make up é onde a mágica visível acontece. Ele cria o diretório de artefatos, executa vagrant up, e o Vagrant cuida de absolutamente tudo sozinho: lê o inventário, cria as VMs no KVM, gera as chaves SSH, injeta a chave pública em cada máquina, configura as duas interfaces de rede via nmcli e corrige os rótulos de SELinux. Você não precisa entrar em nenhuma VM pra configurar nada. Quando o comando termina, as máquinas já estão acessíveis pelo Ansible.

O resultado final são VMs AlmaLinux 10 com:

• Rede eth0 (net_vagrant) rebaixada e sem rota padrão
• Rede eth1 (net_mgmt) como interface principal com IP estático e gateway
• SELinux em modo permissivo (estágio transitório de auditoria para compilar as regras antes do enforcing)
• Chave SSH do projeto no authorized_keys (gerada e injetada automaticamente)
• Conectividade plena entre todas as VMs na faixa 172.24.0.0/24
• Ansible pronto para se conectar via o ssh_config do projeto

Nenhum componente Kubernetes instalado. Nenhuma role Ansible executada. Apenas máquinas virtuais com o sistema operacional base, rede configurada e prontas para receber o cluster.

Diagnóstico e Troubleshooting

Se algo der errado no processo de subida das VMs, aqui estão os comandos de diagnóstico essenciais:

Status das VMs

vagrant status

Mostra o estado atual de cada VM (running, shutoff, not created).

virsh list --all

Lista todas as VMs no hipervisor KVM, incluindo as que estão desligadas. Útil quando o Vagrant perde a referência para uma VM.

Verificação de rede dentro das VMs

Conecte-se a uma VM e inspecione a configuração de rede:

vagrant ssh manager1

Dentro da VM:

nmcli con show

Lista todas as conexões do NetworkManager. Você deve ver net_vagrant (eth0) e net_mgmt (eth1) com os nomes que definimos.

nmcli con show net_mgmt | grep -E "ipv4\.(addresses|gateway|route-metric|dns)"

Verifica se a eth1 está configurada corretamente com o IP, gateway, métrica e DNS.

Teste de conectividade entre VMs

De qualquer VM, teste o acesso a outra:

ping -c 3 172.24.0.31    # manager1
ping -c 3 172.24.0.41    # worker1
ping -c 3 172.24.0.21    # loadbalancer1

Se algum ping falhar, verifique se a rede k8sbox_mgmt existe no libvirt com virsh net-list --all.

Problemas comuns

Conclusão

Se tudo correu bem, neste momento você tem um ambiente de laboratório completo rodando na sua máquina: cinco a nove VMs AlmaLinux 10 interconectadas numa rede privada isolada, com IPs estáticos previsíveis, chaves SSH distribuídas e uma interface de Makefile que simplifica tudo.

Não tem Kubernetes instalado ainda. Não tem certificado gerado. Não tem nenhum serviço rodando. E isso é proposital. A ideia de separar a infraestrutura do hospedeiro do provisionamento do cluster permite que você destrua e recrie as VMs quantas vezes precisar sem perder tempo reinstalando ferramentas no seu sistema operacional.

No próximo post (Parte 3: O Inventário Ansible e as Variáveis do Cluster), vamos mergulhar na outra metade do cérebro do projeto: o arquivo all.yml onde todas as variáveis do cluster moram, o .ansible.cfg com suas decisões de configuração, e como uma única mudança de variável propaga por todo o ecossistema de roles e playbooks. É onde o Ansible deixa de ser apenas uma ferramenta de automação e vira o mapa completo do cluster que estamos construindo.

Referências

Existe uma vergonha velada na internet quando o assunto é usar IA para escrever. De um lado, a seita dos puristas: gente que jura de pés juntos que cada frase brotou de um nirvana diante da tela, como se fossem poetas do século XIX sofrendo por amor (quando na verdade só têm vergonha de admitir que usam corretor ortográfico até pro "bom dia" no chat corporativo). Do outro, a horda do prompt mágico: os gênios da automação que colaram um comando genérico, ou construíram um prompt altamente complexo e específico, copiaram o vômito sintático da máquina e publicaram achando que inventaram a roda.

Os dois lados compartilham a mesmíssima ilusão: acham que escrever com IA é apertar um botão e esperar o milagre pronto ¹.

Quem realmente senta para escrever de verdade sabe que não é nada disso. Não é automação; é pura briga de foice no escuro. É uma sessão de pair writing regada a atrito, onde o texto só sai porque duas entidades completamente cegas de seus próprios vícios entram em rota de colisão constante: uma dinâmica que tem muito menos a ver com "produtividade corporativa" e muito mais com a teoria dialógica de Bakhtin.

A dança das duas cegueiras

O título deste post não é metáfora fofa (Saramago que o diga) ². Escrever a quatro mãos com uma LLM é basicamente colocar dois cegos para discutir a cor da parede de uma casa:

A primeira é a cegueira da máquina. O modelo tem bilhões de parâmetros decorados, lê uma enciclopédia em três milissegundos, mas tem a sensibilidade de uma britadeira. Ele não tem corpo, nunca passou pela humilhação de reprovar numa prova de lógica e não faz a menor ideia da diferença entre uma ironia ácida e uma piada de tiozão no churrasco de domingo. Se você deixar a IA solta, ela vai invariavelmente produzir um texto engomado, prolixo e com aquele tom insuportável de coach motivacional de firma.

A segunda é a cegueira do autor. E aqui entra a minha própria incompetência: quando estou escrevendo, perco completamente o senso de proporção. Fico apegado àquela piada ruim que achei genial às duas da manhã, empilho analogias (entre parênteses) como se não houvesse amanhã, repito as mesmas três palavras de efeito em todo santo parágrafo e tenho a ilusão de que o leitor tem a obrigação moral de acompanhar as voltas do meu labirinto mental.

A mágica não acontece quando um cede ao outro. Acontece quando a gente se cansa das tosquices mútuas e começa a cortar excessos.

Bakhtin e a palavra meio alheia

O filósofo russo Mikhail Bakhtin tinha uma tese que resume perfeitamente essa bagunça ³:

Para ele, a linguagem nunca é 100% nossa desde o berço. A palavra é sempre "meio alheia" até o momento em que você a ocupa com a sua intenção, o seu sotaque e o seu contexto.

Na prática, isso destrói tanto a pose do purista quanto a preguiça de quem copia e cola.

Eu não abro o chat pedindo "escreva um artigo sobre tal coisa". Fazer isso é pedir para receber um monte de clichês plastificados que parecem gerados para agradar algoritmo de busca. Mas também não tenho a frescura de fingir que nunca travo numa frase. Às vezes estou no meio de um raciocínio truncado e solto na lata: "como você desenrolaria esse parágrafo?". A máquina me cospe três variações, eu leio a primeira com cara de desdém, acho a segunda intragável, pesco uma única conjunção que prestou na terceira e reescrevo tudo por cima com a minha própria voz (ou, às vezes, jogo de volta na mesa pedindo para ela reescrever o parágrafo em volta daquela ideia).

Mas a direção fundamental é sempre minha. Eu não peço pra máquina criar: eu crio. Depois largo o rascunho na frente dela e pergunto onde o texto perdeu o fio, onde a analogia forçou, onde o parágrafo ficou pesado. A dinâmica se parece com ter um secretário que domina o lado operacional da escrita: alguém que percebe quando uma transição engasgou, que avisa quando repeti a mesma palavra três vezes, que sugere uma conjunção melhor quando a frase empacou. Mas quem decide o que o texto vai dizer, qual posição defender, qual piada fica e qual analogia morre: sou eu. A máquina ajuda a fechar o texto depois que eu já decidi o que ele precisa ser.

O processo vira um sparring cínico:

• Eu testo analogias e pergunto se aquilo faz sentido ou se é só loucura da minha cabeça;
• Peço para a máquina simular o leitor chato: "qual contra-argumento óbvio alguém na defensiva vai jogar na minha cara aqui?";
• Peço diagnósticos secos: "o que ficou forçado, palestrinha demais ou com cara de redação nota mil do ENEM?".

O atrito dialógico na prática

Isso só funciona porque eu não trato a IA como um script de autocompletar e muito menos como uma divindade consciente. Trato como uma entidade interlocutora: alguém que está do outro lado do ringue pronto para tomar um jab retórico e também devolver um diagnóstico direto sem melindre.

A dinâmica é uma via de mão dupla de desconfiança mútua.

De um lado, o que a IA aponta sobre os meus cacoetes:

• O espelho do ritmo: Avisa que empilhei analogias até o leitor perder o ar, que usei o mesmo adjetivo dramático duas vezes na mesma página ou que uma explicação pareceu um livro didático enciclopédico em vez de um relato honesto;
• O teste de estresse: Levanta furos lógicos e contra-argumentos que eu ignorei porque estava apaixonado demais pela minha própria tese;
• A elasticidade: Oferece rapidamente caminhos sintáticos diferentes quando uma transição fica estranha.

Do outro lado, o que eu faço como a vigilância sanitária do texto:

• Podo o verniz corporativo: Corto na hora a tentação da máquina de soar como texto de Linkedin ou de meter metáforas quinta-série;
• Puxo a orelha da superficialidade: Se o modelo traz um consenso frouxo, eu jogo autores reais e contraexemplos na roda para forçar a discussão a descer um degrau;
• Auditoria implacável de fontes: Cobro a validação exata de cada referência para garantir que ela não inventou uma citação com cara de verdade absoluta.

Identificado o problema de um lado ou de outro, a gente volta para a mesa de cirurgia textual:

1. O diagnóstico: Apontamos onde o texto virou lixo, perdeu o ritmo ou ficou pedante;
2. O debate: Discutimos abordagens diferentes para resolver aquele impasse;
3. A navalha: Eu reescrevo sem dó, garantindo que o sotaque e o sangue do autor fiquem na página.

Um parágrafo que presta nunca sai de um comando milagroso. Ele sai da paciência cínica de rejeitar versões ruins até a frase parar em pé.

E aqui mora um detalhe que a turma do "a IA escreve tudo" ignora: o processo é lento. Cada seção de um post passa por múltiplas rodadas de reescrita. A maioria das sugestões que a máquina oferece morre na mesa de edição, não porque estejam gramaticalmente erradas, mas porque não soam como eu. O filtro final nunca é "está correto?". É "eu escreveria isso?". Se a frase não sobrevive a esse teste, não importa o quão bem construída ela esteja: vai pro lixo.

Onde mora a autoria?

A discussão sobre "a IA vai matar a autoria" é de uma preguiça monumental. Ela assume que escrever é apenas a atividade física de bater dedos descontroladamente num teclado. Se fosse só isso, um gerador de lero-lero programado nos anos 90 seria autor de enormes best-sellers.

A verdade é que esse processo escancara uma realidade desconfortável: a máquina tem o viés probabilístico dela (aquela atração fatal pela média insossa e pelo clichê), mas eu tenho o viés das vozes da minha própria cabeça (com toda a dissonância cognitiva, rancores teóricos e certezas infundadas que acumulei pela vida). Nenhum dos dois sistemas é confiável sozinho.

A autoria não mora na digitação; mora no discernimento estético. Mora no papel de ser o árbitro desse confronto: na recusa obstinada, no mau humor de ler uma frase empolada e dizer "isso aqui tá uma bosta", e na decisão consciente sobre cada vírgula que tem permissão para ficar no texto final (ok, não tão extremo, mas às vezes acontece).

E isso vale para todos os tipos de conteúdo que eu produzo. O mesmo método sustenta desde posts técnicos com código até posts onde eu destilo meu ranço com alguma situação ou ferramenta. A máquina ajuda a manter consistência terminológica, a checar se um bloco de código conversa com o que foi explicado antes, a organizar uma sequência didática. A decisão final sobre o que discutir e o que defender continua sendo minha. A ferramenta muda, o papel de cada um na mesa não.

No fim das contas, continuamos dois cegos tateando a linguagem, talvez buscando significado onde parece só ter atrito ⁴. Mas a graça é que, batendo uma cegueira contra a outra com a dose certa de deboche e ceticismo, a gente consegue, pelo menos por alguns parágrafos, fazer o texto enxergar.

Referências

Na aula dos próximos dias, o passador de slides estará na minha mão. A plateia é a mesma turma que vem acompanhando os seminários da disciplina, e o desafio é passar pelos capítulos 19 e 23 do Russell e Norvig ¹, costurando com os fundamentos clássicos do livro de Sutton e Barto ² (que eu mesmo coloquei porque aparentemente não tenho amor à vida), sem parecer um papagaio recitando índices de livros ou um leitor de tela acelerado em duas vezes.

O perigo clássico desse tipo de apresentação é cair na tentação de colocar todas as fórmulas no slide para parecer erudito. O resultado disso todo mundo conhece: o apresentador se perde nos subscritos das matrizes, o tempo estoura no terceiro slide e ninguém na sala consegue pescar o fio da meada.

Para colocar ordem na minha própria cabeça e criar uma bússola de apresentação, organizei estas notas. Elas funcionam como o meu roteiro de estudo e reflexão: a história técnica de como ensinamos máquinas a reconhecer padrões em dados do passado e como damos autonomia para que elas aprendam a agir no futuro.

O desafio da síntese: escolher as brigas certas

Vinte minutos passam como um estalar de dedos quando você está falando em público. Se você gastar cinco minutos deduzindo uma regressão linear, faltará tempo para explicar por que o Q-Learning se diferencia do SARSA ou como o truque do kernel salvou as máquinas de vetores de suporte.

O segredo de uma apresentação curta não é correr com a fala, mas ter clareza absoluta sobre o papel de cada bloco:

1. A base conceitual: O que é indução estatística e por que o equilíbrio entre viés e variância governa tudo.
2. O cardápio supervisionado: Como árvores, modelos lineares, SVMs e comitês de modelos resolvem problemas com dados rotulados.
3. A virada para o reforço: Por que a supervisão direta falha em problemas sequenciais e como a interação com o ambiente substitui o professor.
4. O controle ótimo e a generalização: Como estimar utilidades no tempo e o que acontece quando colocamos redes neurais dentro do loop de decisão.

Com essa estrutura na cabeça, fica muito mais fácil cortar o excesso de detalhes sem perder a espinha dorsal do assunto.

O problema da indução: caçando funções no escuro

Todo aprendizado supervisionado parte de uma premissa simples: você tem um conjunto de treino com pares de entrada e saída (x_i, y_i). Alguma regra desconhecida da natureza gerou essas respostas, e o seu objetivo é encontrar uma função candidata h (a hipótese) que aproxime essa regra para qualquer dado que aparecer depois.

A primeira bifurcação clássica desse caminho:

• Classificação: O objetivo é prever uma categoria discreta (identificar se uma transação bancária é legítima ou fraude, se uma imagem contém um gato ou um cachorro).
• Regressão: O objetivo é prever um valor numérico contínuo (estimar o tempo de resposta de um servidor com base na carga, prever o consumo de memória de um processo).

Toda a matemática repousa sobre a suposição de estacionariedade (i.i.d.): assume-se que os dados futuros seguirão a mesma distribuição probabilística dos dados passados. No mundo real da infraestrutura e dos sistemas isso é uma meia-verdade constante (o tráfego muda, o perfil dos usuários evolui, o comportamento de ataque se transforma), mas sem essa âncora inicial, nenhum modelo consegue sair do lugar.

Viés contra variância: o equilíbrio entre a teimosia e o exagero

Qualquer modelo de aprendizado supervisionado vive sob a tensão de duas forças opostas:

• Viés (Bias): Representa a rigidez do modelo. Se o espaço de hipóteses for limitado demais (como insistir em passar uma linha reta sobre dados que descrevem uma curva acentuada), o modelo falha em capturar o padrão essencial. É o chamado underfitting.
• Variância: Representa a sensibilidade excessiva aos dados de treino. Se o modelo for flexível demais, ele passa a memorizar o ruído estatístico e as peculiaridades daquela amostra específica. Ele acerta tudo no treino, mas desaba diante de qualquer dado inédito. É o clássico overfitting.

A Navalha de Ockham entra aqui como princípio orientador: entre duas explicações que justificam igualmente bem as observações, a mais simples costuma ser a mais confiável para generalizar.

O papel das perdas e a geometria da regularização

Para calibrar os parâmetros de um modelo, usamos funções de perda. A perda quadrática (L2) penaliza desvios grandes com muito mais rigor, sendo a escolha natural quando assumimos ruído Gaussiano. A perda absoluta (L1) é mais estável na presença de dados discrepantes (outliers), pois não eleva os erros ao quadrado.

Para evitar que os pesos cresçam descontroladamente e gerem sobreajuste, aplicamos técnicas de regularização:

Custo = Perda nos Dados + lambda * Penalidade dos Pesos

A escolha da penalidade altera completamente a natureza do modelo:

• Regularização L1 (Lasso): Penaliza a magnitude absoluta dos coeficientes. Devido à sua geometria em formato de losango, cujos vértices coincidem com os eixos cartesianos, ela força vários coeficientes a se tornarem exatamente zero durante a otimização. Na prática, funciona como uma seleção automática de variáveis, descartando o que não tem relevância.
• Regularização L2 (Ridge): Penaliza o quadrado dos coeficientes. Com sua geometria esférica e suave, ela puxa todos os pesos para valores próximos de zero de maneira uniforme, mas raramente anula qualquer parâmetro por completo.

Quatro pilares do aprendizado supervisionado

Para cobrir a diversidade de abordagens nos vinte minutos, escolhi quatro famílias conceituais que mostram como a área evoluiu.

1. Árvores de decisão e a medida da desordem

Árvores de decisão organizam o espaço de busca como uma sequência hierárquica de testes condicionais. A grande vantagem é a interpretabilidade direta: cada caminho da raiz até a folha pode ser lido como uma regra lógica compreensível.

Para construir a árvore sem testar todas as combinações possíveis (o que seria computacionalmente inviável), usa-se uma estratégia gulosa guiada pela Entropia de Shannon, que mede a incerteza dos dados:

H(V) = - somatorio( P(v_k) * log2(P(v_k)) )

A cada nó, o algoritmo escolhe a variável que proporciona o maior Ganho de Informação (a maior redução líquida de incerteza após a divisão).

Como árvores profundas decoram os dados com facilidade, a poda é essencial. Parar o crescimento antes da hora (early stopping) é arriscado porque o algoritmo não enxerga interações complexas entre atributos (em um problema de porta lógica XOR, por exemplo, nenhum atributo sozinho parece informativo no primeiro corte). A melhor prática é deixar a árvore crescer por completo e aplicar a Poda Chi-quadrado (chi^2) retrospectivamente, eliminando nós cujas divisões não apresentem relevância estatística.

2. Modelos lineares: do Perceptron à Regressão Logística

A regressão linear busca o hiperplano que minimiza o erro quadrático médio em relação aos dados. Pode ser calculada de forma exata pela Equação Normal quando a matriz cabe na memória, ou otimizada iterativamente via Gradiente Descendente quando lidamos com grandes volumes de informação.

Na classificação, o Perceptron histórico utilizava um limiar rígido: se a combinação linear ultrapassasse zero, a resposta era 1; caso contrário, 0. A limitação é evidente: se os dados não forem perfeitamente separáveis por uma reta, o algoritmo nunca se estabiliza.

A Regressão Logística contorna essa fragilidade aplicando a função sigmoide sobre a saída linear:

h(x) = 1 / (1 + e^(-w . x))

Em vez de tomar uma decisão binária abrupta, o modelo entrega uma probabilidade contínua e bem calibrada entre 0 e 1. Por ser suave e derivável, sua superfície de custo permite uma otimização convexa e robusta mesmo quando as classes apresentam sobreposição natural.

3. Support Vector Machines (SVM) e o salto dimensional

O conceito central das Máquinas de Vetores de Suporte é a busca pela Margem Máxima: entre todos os hiperplanos capazes de separar duas classes, o algoritmo escolhe aquele que mantém a maior distância possível em relação aos pontos mais próximos de cada categoria.

Esses pontos críticos que determinam a fronteira são os vetores de suporte. Qualquer outro ponto distante da margem pode ser alterado ou removido do conjunto de dados sem afetar a decisão final.

Quando os dados não possuem separação linear no espaço original, entra em cena o Kernel Trick: uma formulação matemática fundamentada no Teorema de Mercer que calcula o produto escalar das amostras em um espaço de características de alta dimensão sem precisar projetar os dados explicitamente. É o equivalente a desembolar pontos misturados em uma mesa bidimensional elevando-os em diferentes alturas para conseguir passar um plano reto entre eles.

4. Métodos de Ensemble: a força da combinação

Nenhum modelo precisa carregar todo o peso da decisão sozinho. Os métodos de comitê combinam múltiplos aprendizes base para produzir estimativas mais robustas:

• Bagging: Treina instâncias do mesmo algoritmo em diferentes amostras aleatórias com reposição (bootstrapping) e agrega os votos por maioria ou média. Seu principal efeito é a redução drástica de variância em modelos instáveis.
• Random Forests: Sofistica o Bagging ao introduzir aleatoriedade também na escolha das variáveis avaliadas a cada divisão de nó (usando tipicamente a raiz quadrada do total de atributos). Isso quebra a correlação entre as árvores da floresta, gerando um conjunto muito mais diverso.
• Boosting (AdaBoost e Gradient Boosting): Opera de forma sequencial. Cada novo modelo é construído com foco prioritário nas instâncias que os modelos anteriores classificaram incorretamente. O Gradient Boosting refina essa ideia ajustando os novos modelos diretamente aos resíduos (o gradiente negativo da função de perda), reduzindo progressivamente o viés.

A fronteira: por que o aprendizado por reforço é diferente

Até este ponto, o paradigma foi sempre o mesmo: existia um conjunto de dados anotado, com entradas e respostas corretas fornecidas por um agente externo. O aprendizado supervisionado é essencialmente um processo de inferência passiva sobre amostras prévias.

O Aprendizado por Reforço (RL) quebra essa estrutura:

             ┌─────────────────────────┐
             │         Agente          │
             └───────────┬─────────────┘
                         │ Ação (A_t)
                         ▼
             ┌─────────────────────────┐
             │        Ambiente         │
             └───────────┬─────────────┘
                         │ Estado (S_t+1) e Recompensa (R_t+1)
                         ▼

Não há um professor dizendo qual era a ação ótima a cada instante. O agente interage ativamente com um mundo estocástico, toma decisões e recebe apenas sinais escalares de recompensa ou punição ao longo do tempo.

O problema central passa a ser a atribuição de crédito temporal: quando o agente alcança um resultado relevante após centenas de ações consecutivas, como determinar quais decisões intermediárias foram realmente determinantes para aquele desfecho?

Formalizamos esse ambiente através de um Processo de Decisão de Markov (MDP), definido pela quádrupla (S, A, P, R, gamma):

• S: Espaço de estados do ambiente.
• A: Conjunto de ações disponíveis.
• P(s' | s, a): Dinâmica de transição do mundo.
• R(s, a, s'): Função de recompensa imediata.
• gamma: Fator de desconto no tempo (entre 0 e 1), que pondera o valor de retornos futuros em relação a ganhos imediatos.

O objetivo do agente é encontrar uma política pi(s) que mapeie estados em ações de modo a maximizar o retorno acumulado esperado:

G_t = R_t+1 + gamma * R_t+2 + gamma^2 * R_t+3 + ...

RL Passivo: estimando valores no tempo

Antes de aprender a agir, o agente precisa aprender a avaliar a qualidade dos estados sob uma política fixa pi. A literatura clássica divide essa tarefa em três abordagens fundamentais:

Métodos de Avaliação de Políticas
├── Direct Utility Estimation (Monte Carlo puro, sem modelo, sem bootstrapping)
├── Adaptive Dynamic Programming (Model-based, aprende transições P, resolve Bellman)
└── Temporal-Difference TD(0) (Model-free, com bootstrapping local)

1. Direct Utility Estimation (Monte Carlo): O agente executa trajetórias completas até o estado terminal, soma os retornos observados a partir de cada estado e calcula médias amostrais. O problema é que essa abordagem trata cada estado de forma isolada, ignorando que o valor de um estado está estruturalmente amarrado ao valor de seus sucessores pelas equações de Bellman.
2. Adaptive Dynamic Programming (ADP): O agente adota uma postura model-based. Ele conta as frequências de transição observadas para construir uma estimativa explícita de P(s' | s, a) e resolve o sistema de equações de Bellman por programação dinâmica. É a abordagem com maior eficiência amostral, mas se torna computacionalmente intratável quando o número de estados cresce exponencialmente.
3. Temporal-Difference Learning (TD(0)): Proposto por Rich Sutton em 1988, o método TD une o melhor dos dois mundos. Ele dispensa o modelo de transição do ambiente e atualiza a estimativa de utilidade logo no passo seguinte:

U(s) <- U(s) + alpha * [ R + gamma * U(s') - U(s) ]

A mágica reside no conceito de bootstrapping: o algoritmo usa a sua própria estimativa do estado seguinte U(s') para atualizar a estimativa do estado anterior U(s), sem precisar esperar o final do episódio e sem precisar calcular matrizes de transição completas.

RL Ativo: o controle e o equilíbrio da exploração

Quando o agente precisa escolher ativamente as ações para maximizar o retorno, ele se depara imediatamente com o conflito entre Exploração e Explotação:

• Explotação (Exploitation): Escolher a ação que o agente atualmente acredita ser a melhor para garantir recompensas a curto prazo.
• Exploração (Exploration): Tomar ações com retornos incertos na tentativa de descobrir rotas e estratégias potencialmente superiores.

Um agente puramente guloso (greedy) costuma convergir para políticas medíocres: ele descobre um caminho razoável nas primeiras tentativas e passa a repeti-lo indefinidamente, sem jamais explorar caminhos vizinhos que poderiam ser ordens de magnitude melhores.

Para contornar isso, usamos estratégias como o epsilon-greedy, onde o agente escolhe a melhor ação com probabilidade 1 - epsilon e seleciona uma ação aleatória com probabilidade epsilon. Ao reduzir gradualmente o valor de epsilon ao longo do tempo, o sistema atende à condição de exploração infinita (GLIE), garantindo convergência para a política ótima.

Q-Learning contra SARSA: duas filosofias de controle

No controle livre de modelo (model-free), aprendemos a função de valor de ação Q(s, a), que representa o retorno esperado ao tomar a ação a no estado s. Dois algoritmos clássicos dominam essa categoria:

Q-Learning (Watkins, 1989 - Off-Policy):

Q(s, a) <- Q(s, a) + alpha * [ R + gamma * max_a'( Q(s', a') ) - Q(s, a) ]

SARSA (Rummery & Niranjan, 1994 - On-Policy):

Q(s, a) <- Q(s, a) + alpha * [ R + gamma * Q(s', a') - Q(s, a) ]

A distinção entre as duas fórmulas é sutil no índice, mas fundamental no comportamento:

• O Q-Learning atualiza a estimativa assumindo que a próxima ação será a melhor teoricamente possível (max_a' Q), independentemente da ação que o agente realmente venha a executar durante a fase exploratória. Por ser off-policy, ele aprende diretamente a política ótima, mas pode ser arriscado durante a fase de treino se o ambiente contiver armadilhas severas.
• O SARSA atualiza a estimativa utilizando a ação a' que foi efetivamente sorteada pela política do agente no passo seguinte. Sendo on-policy, ele leva em consideração os próprios desvios exploratórios. Em ambientes com penalidades catastróficas próximas da borda, o SARSA aprende uma rota mais conservadora e segura para evitar quedas acidentais.

A Tríade Mortal e a escalabilidade no mundo real

Em problemas reais de grande porte, o espaço de estados é infinito ou excessivamente vasto para caber em uma tabela de memória. A solução é usar aproximadores de função (como redes neurais) para estimar Q(s, a) a partir de vetores de características.

No livro canônico de Sutton e Barto, os autores destacam um alerta fundamental para a engenharia de sistemas de IA: a Tríade Mortal (The Deadly Triad). A combinação simultânea de três fatores pode tornar o treinamento matematicamente instável e levar à divergência:

1. Aproximação de funções: Uso de modelos não lineares parametrizados no lugar de representações tabulares.
2. Bootstrapping: Atualização de estimativas baseada em estimativas seguintes (como no TD e Q-Learning).
3. Treinamento Off-policy: Aprender sobre uma política enquanto os dados são coletados por outra política de exploração.

O marco do algoritmo Deep Q-Network (DQN) da DeepMind em 2015 foi justamente conseguir estabilizar essa tríade ao jogar títulos do Atari a partir de pixels puros. A solução central foi o mecanismo de Experience Replay: as transições observadas são armazenadas em um buffer de memória e o modelo é atualizado a partir de mini-lotes sorteados aleatoriamente, quebrando a correlação temporal dos dados e restaurando a estabilidade do aprendizado.

Roteiro cronometrado para a apresentação

Para garantir que os vinte minutos cubram toda essa trajetória sem atropelos, estruturei a apresentação nos seguintes marcos de tempo:

• [00:00 a 03:00] Fundamentos da Aprendizagem e Indução:
  • O problema de aproximar a função desconhecida f via hipótese h.
  • A fronteira entre classificação e regressão.
  • O dilema central de viés contra variância e a parcimônia da Navalha de Ockham.
  • O papel das funções de perda e o contraste geométrico entre regularização L1 (esparsidade) e L2 (suavização).
• [03:00 a 11:00] Quatro Pilares do Aprendizado Supervisionado:
  • Árvores de Decisão: Entropia de Shannon, ganho de informação e por que a poda Chi-quadrado é superior ao corte precoce em problemas como XOR.
  • Modelos Lineares: O Perceptron com limiar rígido versus a Regressão Logística com sigmoide contínua e probabilística.
  • Máquinas de Vetores de Suporte (SVM): O princípio da Margem Máxima, vetores de suporte e a projeção implícita do Kernel Trick.
  • Ensembles: A redução de variância com Bagging/Random Forests e a redução de viés com Boosting sequencial.
• [11:00 a 18:00] A Transição para o Aprendizado por Reforço:
  • A ausência de gabarito e a dinâmica de tentativa e erro nos Processos de Decisão de Markov.
  • O problema da atribuição de crédito em sequências longas de ação.
  • Avaliação passiva: o salto conceitual do Monte Carlo para o TD(0) com bootstrapping.
  • Controle ativo: o equilíbrio da exploração (epsilon-greedy) e o contraste entre o otimismo do Q-Learning e o realismo do SARSA.
  • A Tríade Mortal de Sutton & Barto e o papel do Experience Replay no DQN.
• [18:00 a 20:00] Síntese e Fechamento:
  • O arco evolutivo: da indução passiva de padrões estruturados para o controle autônomo em ambientes dinâmicos.
  • Conclusão aberta para a arguição da banca.

Considerações finais

Apresentar um panorama denso em uma janela curta de tempo é um exercício de foco naquilo que realmente importa. Não adianta tentar transformar vinte minutos em uma leitura apressada de enciclopédia; o objetivo é guiar a banca através das grandes ideias que moldaram o aprendizado de máquina nas últimas décadas.