K8sGPT - Ferramenta CLI de diagnóstico e solução de problemas Kubernetes com IA

O que é K8sGPT

Gerenciar clusters Kubernetes é uma tarefa complexa que exige conhecimento profundo em SRE (Site Reliability Engineering). Quando uma aplicação entra em estado Pending, quando um Pod entra em CrashLoopBackOff, ou quando serviços enfrentam problemas de conectividade, a排查 (diagnóstico) pode ser demorada e frustrante — especialmente para equipes que não contam com especialistas certificados em Kubernetes.

K8sGPT é uma ferramenta CLI de código aberto que transforma essa realidade. O projeto aplica o conceito de "SRE como código", codificando anos de experiência em análise de problemas em analyzers modulares que, combinados com a capacidade de raciocínio de Large Language Models (LLMs), oferecem diagnóstico inteligente e sugestões de correção em linguagem natural.

A proposta é democratizar o acesso ao conhecimento de SRE. Enquanto ferramentas tradicionais de monitoramento alertam sobre problemas, o K8sGPT vai além: identifica a causa raiz, explica o que está acontecendo em termos compreensíveis e sugere ações concretas para resolução. A ferramenta já é utilizada por empresas como Spectro Cloud, Nethopper e Upstage AI, e conta com uma comunidade ativa no GitHub.

Com mais de 12 analyzers内置 cobrindo os principais recursos do Kubernetes — incluindo Pod, Service, Deployment, Ingress, StatefulSet e muito mais — o K8sGPT se adapta desde ambientes de desenvolvimento locais até operações de produção em escala enterprise.

---

Funcionalidades Principais do K8sGPT

A arquitetura do K8sGPT foi projetada para ser extensível e modular. Cada analyzer é responsável por inspecionar um tipo específico de recurso do Kubernetes, aplicando regras de validação baseadas em boas práticas operacionais. Quando combinado com um LLM, o sistema traduz os resultados técnicos em explicações acessíveis.

AI-Powered Analysis

O coração do produto é o motor de análise alimentado por IA. Ao executar k8sgpt analyze, a ferramenta varre o cluster identificando anomalias nos recursos configurados. O modo stats exibe o tempo de execução de cada analyzer, permitindo otimização de performance em ambientes com muitos recursos. Para obter explicações detalhadas, basta adicionar a flag --explain, e o LLM escolhido gera um relatório em linguagem natural com causa raiz e recomendações de remediation.

Data Anonymization

A segurança de dados é uma preocupação legítima em ambientes de produção. O K8sGPT inclui um recurso de anonimização automática que substitui nomes de objetos, labels e outros identificadores sensíveis por placeholders reversíveis antes de enviar qualquer informação ao backend de AI. Essa proteção abrange mais de 12 tipos de recursos: StatefulSet, Service, PodDisruptionBudget, Node, NetworkPolicy, Ingress, HPA, Deployment, CronJob, entre outros.

Múltiplos Provedores de AI

A flexibilidade na escolha do provedor de AI é um diferencial importante. O K8sGPT suporta integração com:

• OpenAI (GPT-4, GPT-4o)
• Azure OpenAI Service
• Google Vertex AI
• Amazon Bedrock (Claude, Llama, Titan)
• IBM WatsonX
• Cohere
• Hugging Face
• Ollama (modelos locais, sem custos de API)
• Custom REST (qualquer endpoint compatível)

A configuração é feita via comando k8sgpt auth, que armazena as credenciais de forma segura no arquivo de configuração local.

Auto Remediation

O K8sGPT pode aplicar automaticamente as correções sugeridas quando a flag --autoremediation é ativada. O usuário mantém controle total sobre o processo, podendo revisar cada ação antes da execução.

MCP Server

O Model Context Protocol (MCP) é uma especificação emergente para integração entre ferramentas de IA e sistemas externos. O K8sGPT implementa um servidor MCP completo que expõe:

• 12+ ferramentas: análise de cluster, gerenciamento de recursos, acesso a logs e eventos, configuração de analyzers
• 3 recursos: informações somente-leitura do cluster
• 3 prompts: workflows guiados para troubleshooting

O servidor pode operar em modo Stdio (k8sgpt serve --mcp) para integração com Claude Desktop, ou em modo HTTP (k8sgpt serve --mcp --mcp-http --mcp-port 8089) para implantações mais complexas.

In-Cluster Operator

Para monitoramento contínuo em produção, o k8sgpt-operator permite rodar o K8sGPT diretamente dentro do cluster Kubernetes. Ele se integra com Prometheus e Alertmanager, permitindo que alertas de análise sejam disparados automaticamente quando problemas são detectados.

Analyzers Customizados

A arquitetura suporta extensibilidade total. Desenvolvedores podem criar analyzers personalizados seguindo um schema definido, expondo-os via serviço gRPC. O projeto host-analyzer (implementado em Rust) serve como exemplo prático de como estender as capacidades nativas.

Remote Caching

Em ambientes com múltiplos clusters, o caching remoto reduz chamadas desnecessárias à API e custos de AI. O K8sGPT suporta AWS S3, Azure Blob Storage e Google Cloud Storage como backends de cache.

---

Quem Está Usando K8sGPT

O K8sGPT atende diferentes perfis de usuários, desde desenvolvedores individuais até equipes de SRE enterprise. A seguir, apresentamos os cenários mais comuns de uso:

Cenário 1: Troubleshooting Rápido de Aplicações

Quando uma aplicação apresenta problemas no cluster — um Pod preso em Pending, um Deployment com ReplicaSets não disponíveis, ou serviços com erros de conexão — a команда k8sgpt analyze --explain é executada. Em segundos, o sistema retorna não apenas o diagnóstico técnico, mas uma explicação clara do que está acontecendo e qual a ação recomendada. Isso reduz drasticamente o tempo de MTTR (Mean Time to Recovery), especialmente para equipes que estão aprendendo Kubernetes.

