Como configurar observabilidade básica num cluster Kubernetes do zero

1. Fundamentos da Observabilidade no Kubernetes

Observabilidade é a capacidade de entender o estado interno de um sistema a partir dos dados que ele produz externamente. Em ambientes Kubernetes, onde dezenas ou centenas de contêineres são orquestrados dinamicamente, essa capacidade não é opcional — é requisito fundamental para operação confiável.

Os três pilares da observabilidade são:

  • Métricas: dados numéricos coletados em intervalos regulares (uso de CPU, memória, latência de requisições)
  • Logs: registros textuais de eventos ocorridos nos componentes do sistema
  • Tracing: rastreamento do fluxo de requisições através de múltiplos serviços

Para este guia prático, focaremos em métricas e logs, que formam a base mínima para qualquer operação de cluster Kubernetes.

Diferente do monitoramento tradicional (que pergunta "o sistema está no ar?"), a observabilidade permite perguntar "por que o sistema está se comportando desta forma?" — uma distinção crítica em ambientes dinâmicos como Kubernetes.

2. Preparando o Cluster para Observabilidade

Antes de instalar qualquer ferramenta, precisamos de um cluster funcional e do Helm instalado.

Pré-requisitos:

- Cluster Kubernetes (minikube, kind, ou cloud como EKS/GKE/AKS)
- kubectl configurado e apontando para o cluster
- Helm 3.x instalado (versão mais recente)

Verificando o cluster:

kubectl cluster-info
kubectl get nodes

Instalando o Helm:

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm version

Criando namespaces dedicados:

kubectl create namespace monitoring
kubectl create namespace logging

Organizar ferramentas em namespaces separados facilita o gerenciamento, a segurança e a limpeza futura.

3. Coleta de Métricas com Prometheus

O Prometheus é o padrão de fato para métricas em Kubernetes. Usaremos o kube-prometheus-stack, que empacota Prometheus, Alertmanager, Grafana e exportadores essenciais.

Adicionando o repositório Helm:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

Instalando o stack:

helm install prometheus prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --set grafana.enabled=true \
  --set alertmanager.enabled=true

Este comando instala:
- Prometheus Server: coleta e armazena métricas
- kube-state-metrics: métricas sobre objetos Kubernetes (pods, deployments, etc.)
- node-exporter: métricas dos nós (CPU, memória, disco)
- Grafana: visualização (abordaremos na seção 4)
- Alertmanager: gerenciamento de alertas (seção 6)

Verificando a instalação:

kubectl get pods -n monitoring
kubectl get svc -n monitoring

Verificando targets do Prometheus:

kubectl port-forward -n monitoring svc/prometheus-operated 9090:9090

Acesse http://localhost:9090/targets no navegador para ver todos os endpoints sendo monitorados.

4. Visualização de Métricas com Grafana

O Grafana já foi instalado junto com o stack. Vamos configurá-lo e importar dashboards essenciais.

Expondo o Grafana:

kubectl port-forward -n monitoring svc/prometheus-grafana 3000:80

Acesse http://localhost:3000. Credenciais padrão:
- Usuário: admin
- Senha: prom-operator

Verificando o datasource Prometheus:

No Grafana, vá em Configuration > Data Sources. O datasource Prometheus já deve estar configurado automaticamente apontando para http://prometheus-operated:9090.

Importando dashboards essenciais:

Vá em Dashboards > Import e use os seguintes IDs:
- Kubernetes Cluster (ID 315): visão geral do cluster
- Kubernetes Nodes (ID 11073): métricas detalhadas por nó
- Kubernetes Pods (ID 6411): métricas por pod

Exemplo de consulta simples:

No Prometheus, execute esta consulta para ver uso de CPU dos pods:

rate(container_cpu_usage_seconds_total{namespace="default"}[5m])

5. Centralização de Logs com Loki e Promtail

Loki é um sistema de agregação de logs desenvolvido pela Grafana Labs, projetado para ser econômico e integrar-se nativamente ao Grafana.

Instalando Loki e Promtail:

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

