Karpenter escala o EKS sem pré-dimensionar node groups, mostra repositório Terraform

Um repositório Terraform publicado por um AWS Community Builder mostra como trocar o Cluster Autoscaler pelo Karpenter no EKS: em vez de redimensionar node groups fixos, o controlador escolhe a instância mais barata para cada pod pendente.

O Cluster Autoscaler resolve escala de cluster redimensionando node groups que alguém já definiu antes: você escolhe o tipo de instância, o tamanho mínimo e máximo, e o autoscaler só soma ou subtrai réplicas daquele grupo. O problema aparece quando a carga de trabalho não é homogênea: para caber workloads diferentes, o arquiteto acaba criando vários node groups ou superdimensionando um único tipo de instância, pagando por capacidade ociosa a maior parte do tempo.

Um post publicado na DEV Community pela comunidade AWS Community Builders (autor ligado ao repositório chinmayto/terraform-aws-eks-karpenter) mostra a alternativa: o Karpenter observa pods que não conseguem ser agendados, calcula a combinação mais barata de instâncias EC2 que atende aos requests de CPU e memória, e lança exatamente essas instâncias. Não existe node group para dimensionar antes: existe um NodePool que descreve um menu de instâncias aceitáveis, e o controlador decide dentro desse menu.

Este texto segue o material da fonte, mas com o olhar de quem vai operar isso em produção: onde o Karpenter corta custo de verdade, o que ele exige de IAM e rede, e em que ponto a consolidação automática pode morder se não houver orçamento de disrupção definido.

O que você vai construir

O repositório da fonte sobe um cluster EKS completo em duas camadas. A camada Terraform cria a VPC, o control plane do EKS, um managed node group pequeno (dois t3.medium on-demand) que hospeda só os add-ons de sistema e o controlador do Karpenter, além de toda a parte de IAM, EKS Pod Identity e uma fila SQS ligada ao EventBridge para eventos de spot interruption.

A camada Kubernetes é só duas definições: um EC2NodeClass, que diz ao Karpenter qual AMI, qual IAM role e quais subnets usar, e um NodePool, que define a faixa de instâncias aceitável e a política de consolidação. Por cima disso roda um Deployment de demonstração (nodejs-app) que força pods para nós do Karpenter via nodeAffinity, só para dar ao controlador algo concreto para reagir.

O ponto central da arquitetura: o controlador do Karpenter roda fixo no managed node group, nunca nos nós que ele próprio cria. Isso evita o cenário em que o Karpenter decide consolidar (remover) o nó onde ele mesmo está rodando.

Pré-requisitos

Antes de reproduzir o laboratório, confira:

• Conta AWS com permissão para criar VPC, cluster EKS, IAM roles, EKS Pod Identity associations, fila SQS e regra no EventBridge (um usuário ou role com AdministratorAccess resolve em laboratório; em produção, vale restringir essas permissões a uma política específica para o laboratório em vez de usar acesso administrativo amplo).
• Terraform, em versão compatível com o módulo terraform-aws-modules/eks/aws usado, na versão ~> 21.0.
• kubectl compatível com Kubernetes 1.36, a versão do control plane criado no exemplo.
• Helm 3, usado internamente pelo recurso helm_release que instala o chart do Karpenter.
• AWS CLI v2 configurado com as credenciais da conta alvo.
• git, para clonar github.com/chinmayto/terraform-aws-eks-karpenter, o repositório linkado pela fonte.

Atenção ao custo: o control plane do EKS é cobrado por hora e não entra no Free Tier; some a isso as instâncias t3.medium do managed node group e qualquer instância c, m ou r que o Karpenter vier a lançar durante o teste.

Passo a passo

1. Provisionar a infraestrutura com Terraform.

cd infrastructure
terraform init
terraform plan
terraform apply

Esse apply cria a VPC, o cluster, o managed node group, as roles e a fila SQS do Karpenter, e já instala o controlador via Helm. Um null_resource.update_kubeconfig atualiza o kubeconfig local automaticamente.

2. Conferir as tags de descoberta que o Karpenter usa.

