Limites do Kubernetes em produção: guia com valores verificáveis

Um cluster que funciona não é um cluster pronto para produção#

Existe uma ideia perigosa que se repete em muitos times: achar que um cluster está pronto porque "funciona". Funciona em staging, funciona com três serviços, funciona no dia da demo. Mas um cluster que funciona não é o mesmo que um cluster projetado para produção, e a diferença quase sempre está em um terreno que poucos revisam a tempo: os limites do Kubernetes.

O Kubernetes é flexível, mas não é infinito. Por trás de cada componente há tetos (do API server, do etcd, do kubelet, das regras de nomes) que raramente aparecem em um runbook interno e que se manifestam justamente quando o cluster cresce. O resultado típico: deploys que falham sem causa aparente, custos que sobem, troubleshooting sem fim e decisões de arquitetura que precisam ser refeitas sob pressão.

Este guia percorre os limites com mais impacto na operação real, explica de onde vem cada um e como monitorá-los. Todos os valores remetem à documentação oficial; quando um provedor gerenciado muda o número, nós indicamos.

Documentação: Kubernetes · Considerações para clusters grandes ↗

Por que os limites não são um detalhe técnico#

Os limites do Kubernetes não são curiosidade para entrevista: são restrições que condicionam a arquitetura do cluster desde o primeiro dia.

O exemplo mais conhecido: a documentação oficial indica que o Kubernetes foi projetado para configurações que atendam, ao mesmo tempo, a no máximo 110 pods por nó, 5.000 nós, 150.000 pods no total e 300.000 containers no total por cluster. Não são números arbitrários: eles marcam a faixa em que o projeto garante um comportamento previsível do control plane.

Quando um time se aproxima desses tetos ou os ignora, não recebe um erro claro dizendo "você passou do limite". O que costuma ver é latência crescente no API server, scheduling mais lento, addons reiniciando por falta de memória e um cluster cada vez mais difícil de operar. O limite não desaparece por você não conhecê-lo; ele se manifesta como incidente.

O mesmo vale para o armazenamento. O Kubernetes guarda todo o estado do cluster no etcd, e o etcd tem seus próprios limites: por padrão, o tamanho máximo de uma requisição é 1,5 MiB e a cota de armazenamento é de 2 GiB, com 8 GiB como máximo sugerido para ambientes normais. Se o etcd atinge a cota, ele para de aceitar escritas: não cai "só mais um serviço", a memória do cluster inteiro congela.

Documentação: Kubernetes · Considerações para clusters grandes ↗ · etcd · Limites do sistema ↗

Nem todos os limites vêm do mesmo lugar#

Um erro frequente é tratar todos os limites como se tivessem a mesma origem. Entender quem impõe cada um muda a forma de diagnosticar.

• API server. Secrets individuais são limitados a 1 MiB para evitar objetos enormes que esgotem a memória do API server e do kubelet; os dados de um ConfigMap também não podem passar de 1 MiB. Além disso, o total de anotações de um objeto (chaves e valores) não pode passar de 256 KiB.
• etcd. O teto de 1,5 MiB por requisição é do etcd e pode ser configurado com --max-request-bytes; a cota do banco de dados é ajustada com --quota-backend-bytes. Em serviços gerenciados, você não controla essas flags.
• Metadados e nomes. As chaves de labels e anotações têm um nome de até 63 caracteres e um prefixo opcional de até 253; os valores de labels, até 63. A maioria dos objetos, como os Pods, usa nomes de subdomínio DNS (até 253 caracteres), enquanto outros, como os Services, exigem rótulos DNS de no máximo 63 caracteres.
• Kubelet e nó. Aqui ficam valores operacionais como o período de tolerância de encerramento (30 segundos por padrão) e os limites de eviction padrão no Linux: memory.available<100Mi, nodefs.available<10 %, imagefs.available<15 % e nodefs.inodesFree<5 %. Ao cruzá-los, o kubelet começa a despejar pods.