helm install loki grafana/loki-stack \
  --namespace logging \
  --set grafana.enabled=false \
  --set promtail.enabled=true \
  --set loki.persistence.enabled=true

Verificando a instalação:

kubectl get pods -n logging
kubectl get svc -n logging

Configurando o Promtail para capturar logs de todos os pods:

O Promtail coleta logs dos arquivos de log dos contêineres em cada nó. A configuração padrão já inclui scraping de todos os pods. Para verificar:

kubectl port-forward -n logging svc/loki 3100:3100

Teste o Loki:

curl http://localhost:3100/ready

Adicionando datasource Loki no Grafana:

  1. No Grafana, vá em Configuration > Data Sources > Add data source
  2. Selecione Loki
  3. URL: http://loki.logging.svc.cluster.local:3100
  4. Clique em Save & Test

Consultando logs no Grafana:

Vá em Explore, selecione o datasource Loki e execute:

{namespace="default"}

Para filtrar por pod específico:

{namespace="default"} |= "error"

6. Alertas Básicos e Notificações

Vamos criar regras de alerta no Prometheus e configurar o Alertmanager para notificações.

Criando regras de alerta:

Edite a configuração do Prometheus:

kubectl edit prometheus prometheus-kube-prometheus-prometheus -n monitoring

Adicione regras como:

groups:
  - name: kubernetes-alerts
    rules:
      - alert: PodCrashLooping
        expr: kube_pod_status_phase{phase="CrashLoopBackOff"} > 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Pod {{ $labels.pod }} em CrashLoopBackOff"

      - alert: NodeLowMemory
        expr: node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes < 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Nó {{ $labels.node }} com menos de 10% de memória disponível"

Configurando Alertmanager para Slack:

Edite o Alertmanager:

kubectl edit alertmanager prometheus-kube-prometheus-alertmanager -n monitoring

Adicione a configuração:

receivers:
  - name: slack
    slack_configs:
      - api_url: "https://hooks.slack.com/services/SEU/WEBHOOK/AQUI"
        channel: "#alerts"
        send_resolved: true

route:
  receiver: slack

Testando o alerta:

Force um pod a crashar:

kubectl run test-alert --image=nginx --restart=Never
kubectl delete pod test-alert

Verifique no Alertmanager:

kubectl port-forward -n monitoring svc/prometheus-kube-prometheus-alertmanager 9093:9093

Acesse http://localhost:9093 para ver alertas disparados.

7. Validação e Troubleshooting da Stack

Verificação geral de saúde:

kubectl get pods -n monitoring -o wide
kubectl get pods -n logging -o wide
kubectl logs -n monitoring prometheus-prometheus-kube-prometheus-prometheus-0

Problemas comuns e soluções:

Problema Causa provável Solução
Pods não aparecem nos targets RBAC insuficiente Verificar ClusterRoleBindings
Grafana não carrega dashboards Datasource incorreto Verificar URL do Prometheus
Loki sem logs Promtail não consegue ler arquivos Verificar permissões do daemonset
Alertas não disparam Regras mal formatadas Validar sintaxe YAML

Diagnóstico com kubectl:

# Verificar logs de um pod específico
kubectl logs -n monitoring prometheus-prometheus-kube-prometheus-prometheus-0

# Verificar eventos do namespace
kubectl get events -n monitoring

# Verificar métricas disponíveis
kubectl port-forward -n monitoring svc/prometheus-operated 9090:9090
# Acesse http://localhost:9090/api/v1/label/__name__/values

Boas práticas finais:

  • Defina limites de recursos para todos os componentes da stack
  • Configure persistência de dados para Prometheus e Loki
  • Implemente NetworkPolicies para restringir tráfego entre componentes
  • Utilize ServiceMonitors e PodMonitors para escalar a coleta de métricas
  • Documente todos os alertas criados e seus procedimentos de resposta

Com esta configuração básica, você tem métricas, logs e alertas funcionando em seu cluster Kubernetes, prontos para evoluir conforme a complexidade do ambiente aumentar.

Referências