Como corrigir erros na porta 10250 do kubelet

O que é a porta 10250

A porta 10250 é a API do kubelet, e todos os erros que a mencionam indicam um de dois problemas opostos. Ou já existe algo a utilizar a porta, pelo que kubeadm init se recusa a iniciar. Ou nada consegue alcançar a porta, pelo que kubectl logs e kubectl exec falham contra um node que, de resto, parece perfeitamente saudável.

O kubelet é o agente que o Kubernetes executa em cada node. Inicia contentores e comunica o respetivo estado ao control plane. Também escuta na porta TCP 10250 e disponibiliza uma API HTTPS que o control plane utiliza. O API server abre uma ligação a essa porta quando executa kubectl logs, kubectl exec, kubectl attach ou kubectl port-forward. O metrics-server consulta /metrics/resource na mesma porta, permitindo que kubectl top node funcione.

Essa API requer autenticação. O kubeadm desativa o acesso anónimo e configura o kubelet para utilizar a CA (certificate authority) do cluster. Assim, um pedido sem credenciais recebe Unauthorized, em vez de obter uma shell dentro de um dos seus contentores. Tenha este detalhe presente, porque também é a forma mais rápida de confirmar que a porta está acessível. Se as portas forem um conceito novo para si, o que é realmente uma porta no Linux explica o modelo assumido por este guia.

Ambos os modos de falha resultam do mesmo requisito. A porta 10250 tem de estar livre antes de o kubelet iniciar e acessível a partir do control plane depois de estar em execução.

Qual dos dois problemas ocorre

Execute estes comandos no nó em questão. Todos os comandos abaixo devem ser executados por si, no seu próprio servidor.

sudo ss -lntp | grep 10250
sudo systemctl status kubelet --no-pager

ss -lntp lista os sockets TCP em escuta e mostra o processo associado a cada um. -l significa que o socket está em escuta, -n mantém as portas no formato numérico, -t limita a saída a TCP e -p mostra o processo proprietário. Esse último sinalizador requer root. Caso contrário, a coluna do processo fica vazia e não é possível obter essa informação.

Uma linha terminada em users:(("kubelet",pid=1043,fd=23)) significa que o kubelet está em execução e mantém a porta ocupada. Se esperava que a porta estivesse livre, encontrou a causa. Se ss não apresentar qualquer saída e o control plane continuar sem conseguir contactar este nó, ainda não há uma firewall envolvida, porque nada está a servir a porta. Descubra por que motivo o kubelet está parado antes de alterar qualquer regra.

systemctl status kubelet mostra a outra parte do problema. active (running) com uma hora de início de há poucos minutos é normal. Um kubelet que reinicia a cada poucos segundos antes de executar kubeadm init ou kubeadm join também é normal: a unidade fornecida pelo pacote inicia durante a instalação, não encontra qualquer configuração e termina. A documentação upstream descreve este crash loop como comportamento esperado enquanto o kubelet aguarda que o kubeadm lhe indique o que fazer. Se o comportamento de reinício do systemd não lhe for familiar, como funcionam os tipos de serviço e as políticas de reinício do systemd fornece o contexto desta secção.

Por que a porta 10250 já está em uso quando kubeadm init é executado

kubeadm init executa verificações preliminares antes de gravar qualquer coisa no disco. Uma dessas verificações tenta associar cada porta de que o control plane precisa e é interrompida com um erro que identifica a porta 10250 quando essa associação falha. Isto não é um bug. O kubeadm recusa-se a criar um segundo cluster sobre os restos do primeiro.

Na prática, quatro situações causam este problema:

• Uma execução anterior de kubeadm init ou kubeadm join que falhou a meio. O kubelet já recebeu uma configuração, por isso está em execução e mantém a porta ocupada.
• Um kubeadm reset que foi iniciado mas não terminou. O reset para o kubelet, mas não desativa a unit, por isso o arranque seguinte volta a ativar o listener.
• O k3s ou outra distribuição Kubernetes instalada no mesmo servidor. O k3s inclui um kubelet, e esse kubelet também associa a porta 10250.
• O pacote kubelet instalado pelo apt e iniciado pela sua própria unit do systemd, num servidor onde ainda não executou o kubeadm.

Identifique a causa antes de alterar qualquer coisa:

sudo ss -lntp 'sport = :10250'
systemctl list-units --type=service --state=running | grep -Ei 'kubelet|k3s|k0s'

Se o listener pertencer ao k3s, pare e decida qual cluster pretende realmente utilizar. O k3s e o kubeadm não podem partilhar um servidor, porque usam as mesmas portas e o mesmo diretório CNI (container network interface). O instalador do k3s deixa um script de desinstalação em /usr/local/bin/k3s-uninstall.sh num nó de servidor e em k3s-agent-uninstall.sh num nó de agente.

Por que matar o kubelet não liberta a porta

sudo pkill kubelet liberta a porta 10250 durante cerca de dez segundos. A unidade fornecida pelo pacote define uma política de reinício, por isso o systemd inicia um novo kubelet, que volta a associar-se à mesma porta. Pode consultar a política diretamente:

systemctl show kubelet -p Restart -p RestartSec
sudo systemctl stop kubelet
sudo ss -lntp | grep 10250

Restart=always com RestartSec=10 é o que vem definido na unidade, e é exatamente por isso que kill parece funcionar e depois deixa de funcionar. systemctl stop é a forma correta de libertar a porta, porque o systemd deixa de reiniciar uma unidade que recebeu instruções para parar.

Uma porta livre ainda não é suficiente num node que contém metade de um cluster. /var/lib/kubelet/config.yaml, os certificados em /etc/kubernetes/pki e quaisquer manifestos de static pods em /etc/kubernetes/manifests continuam presentes. As verificações de preflight posteriores encontram esses ficheiros e falham, e ignorar as verificações à força deixa um cluster cujos certificados não correspondem à configuração. Faça o reset correto do node.

Redefinir o node de forma limpa

sudo kubeadm reset -f
sudo rm -rf /etc/cni/net.d
rm -rf $HOME/.kube
sudo systemctl stop kubelet
sudo ss -lntp | grep -E '10250|6443|2379'

-f ignora o pedido de confirmação. O reset tenta reverter o que init ou join fizeram. Remove os ficheiros e a configuração locais, remove o membro local do etcd num node do control plane, limpa os certificados em /etc/kubernetes/pki e remove a configuração e os manifests do kubelet.

A documentação especifica claramente o que o reset deixa para trás, e cada item pode causar problemas. Não limpa /etc/cni/net.d, por isso a configuração antiga do plugin CNI permanece e o novo cluster lê-a. Não limpa as regras de iptables, nftables ou IPVS que o kube-proxy aplicou ao host. Não altera $HOME/.kube, por isso kubectl continua a comunicar com um cluster que já não existe e devolve erros de certificado que parecem indicar um problema novo.

As regras de pacotes deixadas para trás são a parte mais difícil. Limpar as tabelas manualmente também remove as regras instaladas pelo ufw, porque o ufw no Ubuntu escreve através do mesmo backend. O servidor fica sem filtragem até executar sudo ufw reload. Num node que vai reconstruir de qualquer forma, faça reboot depois do reset. O reboot limpa as regras de runtime adicionadas pelo kube-proxy e demora menos tempo do que corrigir um conjunto de regras parcialmente limpo. Por que as regras de iptables e nftables aparecem na saída umas das outras explica o que acontece internamente.

O último comando ss deve não produzir qualquer saída. Sem nenhum listener nas portas 10250, 6443 ou 2379, o node está pronto para um novo kubeadm init.

Por que kubectl logs e kubectl exec atingem o tempo limite na porta 10250

Esta é a reclamação oposta e não se apresenta como um problema de porta. O cluster inicia. Os nós ficam Ready. Os pods executam. Depois, um comando falha:

Error from server: Get "https://10.0.0.12:10250/containerLogs/default/web-0/web": dial tcp 10.0.0.12:10250: i/o timeout

Leia essa mensagem a partir do fim. O API server tentou abrir uma ligação TCP ao nó na porta 10250 e não obteve resposta. i/o timeout significa que os pacotes foram descartados silenciosamente. Algo está a filtrá-los: a firewall do host no nó ou a firewall de rede separada do seu provedor, no painel de controlo. connect: connection refused na mesma posição significa o oposto. O pacote chegou e não havia nada a escutar, portanto o kubelet está parado. Este é o mesmo par de causas descrito em ligação recusada versus ligação que atinge o tempo limite, mas aqui numa porta diferente.