Cenário 2: Verificação de Saúde do Cluster

Para operações que exigem monitoramento proativo, o k8sgpt-operator pode ser implantado no cluster com análise programada. Configurando regras de tempo em tempo (cron-style), a equipe recebe alertas antes que problemas críticos afetem os usuários finais. A integração com Prometheus permite visualizar métricas de saúde no mesmo painel usado para monitorar outros serviços.

Cenário 3: Proteção de Dados em Produção

Em ambientes regulados (financeiro, saúde, governo), enviar dados do cluster para APIs externas pode ser inviável. O K8sGPT oferece duas soluções: usar a flag --anonymize para enviar apenas dados mascarados, ou executar com Ollama rodando localmente — dessa forma, nenhuma informação sai do ambiente DMZ da empresa.

Cenário 4: Integração com Claude Desktop

Para desenvolvedores que preferem interação por linguagem natural, configurar o MCP Server (k8sgpt serve --mcp) permite perguntar ao Claude Desktop coisas como "Qual é o status dos meus pods no namespace production?" ou "Me mostre os eventos recentes de erro no cluster". O assistente utiliza as ferramentas expostas pelo K8sGPT para executar operações reais.

Cenário 5: Gestão Multi-Cloud

Equipes que operam clusters em AWS (EKS), GCP (GKE), Azure (AKS) ou soluções on-premises enfrentam inconsistências na forma como cada provedor reporta erros. O K8sGPT normaliza a experiência de diagnóstico, permitindo que a mesma команда e o mesmo fluxo de trabalho sejam aplicadosindependentente de onde o cluster está hospedado.

---

Primeiros Passos

Instalação

A instalação do K8sGPT é simples e segue os padrões do ecossistema de ferramentas CLI:

macOS / Linux (via Homebrew):

brew install k8sgpt

Windows: Baixe o binário .exe do repositório GitHub e adicione ao PATH do sistema.

Kubernetes (Operator):

kubectl apply -f https://operator.k8sgpt.ai/install.yaml

Configuração do Backend de AI

Após a instalação, configure o provedor de AI de sua preferência:

# Configurar OpenAI
k8sgpt auth add openai

# Configurar Ollama (local)
k8sgpt auth add ollama

# Configurar Azure OpenAI
k8sgpt auth add azure

O arquivo de configuração será criado automaticamente no diretório padrão:

• macOS: ~/Library/Application Support/k8sgpt/k8sgpt.yaml
• Linux: ~/.config/k8sgpt/k8sgpt.yaml
• Windows: %LOCALAPPDATA%/k8sgpt/k8sgpt.yaml

Comandos Básicos

# Análise básica do cluster
k8sgpt analyze

# Análise com explicação em linguagem natural
k8sgpt analyze --explain

# Ativar anonimização de dados
k8sgpt analyze --explain --anonymize

# Ver estatísticas de performance dos analyzers
k8sgpt analyze --explain --show-stats

# Iniciar MCP Server (modo Stdio)
k8sgpt serve --mcp

# Iniciar MCP Server (modo HTTP)
k8sgpt serve --mcp --mcp-http --mcp-port 8089

Configuração com Claude Desktop

Para usar o K8sgpt com Claude Desktop, adicione a configuração no arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "k8sgpt": {
      "command": "k8sgpt",
      "args": ["serve", "--mcp"]
    }
  }
}

---

Características Técnicas

Arquitetura Modular de Analyzers

O design do K8sGPT separa claramente a lógica de coleta de dados da lógica de análise. Cada analyzer implementa uma interface específica que retorna uma lista de "results" — problemas identificados no recurso analisado. Essa abordagem permite que a comunidade contribua novos analyzers sem modificar o core da aplicação.

Os analyzers nativos incluem:

• podAnalyzer — valida estado de pods, eventos, restarts
• pvcAnalyzer — verifica claims e volumes
• serviceAnalyzer — analisa conectividade e endpoints
• deploymentAnalyzer — valida réplicas e disponibilidade
• ingressAnalyzer — verifica configuração de rotas
• eventAnalyzer — analisa eventos recentes do cluster
• nodeAnalyzer — avalia saúde de nodes
• mutatingWebhookAnalyzer / validatingWebhookAnalyzer — valida webhooks
• cronJobAnalyzer — verifica jobs agendados

Os analyzers opcionais expandem a cobertura para HPA, NetworkPolicy, Gateway API, Log Analysis e Security Analysis — úteis em ambientes que utilizam essas funcionalidades avançadas.

Suporte a MCP

O MCP Server do K8sGPT segue a especificação oficial do Model Context Protocol, expondo ferramentas e recursos de forma padronizada. Isso garante compatibilidade não apenas com Claude Desktop, mas com qualquer cliente MCP futuro. A arquitetura stdio é ideal para integração desktop, enquanto o modo HTTP escala melhor em ambientes server-side.

Segurança e Conformidade

O projeto mantém altos padrões de segurança:

• OpenSSF Best Practices certification
• Apache 2.0 — licença permissiva de código aberto
• FOSSA compliance checks
• Anonimização reversível — dados sensíveis são mascarados com hash, permitindo que o usuário reverta localmente se necessário

O suporte a Ollama elimina completamente a dependência de APIs externas, tornando o K8sGPT adequado para ambientes air-gapped ou com requisitos rigorosos de soberania de dados.

Cache Distribuído

O sistema de cache remoto utiliza protocolos nativos de cada provedor (S3, Azure Blob, GCS), permitindo que múltiplos membros da equipe ou múltiplos clusters compartilhem resultados de análise sem refazer chamadas — economizando tempo e custos de API.

---

Perguntas Frequentes