![\"Mascote](\"\/wp-content\/uploads\/2026\/09\/metallb-v1.webp\")
<\/p>\n<\/p>\n
Crie um Service do tipo <\/p>\n Num cluster bare metal sem MetalLB, o sintoma \u00e9 este:<\/p>\n Sem um balanceador, sobram duas sa\u00eddas ruins. O MetalLB<\/a> \u00e9 uma implementa\u00e7\u00e3o de balanceador de carga de rede para clusters Kubernetes bare metal, escrita em Go, sob licen\u00e7a Apache 2.0<\/strong>. O reposit\u00f3rio existe desde 2017, tem cerca de 8,4 mil estrelas e o projeto \u00e9 sandbox<\/em> da Cloud Native Computing Foundation. A API ainda \u00e9 marcada como beta, mas a pr\u00f3pria documenta\u00e7\u00e3o afirma que o MetalLB \u00e9 est\u00e1vel e confi\u00e1vel em produ\u00e7\u00e3o. Se voc\u00ea quer entender de onde vem o modelo de Services e controladores, veja a hist\u00f3ria do Kubernetes<\/a>.<\/p>\n Ele faz duas coisas que trabalham juntas:<\/p>\n Depois que o pacote chega ao n\u00f3, o trabalho do MetalLB acabou. Dali em diante quem encaminha at\u00e9 o pod \u00e9 o Em nuvem p\u00fablica, a maioria dos provedores n\u00e3o funciona com o MetalLB, porque a rede virtual n\u00e3o aceita IPs anunciados pela VM. A p\u00e1gina de compatibilidade com nuvens<\/a> detalha cada caso. No OpenStack funciona, desde que voc\u00ea libere os IPs na prote\u00e7\u00e3o antispoofing da porta.<\/p>\n No modo Layer 2, um \u00fanico n\u00f3 do cluster \u00e9 eleito “dono” de cada IP de servi\u00e7o. Quando algu\u00e9m na rede pergunta via ARP quem tem aquele IP, o Isso tem duas consequ\u00eancias que voc\u00ea precisa conhecer:<\/p>\n A elei\u00e7\u00e3o do l\u00edder n\u00e3o guarda estado: cada Quem conhece o Keepalived vai achar familiar: do ponto de vista do cliente, o IP “pula” de uma m\u00e1quina para outra. A diferen\u00e7a \u00e9 que o MetalLB n\u00e3o usa VRRP, e sim o memberlist. Por isso n\u00e3o existe o limite de 255 roteadores virtuais por rede nem IDs de roteador virtual para configurar. Em compensa\u00e7\u00e3o, ele n\u00e3o conversa com equipamentos VRRP de terceiros.<\/p>\n No modo BGP, cada n\u00f3 fecha uma sess\u00e3o BGP com os roteadores da sua rede e anuncia o IP de cada servi\u00e7o como uma rota A divis\u00e3o \u00e9 por conex\u00e3o<\/strong>, com hash de campos do pacote: todos os pacotes de uma conex\u00e3o TCP v\u00e3o para o mesmo n\u00f3. Hash de 5 campos (protocolo, IPs e portas de origem e destino) espalha melhor do que o de 3, porque separa conex\u00f5es diferentes do mesmo cliente.<\/p>\n A limita\u00e7\u00e3o principal: quando o conjunto de n\u00f3s muda, por exemplo porque um n\u00f3 caiu, o roteador recalcula o hash e a maioria das conex\u00f5es ativas vai parar em outro n\u00f3, que n\u00e3o conhece aquela conex\u00e3o. O cliente recebe connection reset<\/em>. \u00c9 um corte \u00fanico, n\u00e3o perda cont\u00ednua. Para suavizar, a documenta\u00e7\u00e3o sugere ECMP “resiliente” no roteador, deixar um Ingress Controller entre o BGP e os servi\u00e7os, e fazer mudan\u00e7as em hor\u00e1rio de pouco tr\u00e1fego.<\/p>\n O MetalLB tem tr\u00eas implementa\u00e7\u00f5es de BGP, e a v0.16.0<\/strong>, de 20 de maio de 2026, mudou qual delas \u00e9 a padr\u00e3o:<\/p>\n Para reproduzir tudo sem mexer em produ\u00e7\u00e3o, usamos o kind<\/a>, que sobe n\u00f3s Kubernetes como cont\u00eaineres Docker. As vers\u00f5es do teste foram kind 0.33.0, Kubernetes 1.37.0 e MetalLB 0.16.1.<\/p>\n O \u00faltimo comando mostra a sub-rede da rede Armadilha do kind:<\/strong> se algum pod entrar em Se o seu O manifesto recomendado inclui o backend FRR-K8s:<\/p>\n Para uma instala\u00e7\u00e3o mais enxuta, sem FRR, troque por O chart 0.16.1 tamb\u00e9m instala o FRR-K8s por padr\u00e3o. Para usar o backend nativo, passe Quem vem de vers\u00f5es antigas: at\u00e9 a v0.12 a configura\u00e7\u00e3o era um ConfigMap. Desde a v0.13 s\u00f3 existem os recursos customizados (CRDs) mostrados abaixo, e h\u00e1 uma ferramenta de convers\u00e3o<\/a>.<\/p>\n S\u00e3o dois recursos: o pool de endere\u00e7os e o an\u00fancio em Layer 2 que aponta para ele.<\/p>\n Os endere\u00e7os aceitam faixas ( O Service que estava em No laborat\u00f3rio, derrubamos o n\u00f3 l\u00edder com Um detalhe de teste: Por padr\u00e3o, qualquer n\u00f3 com Para o teste de BGP, recriamos o cluster com dois n\u00f3s (o control-plane, No diret\u00f3rio Do lado do MetalLB, s\u00e3o tr\u00eas recursos: o par BGP, o pool e o an\u00fancio.<\/p>\n Use No roteador, as sess\u00f5es sobem e a rota aparece com dois pr\u00f3ximos saltos:<\/p>\n Para ver o que cada n\u00f3 pretende anunciar, sem entrar no roteador:<\/p>\n O BGP sozinho pode levar dezenas de segundos para perceber um vizinho morto. Nos backends FRR, d\u00e1 para acoplar uma sess\u00e3o BFD ao par:<\/p>\nLoadBalancer<\/code> num cluster Kubernetes na AWS ou no Google Cloud e, em segundos, ele ganha um IP externo. Fa\u00e7a o mesmo num cluster em servidores pr\u00f3prios e o EXTERNAL-IP<\/code> fica em <pending><\/code> para sempre. O Kubernetes n\u00e3o traz um balanceador de carga de rede para bare metal: as implementa\u00e7\u00f5es que acompanham o projeto s\u00f3 conversam com as nuvens. O MetalLB<\/strong> preenche esse buraco. Ele distribui IPs de um pool que voc\u00ea define e anuncia esses IPs na rede com protocolos padr\u00e3o, ARP\/NDP ou BGP. Neste guia, voc\u00ea vai entender como ele funciona, instalar a vers\u00e3o 0.16.1, configurar os modos Layer 2 e BGP e resolver os problemas mais comuns. Todos os comandos foram testados num laborat\u00f3rio com kind e um roteador FRR.<\/p>\nO problema: LoadBalancer em <pending><\/h2>\n
kubectl create deployment nginx --image=nginx:1.29 --replicas=2\nkubectl expose deployment nginx --type=LoadBalancer --port=80\nkubectl get svc nginx<\/code><\/pre>\nNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE\nnginx LoadBalancer 10.96.187.200 <pending> 80:32251\/TCP 5s<\/code><\/pre>\nNodePort<\/code> exp\u00f5e o servi\u00e7o numa porta alta (30000 a 32767) de todos os n\u00f3s, e o cliente precisa saber o IP de um n\u00f3 que esteja de p\u00e9. externalIPs<\/code> depende de voc\u00ea rotear o IP manualmente at\u00e9 algum n\u00f3. A documenta\u00e7\u00e3o do MetalLB<\/a> resume: essas op\u00e7\u00f5es transformam o bare metal em cidad\u00e3o de segunda classe no Kubernetes.<\/p>\nO que \u00e9 o MetalLB<\/h2>\n
\n
controller<\/code>, um Deployment \u00fanico no cluster, pega um IP livre de um IPAddressPool<\/code> e grava no Service. Ele n\u00e3o inventa IPs: s\u00f3 entrega os que voc\u00ea colocou nos pools, sejam p\u00fablicos alugados do seu datacenter ou privados da sua LAN.<\/li>\nspeaker<\/code>, um DaemonSet que roda em cada n\u00f3, faz a rede fora do cluster saber que aquele IP “mora” no cluster. Em modo Layer 2 ele responde ARP (IPv4) e NDP (IPv6); em modo BGP ele fecha sess\u00f5es com seus roteadores e anuncia rotas.<\/li>\n<\/ul>\nkube-proxy<\/code> e o plugin de rede (CNI) do cluster.<\/p>\nRequisitos<\/h3>\n
\n
Modo Layer 2: simples e universal<\/h2>\n
speaker<\/code> desse n\u00f3 responde com o MAC da pr\u00f3pria interface. Para a LAN, parece apenas que a m\u00e1quina tem v\u00e1rios IPs. Funciona em qualquer rede Ethernet, sem equipamento especial.<\/p>\n![\"Diagrama](\"\/wp-content\/uploads\/2026\/09\/metallb-modo-l2.webp\")
<\/p>\n\n
speaker<\/code> calcula, para cada IP, uma lista ordenada pelo hash de “n\u00f3 + IP” entre os n\u00f3s eleg\u00edveis, e quem estiver em primeiro anuncia. Adicionar um n\u00f3 s\u00f3 muda o l\u00edder se o novo n\u00f3 cair no topo da lista; remover um n\u00f3 que n\u00e3o \u00e9 l\u00edder n\u00e3o muda nada.<\/p>\nModo BGP: balanceamento de verdade<\/h2>\n
\/32<\/code>. Se o roteador estiver configurado para m\u00faltiplos caminhos (ECMP), ele trata todos os n\u00f3s como pr\u00f3ximos saltos equivalentes e divide as conex\u00f5es entre eles.<\/p>\n![\"Diagrama](\"\/wp-content\/uploads\/2026\/09\/metallb-modo-bgp.webp\")
<\/p>\nOs tr\u00eas backends de BGP<\/h3>\n
\n
Laborat\u00f3rio: kind com tr\u00eas n\u00f3s<\/h2>\n
cat > kind.yaml <<'EOF'\nkind: Cluster\napiVersion: kind.x-k8s.io\/v1alpha4\nname: metallb-lab\nnodes:\n- role: control-plane\n- role: worker\n- role: worker\nEOF\nkind create cluster --config kind.yaml\ndocker network inspect kind -f '{{range .IPAM.Config}}{{.Subnet}} {{end}}'<\/code><\/pre>\nkind<\/code> no Docker, que faz o papel da sua LAN. No nosso caso foi 192.168.32.0\/20<\/code>, e reservamos o trecho 192.168.47.200-192.168.47.250<\/code> para o MetalLB. Na sua rede real, escolha uma faixa fora do DHCP e que nenhum equipamento use.<\/p>\nCrashLoopBackOff<\/code> com too many open files<\/code> no log, o problema \u00e9 o limite de inotify do host, n\u00e3o o MetalLB. Aumente com sudo sysctl fs.inotify.max_user_instances=512<\/code>, como recomenda a documenta\u00e7\u00e3o do kind. Aconteceu no nosso teste com tr\u00eas n\u00f3s num host que j\u00e1 rodava v\u00e1rios cont\u00eaineres.<\/p>\nInstala\u00e7\u00e3o<\/h2>\n
Prepara\u00e7\u00e3o: kube-proxy em modo IPVS<\/h3>\n
kube-proxy<\/code> roda em modo IPVS, ative o strictARP<\/code>; sem ele, os n\u00f3s respondem ARP de IPs que n\u00e3o deveriam. Em modo iptables (o padr\u00e3o do kubeadm e do kind), pule este passo.<\/p>\nkubectl get configmap kube-proxy -n kube-system -o yaml | \\\n sed -e \"s\/strictARP: false\/strictARP: true\/\" | \\\n kubectl apply -f - -n kube-system<\/code><\/pre>\nPor manifesto<\/h3>\n
kubectl apply -f https:\/\/raw.githubusercontent.com\/metallb\/metallb\/v0.16.1\/config\/manifests\/metallb-frr-k8s.yaml\nkubectl wait -n metallb-system --for=condition=ready pod --all --timeout=240s\nkubectl get pods -n metallb-system<\/code><\/pre>\nNAME READY STATUS RESTARTS AGE\ncontroller-75db68c68f-69tsz 1\/1 Running 0 2m\nfrr-k8s-daemon-fvd4w 5\/5 Running 0 2m\nfrr-k8s-daemon-rdc2p 5\/5 Running 0 2m\nfrr-k8s-statuscleaner-867ddf64df-h9rzt 1\/1 Running 0 2m\nspeaker-kqhsl 1\/1 Running 0 2m\nspeaker-mk2jq 1\/1 Running 0 2m<\/code><\/pre>\nmetallb-native.yaml<\/code> na mesma URL. O manifesto j\u00e1 cria o namespace metallb-system<\/code> com os r\u00f3tulos pod-security.kubernetes.io\/*: privileged<\/code>, necess\u00e1rios porque o speaker<\/code> precisa de privil\u00e9gios de rede. Rec\u00e9m-instalado, o MetalLB fica parado: nada acontece at\u00e9 voc\u00ea criar a configura\u00e7\u00e3o.<\/p>\nPor Helm<\/h3>\n
kubectl create namespace metallb-system\nkubectl label namespace metallb-system \\\n pod-security.kubernetes.io\/enforce=privileged \\\n pod-security.kubernetes.io\/audit=privileged \\\n pod-security.kubernetes.io\/warn=privileged\nhelm repo add metallb https:\/\/metallb.github.io\/metallb\nhelm install metallb metallb\/metallb --namespace metallb-system<\/code><\/pre>\n--set speaker.frr.enabled=false --set frrk8s.enabled=false<\/code>. Com Helm, os recursos de configura\u00e7\u00e3o precisam ficar no mesmo namespace em que o MetalLB foi instalado.<\/p>\nConfigurando o modo Layer 2<\/h2>\n
apiVersion: metallb.io\/v1beta1\nkind: IPAddressPool\nmetadata:\n name: lan\n namespace: metallb-system\nspec:\n addresses:\n - 192.168.47.200-192.168.47.250\n---\napiVersion: metallb.io\/v1beta1\nkind: L2Advertisement\nmetadata:\n name: lan\n namespace: metallb-system\nspec:\n ipAddressPools:\n - lan<\/code><\/pre>\ninicio-fim<\/code>), CIDR (192.168.10.0\/24<\/code>) e IPv6, e voc\u00ea pode ter quantos pools quiser. Um L2Advertisement<\/code> sem ipAddressPools<\/code> vale para todos os pools. Sem nenhum L2Advertisement, o IP \u00e9 atribu\u00eddo mas n\u00e3o \u00e9 anunciado<\/strong>, e o servi\u00e7o n\u00e3o responde; \u00e9 o erro mais comum de quem vem das vers\u00f5es com ConfigMap.<\/p>\nkubectl apply -f l2.yaml\nkubectl get svc nginx\ncurl -s -o \/dev\/null -w '%{http_code}\\n' http:\/\/192.168.47.200\/\nkubectl describe svc nginx | sed -n '\/Events\/,$p'<\/code><\/pre>\nNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE\nnginx LoadBalancer 10.96.187.200 192.168.47.200 80:32251\/TCP 4m45s\n200\nEvents:\n Type Reason Age From Message\n ---- ------ ---- ---- -------\n Normal IPAllocated 5s metallb-controller Assigned IP [\"192.168.47.200\"]\n Normal nodeAssigned 5s metallb-speaker announcing from node \"metallb-lab-worker2\" with protocol \"layer2\"<\/code><\/pre>\n<pending><\/code> ganhou o IP na hora. Os eventos mostram as duas etapas: o controller<\/code> atribuiu o IP e o speaker<\/code> do worker2<\/code> passou a anunci\u00e1-lo. Para ver qual n\u00f3 anuncia cada servi\u00e7o sem ler eventos:<\/p>\nkubectl get servicel2statuses -n metallb-system<\/code><\/pre>\nNAME ALLOCATED NODE SERVICE NAME SERVICE NAMESPACE\nl2-vc27l metallb-lab-worker2 nginx default<\/code><\/pre>\nTestando o failover<\/h3>\n
docker stop<\/code> enquanto um la\u00e7o de curl<\/code> batia no IP a cada meio segundo. O servi\u00e7o voltou a responder em cerca de 6,3 segundos<\/strong>, e a tabela ARP do host trocou sozinha para o MAC do outro worker:<\/p>\nip neigh show 192.168.47.200<\/code><\/pre>\n# antes: MAC do worker2\n192.168.47.200 dev br-a312a0b87cf9 lladdr a2:7a:02:df:0c:57 REACHABLE\n# depois: MAC do worker\n192.168.47.200 dev br-a312a0b87cf9 lladdr c2:00:6c:c6:41:63 DELAY<\/code><\/pre>\ndocker pause<\/code> n\u00e3o serve para simular a queda, porque o kernel do n\u00f3 pausado continua encaminhando pacotes e o servi\u00e7o nem pisca. Use docker stop<\/code>, ou desligue a m\u00e1quina de verdade.<\/p>\nLimitando n\u00f3s, interfaces e servi\u00e7os<\/h3>\n
speaker<\/code> pode ser eleito, e o an\u00fancio sai por todas as interfaces. Quando s\u00f3 alguns n\u00f3s est\u00e3o ligados a uma rede, restrinja:<\/p>\napiVersion: metallb.io\/v1beta1\nkind: L2Advertisement\nmetadata:\n name: dmz\n namespace: metallb-system\nspec:\n ipAddressPools:\n - dmz\n nodeSelectors:\n - matchLabels:\n rede: dmz\n interfaces:\n - eth1\n serviceSelectors:\n - matchLabels:\n tier: frontend<\/code><\/pre>\nserviceSelectors<\/code> chegou na v0.16.0 e limita o an\u00fancio aos Services com aqueles r\u00f3tulos. Cuidado com interfaces<\/code>: ele n\u00e3o influencia a elei\u00e7\u00e3o do l\u00edder. Se o n\u00f3 eleito n\u00e3o tiver a interface, o servi\u00e7o n\u00e3o \u00e9 anunciado; combine sempre com nodeSelectors<\/code>.<\/p>\nConfigurando o modo BGP<\/h2>\n
192.168.32.2<\/code>, e um worker, 192.168.32.3<\/code>) e subimos um roteador FRR<\/a> 10.7.1 em cont\u00eainer, na mesma rede do kind, com o AS 64501:<\/p>\ndocker run -d --name metallb-lab-router --network kind --ip 192.168.40.10 \\\n --privileged -v \"$PWD\/router:\/etc\/frr\" quay.io\/frrouting\/frr:10.7.1<\/code><\/pre>\nrouter\/<\/code> ficam o arquivo daemons<\/code>, com bgpd=yes<\/code>, e o frr.conf<\/code> com a configura\u00e7\u00e3o do roteador:<\/p>\nrouter bgp 64501\n bgp router-id 192.168.40.10\n no bgp ebgp-requires-policy\n neighbor 192.168.32.2 remote-as 64500\n neighbor 192.168.32.3 remote-as 64500\n !\n address-family ipv4 unicast\n maximum-paths 8\n exit-address-family<\/code><\/pre>\nmaximum-paths<\/code> \u00e9 o que liga o ECMP: sem ele, o roteador escolhe um \u00fanico n\u00f3. no bgp ebgp-requires-policy<\/code> \u00e9 necess\u00e1rio no FRR para aceitar rotas eBGP sem pol\u00edtica expl\u00edcita; num roteador de produ\u00e7\u00e3o, prefira filtros de prefixo que aceitem s\u00f3 o seu pool.<\/p>\napiVersion: metallb.io\/v1beta2\nkind: BGPPeer\nmetadata:\n name: roteador\n namespace: metallb-system\nspec:\n myASN: 64500\n peerASN: 64501\n peerAddress: 192.168.40.10\n---\napiVersion: metallb.io\/v1beta1\nkind: IPAddressPool\nmetadata:\n name: bgp\n namespace: metallb-system\nspec:\n addresses:\n - 10.200.0.0\/24\n avoidBuggyIPs: true\n---\napiVersion: metallb.io\/v1beta1\nkind: BGPAdvertisement\nmetadata:\n name: bgp\n namespace: metallb-system\nspec:\n ipAddressPools:\n - bgp<\/code><\/pre>\nmetallb.io\/v1beta2<\/code> no BGPPeer<\/code>; a v1beta1<\/code> est\u00e1 obsoleta. O avoidBuggyIPs<\/code> n\u00e3o est\u00e1 a\u00ed por acaso: sem ele, o primeiro Service do nosso teste recebeu 10.200.0.0<\/code>, e alguns equipamentos antigos descartam endere\u00e7os terminados em .0<\/code> e .255<\/code>. Com a op\u00e7\u00e3o ligada, o Service passou a receber 10.200.0.1<\/code>.<\/p>\ndocker exec metallb-lab-router vtysh -c \"show bgp summary\"\ndocker exec metallb-lab-router vtysh -c \"show ip route bgp\"<\/code><\/pre>\nNeighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up\/Down State\/PfxRcd PfxSnt\n192.168.32.2 4 64500 4 6 1 0 0 00:00:15 1 1\n192.168.32.3 4 64500 7 6 1 0 0 00:00:15 1 1\n\nB>* 10.200.0.1\/32 [20\/0] via 192.168.32.2, eth0, weight 1, 00:00:09\n * via 192.168.32.3, eth0, weight 1, 00:00:09<\/code><\/pre>\nkubectl get servicebgpstatuses -n metallb-system<\/code><\/pre>\nBFD para detectar falhas mais r\u00e1pido<\/h3>\n
apiVersion: metallb.io\/v1beta1\nkind: BFDProfile\nmetadata:\n name: rapido\n namespace: metallb-system\nspec:\n receiveInterval: 380\n transmitInterval: 270\n---\napiVersion: metallb.io\/v1beta2\nkind: BGPPeer\nmetadata:\n name: roteador\n namespace: metallb-system\nspec:\n myASN: 64500\n peerASN: 64501\n peerAddress: 192.168.40.10\n bfdProfile: rapido<\/code><\/pre>\n