Os nós permanecem Ready durante tudo isto porque o estado dos nós segue na outra direção. O kubelet liga-se para fora ao API server na porta 6443 e envia o seu próprio heartbeat. Isso não exige ligações de entrada na porta 10250. Portanto, uma porta 10250 bloqueada permite que o cluster agende pods normalmente, mas faz falhar apenas logs, exec, port-forward e as métricas.

kubectl top node a responder error: Metrics API not available é a mesma falha observada através do metrics-server, cujo log indica o nó e a porta:

unable to fully scrape metrics from node worker-1: unable to fetch metrics from node worker-1: Get "https://10.0.0.12:10250/metrics/resource": dial tcp 10.0.0.12:10250: i/o timeout

Teste o caminho antes de editar qualquer regra de firewall

Execute isto a partir de um nó do control plane, usando o endereço do worker:

nc -zv 10.0.0.12 10250
curl -sk -o /dev/null -w '%{http_code}\n' https://10.0.0.12:10250/healthz

nc -z abre uma ligação, fecha-a e apresenta succeeded! quando a porta aceita a ligação. A linha com curl é o melhor teste, porque comprova que o kubelet está a servir pedidos, em vez de comprovar apenas que uma porta está aberta. Apresenta 401. Esse é o resultado esperado: o handshake TLS (transport layer security) foi concluído e, em seguida, o kubelet rejeitou um pedido não autenticado, exatamente como deve fazer. -k ignora a verificação do certificado, o que é adequado porque está a testar o caminho, não a cadeia de confiança.

Uma pausa longa que termina num timeout significa que os pacotes estão a ser descartados. curl: (7) Failed to connect devolvido imediatamente significa que a porta está fechada num host acessível. Faça o teste a partir do nó do control plane, não do seu portátil, porque o control plane é a única máquina cujo acesso é relevante neste caso.

Quais portas são necessárias em cada control plane e worker

Estas são as portas de entrada indicadas pelo upstream. Num nó control plane, abra a porta TCP 6443 para o API server, acessível a tudo o que executa kubectl. As portas TCP 2379 a 2380 são usadas pela API de cliente e pela API de pares do etcd, pelo API server e pelo próprio etcd. A porta TCP 10250 é usada pela API do kubelet, pelo próprio nó e pelo control plane. As portas TCP 10259, do kube-scheduler, e TCP 10257, do kube-controller-manager, são usadas apenas pelo próprio nó.

Num nó worker, a porta TCP 10250 é usada pela API do kubelet, pelo próprio nó e pelo control plane. A porta TCP 10256 é usada pelo kube-proxy, pelo próprio nó e pelos load balancers que executam verificações de estado. As portas TCP e UDP 30000 a 32767 são usadas pelos serviços NodePort. Esse é o intervalo predefinido e deve estar acessível a quem precisar desses serviços.

O seu plugin CNI acrescenta outras portas à lista. Essas portas não estão incluídas nela. O Flannel e o Calico no modo VXLAN precisam da porta UDP 4789 entre os nós. O Calico com BGP precisa da porta TCP 179. Consulte a documentação do seu plugin e abra essas portas entre os nós. Caso contrário, os pods em nós diferentes não comunicam entre si, mesmo que todas as portas desta secção estejam abertas.

Abrir a porta 10250 sem a expor à Internet

A API do kubelet pode iniciar um processo dentro de qualquer contentor nesse nó. Considere a porta 10250 aberta como acesso root ao nó e restrinja-a pelo endereço de origem. Nunca a permita a partir de qualquer origem.

sudo ufw allow from 10.0.0.0/24 to any port 10250 proto tcp comment 'kubelet API'
sudo ufw allow from 10.0.0.0/24 to any port 10256 proto tcp comment 'kube-proxy'
sudo ufw status numbered

Substitua 10.0.0.0/24 pela rede que os seus nós partilham. ufw status numbered lista as regras ativas com um índice, para que possa eliminar uma regra incorreta com sudo ufw delete <number>. Os conceitos básicos do ufw para um VPS explica as regras de ordenação que determinam qual das suas entradas é efetivamente aplicada.