O Karpenter não recebe lista de subnets e security group em variável: ele descobre os dois por uma tag, karpenter.sh/discovery, cujo valor é o nome do cluster. O módulo Terraform já aplica isso nas subnets privadas e no security group dos nós:

private_subnet_tags = {
 "kubernetes.io/role/internal-elb" = "1"
 "kubernetes.io/cluster/${var.cluster_name}" = "shared"
 "karpenter.sh/discovery" = var.cluster_name
}

Só um security group na conta deve carregar essa tag; se dois carregarem, o Karpenter fica em dúvida sobre qual usar.

3. Confirmar onde o controlador vai morar.

O managed node group fica pequeno de propósito (dois t3.medium) e recebe um label que o Helm usa como nodeSelector para pinar o Karpenter ali:

eks_managed_node_groups = {
 EKS_Node_Group = {
 min_size = 1
 max_size = 3
 desired_size = 2
 instance_types = ["t3.medium"]
 capacity_type = "ON_DEMAND"
 labels = {
 "karpenter.sh/controller" = "true"
 }
 }
}

4. Instalar o controlador via Helm, apontando para a fila de interrupção.

resource "helm_release" "karpenter" {
 name = "karpenter"
 namespace = var.karpenter_namespace # kube-system
 repository = "oci://public.ecr.aws/karpenter"
 chart = "karpenter"
 version = var.karpenter_chart_version # 1.6.0

 values = [yamlencode({
 nodeSelector = { "karpenter.sh/controller" = "true" }
 settings = {
 clusterName = module.eks.cluster_name
 clusterEndpoint = module.eks.cluster_endpoint
 interruptionQueue = module.karpenter.queue_name
 }
 })]
}

O sub-módulo terraform-aws-modules/eks/aws//modules/karpenter cria a IAM role do controlador associada via EKS Pod Identity (sem IRSA/OIDC manual), a role e o instance profile dos nós, o access entry para os nós que o Karpenter lançar, e a fila SQS ligada ao EventBridge para eventos de spot e de saúde de instância.

5. Aplicar o EC2NodeClass e o NodePool.

apiVersion: karpenter.k8s.aws/v1
kind: EC2NodeClass
metadata:
 name: default
spec:
 amiSelectorTerms:
 - alias: al2023@latest
 role: CT-EKS-Cluster
 subnetSelectorTerms:
 - tags:
 karpenter.sh/discovery: CT-EKS-Cluster

apiVersion: karpenter.sh/v1
kind: NodePool
spec:
 template:
 spec:
 nodeClassRef:
 group: karpenter.k8s.aws
 name: default
 requirements:
 - key: karpenter.k8s.aws/instance-category
 operator: In
 values: ["c", "m", "r"]
 - key: karpenter.k8s.aws/instance-cpu
 operator: In
 values: ["4", "8", "16", "32"]
 - key: karpenter.sh/capacity-type
 operator: In
 values: ["on-demand"]
 limits:
 cpu: 1000
 disruption:
 consolidationPolicy: WhenEmptyOrUnderutilized
 consolidateAfter: 30s

kubectl apply -f k8s-manifests/karpenter/default-nodepool.yaml

O requirements é um menu, não uma escolha fixa: o Karpenter pode lançar qualquer instância c, m ou r com 4 a 32 vCPUs, Nitro, geração acima de 2. Quanto mais larga essa faixa, mais espaço o scheduler tem para achar a combinação mais barata que cabe no pod pendente. O limits.cpu: 1000 é o teto de segurança: o Karpenter nunca cria mais de 1000 vCPUs de nós a partir desse pool, não importa a demanda.

Testando

1. Confirmar que o controlador subiu no managed node group.

kubectl get pods -n kube-system -l app.kubernetes.io/name=karpenter

NAME READY STATUS RESTARTS AGE
karpenter-5cdc6cdd7c-bsb7h 1/1 Running 0 29m
karpenter-5cdc6cdd7c-hn55w 1/1 Running 0 29m

2. Subir o workload de demonstração.

kubectl apply -f k8s-manifests/karpenter/nodejs-app-scale.yaml