Um caso real que confunde muitos times: aplicar com kubectl apply (client-side) um ConfigMap de, por exemplo, 400 KiB. Os dados estão abaixo de 1 MiB, mas o kubectl guarda uma cópia completa do manifesto na anotação kubectl.kubernetes.io/last-applied-configuration, e essa anotação ultrapassa o limite de 256 KiB. O erro menciona anotações, não o ConfigMap. A solução é usar server-side apply, que não depende dessa anotação, ou reduzir o objeto.

Parecem detalhes menores, mas um nome longo demais gerado por um chart do Helm ou uma anotação que cresce sem controle podem quebrar um operator ou uma automação inteira, e muitas vezes de forma intermitente, que é o pior jeito de falhar.

Documentação: Kubernetes · Secrets (limite de tamanho) ↗ · Kubernetes · ConfigMaps ↗ · Kubernetes · Annotations ↗ · Kubernetes · Labels e seletores ↗ · Kubernetes · Nomes e IDs de objetos ↗ · etcd · Limites do sistema ↗ · Kubernetes · Node-pressure eviction ↗ · Kubernetes · Ciclo de vida do Pod (encerramento) ↗ · Kubernetes · Gerenciamento declarativo com kubectl apply ↗ · Kubernetes · Server-Side Apply ↗

Tabela de referência rápida#

Valores padrão do projeto upstream e o componente que impõe cada limite. Alguns mudam conforme o provedor, a versão ou o plugin de rede, como você verá na próxima seção.

Documentação: Kubernetes · Considerações para clusters grandes ↗ · etcd · Limites do sistema ↗ · Kubernetes · Secrets (limite de tamanho) ↗ · Kubernetes · ConfigMaps ↗ · Kubernetes · Annotations ↗ · Kubernetes · Nomes e IDs de objetos ↗ · Kubernetes · Service (NodePort) ↗ · Kubernetes · Portas e protocolos ↗ · Kubernetes · Ciclo de vida do Pod (encerramento) ↗

Valores padrão não são valores recomendados#

Este talvez seja o mal-entendido mais caro. Um valor padrão ou um limite máximo é um teto, não uma recomendação para produção.

O limite de 1 MiB em Secrets e ConfigMaps ilustra bem isso. Tecnicamente você pode chegar perto desse teto, mas a própria documentação lembra que um ConfigMap não foi feito para guardar grandes blocos de dados e que muitos Secrets pequenos também podem esgotar a memória. Mantenha esses objetos o menor possível e, se precisar de mais, monte um volume ou use um serviço externo. O limite diz o que é possível; a boa prática diz o que é saudável.

O mesmo acontece com o etcd: 2 GiB é a cota padrão, mas operar um cluster grande exige planejar a compactação do histórico, a desfragmentação periódica para recuperar espaço e o monitoramento contínuo do tamanho do banco de dados. Sem isso, o banco cresce até a cota e o etcd passa para o modo somente leitura.

Documentação: Kubernetes · ConfigMaps ↗ · Kubernetes · Secrets (limite de tamanho) ↗ · etcd · Manutenção (compactação e desfragmentação) ↗

Alguns limites mudam no EKS, GKE e AKS#

Se o seu cluster roda em um serviço gerenciado, vários desses números não se aplicam da mesma forma que em um cluster autogerenciado. O caso mais claro é o de pods por nó:

• Amazon EKS: com a VPC CNI, cada pod recebe um IP da VPC, então o máximo depende das interfaces e endereços IP suportados pelo tipo de instância. Em managed node groups sem AMI personalizada, o EKS também aplica um teto de 110 pods em instâncias com menos de 30 vCPU e de 250 nas maiores.
• Google GKE: os clusters Standard usam 110 por padrão e podem ser configurados até 512 pods por nó; no Autopilot, o GKE escolhe um máximo entre 8 e 256 conforme a densidade esperada.
• Azure AKS: o máximo é 250 pods por nó, e o valor padrão varia conforme o plugin de rede e o método de deploy (CLI, template ARM ou portal).

A conclusão operacional é direta: não assuma que o número "oficial" é o do seu ambiente. Consulte a documentação do provedor, o tipo de instância e o plugin de rede que você usa, e verifique o valor real em cada nó. Afirmar que "o Kubernetes funciona igual em todo lugar" é exatamente o tipo de suposição que gera incidentes. Em serviços gerenciados você também não controla as flags do etcd, então vale conhecer as cotas publicadas pelo provedor.