Uma definição do ufw pode, por si só, interromper o funcionamento do Kubernetes. O tráfego dos pods que atravessa o nó é encaminhado, e não entregue localmente, e o ufw descarta os pacotes encaminhados por predefinição. Defina DEFAULT_FORWARD_POLICY="ACCEPT" em /etc/default/ufw e execute sudo ufw reload. Sem essa definição, a porta 10250 pode ficar totalmente aberta, enquanto o tráfego entre pods em nós diferentes continua a falhar.

Verifique também a firewall do seu fornecedor. A maioria dos painéis de VPS tem uma firewall ao nível da rede, colocada à frente do servidor e invisível para ufw status. Uma regra adicionada no nó não altera nada se o pacote nunca chegar ao servidor.

Quando a porta está acessível, mas o pedido continua a falhar

Algumas falhas na porta 10250 são devolvidas imediatamente em vez de ficarem pendentes. Isso indica que a ligação foi estabelecida, mas o pedido foi rejeitado. x509: certificate signed by unknown authority no log do metrics-server significa que o kubelet está a fornecer um certificado autoassinado que o scraper não considera fidedigno. As soluções habituais são ativar a rotação dos certificados de serviço do kubelet, para que a CA do cluster assine o certificado, e aprovar depois o pedido de assinatura do certificado. Num cluster de laboratório, também pode aceitar o risco e executar o metrics-server com --kubelet-insecure-tls.

Uma mensagem que contenha Forbidden juntamente com nodes/proxy ou nodes/metrics indica uma falha de RBAC (controlo de acesso baseado em funções). O chamador chegou ao kubelet. O kubelet perguntou ao API server se essa identidade podia utilizar o subrecurso, e a resposta foi negativa. Corrija o ClusterRole do chamador. Nenhuma alteração na firewall ajudará, porque nada foi bloqueado.

Se pretende apenas um cluster pequeno

Se encontrar estes erros ao configurar o kubeadm pela primeira vez num único VPS, avalie se precisa mesmo do kubeadm. Um cluster k3s de nó único num VPS fornece uma API Kubernetes funcional com um único comando, com o kubelet, o kube-proxy e uma CNI já integrados. A porta 10250 continua a existir, e aplicam-se as mesmas regras, mas deixa de ser necessário montar o control plane manualmente.

FAQ

Para que serve a porta 10250 no Kubernetes?

É a API HTTPS autenticada do kubelet em cada nó, tanto no control plane como nos workers. O API server liga-se a ela para kubectl logs, kubectl exec, kubectl attach e kubectl port-forward, e o metrics-server recolhe /metrics/resource nessa porta para fornecer kubectl top. O estado do nó não usa essa porta, porque o kubelet envia o heartbeat de saída para o API server na porta 6443. Por isso, um bloqueio da porta 10250 deixa os nós no estado Ready, enquanto os logs e o exec falham.

Como descubro o que está a escutar na porta 10250?

Execute sudo ss -lntp | grep 10250 no nó. O campo users:((...)) no fim da linha indica o processo e o respetivo PID. sudo é importante, porque, sem root, a coluna do processo fica vazia. Se o proprietário for o kubelet, sudo systemctl status kubelet --no-pager indica se é um kubelet saudável ou se está a reiniciar continuamente. Se o proprietário for o k3s, existem duas distribuições Kubernetes instaladas no mesmo servidor e terá de remover uma delas.

Tenho de abrir a porta 10250 na firewall?

Sim, entre os nós. O control plane tem de conseguir aceder à porta 10250 em todos os nós, incluindo no próprio control plane. Caso contrário, os logs, o exec, o port-forward e as métricas falham. Restrinja o acesso à rede partilhada pelos nós, por exemplo sudo ufw allow from 10.0.0.0/24 to any port 10250 proto tcp. Não abra a porta para a Internet: qualquer entidade que consiga autenticar-se nessa porta pode executar um processo em qualquer contentor do nó.

Porque falha kubectl logs apenas nos pods de um nó?

Porque o bloqueio é específico desse nó, e o API server liga-se ao nó que aloja o pod. Leia o texto do erro. Ele contém o endereço IP do nó ao qual o API server tentou ligar-se. Em seguida, execute nc -zv <node-ip> 10250 a partir de um nó do control plane. Um timeout indica um problema na firewall desse nó ou na firewall de rede do seu fornecedor. connection refused indica que o kubelet não está em execução nesse nó. Nesse caso, verifique systemctl status kubelet no próprio nó.