O Deployment nodejs-app, na imagem public.ecr.aws/n4o6g6h8/simple-nodejs-app-1:latest, usa nodeAffinity para só agendar em nós com o label karpenter.sh/nodepool (ou seja, nós que o Karpenter criou) e topologySpreadConstraints para espalhar réplicas entre hosts diferentes, forçando mais de um nó por escala.

3. Provocar um scale-up e acompanhar em três terminais.

kubectl logs -f -n kube-system -l app.kubernetes.io/name=karpenter
kubectl get nodes -l karpenter.sh/registered=true -w
kubectl get pods -n karpenter-demo -o wide -w

kubectl -n karpenter-demo scale deployment nodejs-app --replicas 15

No material da fonte, essa escala para 15 réplicas (de requests de 500m CPU e 256Mi cada) fez o Karpenter subir de um nó único (ip-10-0-20-105.ec2.internal) para nove nós registrados em pouco mais de um minuto, todos já rodando Kubernetes v1.36.5-eks-577a51e. Os pods aparecem distribuídos entre os novos nós assim que cada um fica Ready.

4. Provocar o scale-down e confirmar a consolidação.

kubectl -n karpenter-demo scale deployment nodejs-app --replicas 0

Com consolidationPolicy: WhenEmptyOrUnderutilized e consolidateAfter: 30s, o Karpenter espera meio minuto sem pods para justificar aquele nó e então o termina. É esse ciclo completo, de subir sob demanda e descer sozinho, que substitui o trabalho manual de redimensionar node group.

Limpando os recursos

A ordem importa: remova os workloads do Kubernetes antes de destruir o Terraform, para que o Karpenter desprovisione os nós que ele criou. Se você destruir o Terraform primeiro, as instâncias que o Karpenter lançou ficam órfãs, já que o Terraform nunca as gerenciou diretamente.

# 1. Remove o workload e deixa o Karpenter drenar os nós que ele criou
kubectl delete -f k8s-manifests/karpenter/nodejs-app-scale.yaml
kubectl delete -f k8s-manifests/karpenter/default-nodepool.yaml

# 2. Confirma que não sobrou nenhum nó provisionado pelo Karpenter
kubectl get nodes -l karpenter.sh/registered=true

# 3. Derruba a infraestrutura base (VPC, EKS, IAM, SQS)
terraform destroy

Se o passo 2 ainda listar nós, não rode o destroy: investigue por que o Karpenter não consolidou esses nós antes de apagar a infraestrutura por baixo deles.

Próximos passos

O exemplo da fonte usa só capacidade on-demand. Trocar karpenter.sh/capacity-type para incluir "spot" no NodePool é a extensão mais óbvia, e é exatamente aí que o Karpenter difere mais do Cluster Autoscaler: ele mistura on-demand e spot dentro do mesmo pool, escolhendo a opção mais barata que ainda cabe, enquanto o Cluster Autoscaler trata cada node group (on-demand ou spot) como unidade separada para redimensionar.

Dois cuidados para quem for levar isso a produção. Primeiro, o NodePool com requirements largas (como c, m, r de 4 a 32 vCPUs) dá liberdade ao Karpenter, mas também abre espaço para ele escolher uma família de instância que o time nunca tinha rodado antes; vale revisar se há cota de EC2 suficiente para todas elas. Segundo, consolidateAfter: 30s é agressivo: em cargas com tráfego em rajada, a oscilação de criar e matar nó a cada minuto tem custo de lançamento de instância e de reagendamento de pod, então ambientes de produção costumam usar uma janela maior ou orçamento de disrupção (disruption.budgets) para limitar quantos nós saem por vez.

Para quem já usa taints para isolar workloads de times diferentes, o próximo passo natural é criar múltiplos NodePool com weight distintos, cada um com seu próprio EC2NodeClass, taint e faixa de instâncias, deixando o Karpenter decidir entre eles pela prioridade configurada. O repositório da fonte (github.com/chinmayto/terraform-aws-eks-karpenter) e a documentação oficial de NodePools e NodeClasses do Karpenter são o ponto de partida para isso.

Fonte

DEV Community, AWS Community Builders: "Scaling an EKS Cluster with Karpenter".

Fonte: DEV Community — AWS Community Builders