# 1. Pods permitidos por nó (o que o seu provedor realmente configurou)
kubectl get nodes -o custom-columns=NODE:.metadata.name,MAX_PODS:.status.allocatable.pods

# 2. Pods agendados por nó, do maior para o menor
kubectl get pods -A -o jsonpath='{range .items[*]}{.spec.nodeName}{"\n"}{end}' \
  | sort | uniq -c | sort -rn | head

# 3. Maiores ConfigMaps (tamanho aproximado do objeto serializado)
kubectl get configmaps -A -o json \
  | jq -r '.items[] | "\(tojson | length)\t\(.metadata.namespace)/\(.metadata.name)"' \
  | sort -rn | head

# 4. Objetos grandes: aplique com server-side apply para não criar
#    a anotação last-applied-configuration
kubectl apply --server-side -f big-configmap.yaml

Para se aprofundar: Como fazer deploy de um serviço HTTP em containers na AWS

Documentação: Amazon EKS · Escolher tipo de instância e maxPods ↗ · Google Cloud · Máximo de Pods por nó no GKE ↗ · Microsoft Learn · Cotas e limites do AKS ↗ · Kubernetes · Server-Side Apply ↗

Boas práticas para times de DevOps e Platform Engineering#

Conhecer os limites é o primeiro passo. O segundo é construir uma operação que não dependa de cada engenheiro lembrar deles de cabeça.

• Documente os limites como padrão interno: pods por nó de cada pool, tamanho máximo aceito para Secrets e ConfigMaps, convenções de nomes e comportamento do etcd devem estar em um padrão de plataforma, não na cabeça de uma pessoa.
• Valide no CI/CD e na admissão, não em produção: a validação de manifestos no pipeline e políticas de admissão como ValidatingAdmissionPolicy podem barrar objetos grandes demais ou nomes inválidos antes do deploy.
• Use a observabilidade como alerta antecipado: monitore o tamanho do banco do etcd em relação à cota, os pods por nó e a latência do API server para saber quando você está se aproximando de um limite, e não quando já o cruzou.
• Trate a capacidade como variável explícita: decida pods por nó e nós por cluster com base em limites reais, incluindo os do provedor, e não no crescimento acidental.
• Mantenha os objetos pequenos: Secrets, ConfigMaps e anotações leves reduzem a carga sobre o etcd e o API server, e deixam o cluster mais estável e mais barato de operar.

groups:
  - name: kubernetes-limits
    rules:
      # etcd autogerenciado: alerta antes de atingir a cota do banco de dados
      - alert: EtcdDatabaseNearQuota
        expr: etcd_mvcc_db_total_size_in_bytes / etcd_server_quota_backend_bytes > 0.8
        for: 15m
        labels:
          severity: warning
      # Latência p99 do API server por verbo (exclui WATCH e CONNECT, que são longos)
      - alert: KubeAPIServerHighLatency
        expr: |
          histogram_quantile(0.99,
            sum by (le, verb) (
              rate(apiserver_request_duration_seconds_bucket{verb!~"WATCH|CONNECT"}[5m])
            )
          ) > 1
        for: 10m
        labels:
          severity: warning

É exatamente isso que uma prática madura de Platform Engineering oferece: transformar conhecimento disperso em padrões, automação e guardrails que escalam com o time.

Documentação: Kubernetes · Validating Admission Policy ↗ · Kubernetes · Referência de métricas ↗ · etcd · Manutenção (compactação e desfragmentação) ↗

Conclusão#

A maturidade com Kubernetes não se mede por quantos workloads você faz deploy, mas por quão bem você entende o comportamento do cluster sob carga. Os limites de pods, etcd, Secrets, nomes e kubelet não são obstáculos: são a informação que permite projetar para escalar em vez de improvisar e corrigir.

Um cluster preparado para produção é aquele em que os limites são entendidos, conferidos com o provedor, monitorados e traduzidos em padrões operacionais. Todo o resto é uma falha esperando a sua hora.