Skip to content

jera/jera-cloud-analyzer

BranchesTags

Repository files navigation

🔍 Jera Cloud Analyzer CLI

Esse projeto foi desenvolvido com o suporte de Inteligencia Articial, em especifico a ferramenta Cursor.

Análise inteligente de custos AWS com IA - Ferramenta CLI empresarial e MCP Server

O Jera Cloud Analyzer é uma ferramenta CLI avançada que utiliza Inteligência Artificial para analisar, otimizar e fornecer insights sobre seus custos e recursos AWS através de conversas em linguagem natural. Disponível como CLI local e como MCP Server para integração com IDEs e ferramentas de IA.

🚀 Duas Formas de Usar

🖥️ 1. CLI Local (Desenvolvimento e Uso Direto)

cloud-analyzer -q "Quais são os 5 serviços mais caros?"
cloud-analyzer -q "Analise instâncias EC2 subutilizadas"

🐳 2. MCP Server (Integração com IDEs e IA)

Nós recomendamos que o arquivo docker-compose.yml seja usado por que ele usa diretamente a imagem docker que sempre vai estar atualizado. O docker-compose-local.yml usa o código local para buildar a imagem.

docker-compose up -d
# Acesse via http://localhost:8000/mcp

✨ Principais Recursos

🎯 Análise Conversacional de Custos

cloud-analyzer -q "Quais são os 5 serviços mais caros?"
cloud-analyzer -q "Analise instâncias EC2 subutilizadas"
cloud-analyzer -q "Compare custos S3 vs EBS no último trimestre"

📊 28 Ferramentas Especializadas

Categoria Ferramentas Casos de Uso
💰 Cost Explorer 8 tools Análise de custos, previsões, breakdowns detalhados
📈 CloudWatch 6 tools Performance, métricas, monitoramento
🖥️ EC2 & ELB 10 tools Instâncias, volumes, load balancers, networking
🏷️ Tagging & Governance 4 tools Auditoria, governança, compliance

🔍 Resolução Inteligente

  • Aceita apelidos: rds, ec2, s3 → nomes oficiais AWS
  • Tolerante a erros: databse → database services
  • Sugestões automáticas: quando não encontra, sugere similares

🏢 Integração Empresarial

  • AWS SSO: Detecta automaticamente sessões ativas
  • jera-cli: Integração nativa com ferramentas Jera
  • Multi-conta: Suporte para AWS Organizations
  • Auditoria: Log automático de todas as consultas

🚀 Instalação e Configuração

📦 Opção 1: Uso como CLI Local

1. Clone e Instale

git clone https://github.com/jera/jera-cloud-analyzer
cd jera-cloud-analyzer
./install.sh

2. Configure OpenAI

# Edite o arquivo .env
nano .env

# Adicione apenas:
OPENAI_API_KEY=your_api_key_here

3. Pronto para usar!

cloud-analyzer -q "Olá, analise meus custos AWS"

🐳 Opção 2: Uso como MCP Server (Docker)

1. Configure Variáveis de Ambiente

# Crie o arquivo .env
cat > .env << EOF
# AWS Credentials (opcional se usar SSO)
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1

# Configuração do servidor
EXTERNAL_PORT=8000
EOF

2. Inicie o Servidor MCP

Nós recomendamos que o arquivo docker-compose.yml seja usado por que ele usa diretamente a imagem docker que sempre vai estar atualizado. O docker-compose-local.yml usa o código local para buildar a imagem.

# Iniciar servidor em background
docker-compose up -d

# Verificar logs
docker-compose logs -f cloud-insights-mcp

# Verificar saúde do servidor
curl http://localhost:8000/health

3. Integração com Cursor/Claude Desktop

Para Cursor IDE:

// Adicione ao settings.json do Cursor
{
  "mcp.servers": {
    "jera-cloud-analyzer": {
      "command": "curl",
      "args": [
        "-X", "POST", 
        "http://localhost:8000/mcp",
        "-H", "Content-Type: application/json"
      ]
    }
  }
}

Para Claude Desktop:

// Em ~/.config/claude-desktop/claude_desktop_config.json
{
  "mcpServers": {
    "jera-cloud-analyzer": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "http://localhost:8000/mcp", 
        "-H", "Content-Type: application/json"
      ]
    }
  }
}

Para LobeChat:

{
  "mcpServers": {
    "jera-cloud-analyzer": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "http://localhost:8000/mcp", 
        "-H", "Content-Type: application/json"
      ]
    }
  }
}

4. Testando a Integração MCP

python test_mcp.py

🔧 Comandos Docker Úteis

# Ver status dos containers
docker-compose ps

# Parar o servidor
docker-compose down

# Rebuild da imagem
docker-compose build --no-cache

# Modo debug (container interativo)
docker-compose --profile debug up cloud-insights-debug

# Entrar no container para debug
docker-compose exec cloud-insights-mcp bash

# Ver logs em tempo real
docker-compose logs -f

# Limpar volumes e rebuild completo
docker-compose down -v
docker system prune -f
docker-compose up --build -d

💡 AWS credenciais são detectadas automaticamente via SSO, variáveis de ambiente ou arquivos de configuração

📖 Casos de Uso Empresariais

💰 FinOps e Otimização de Custos

# CLI Local
cloud-analyzer -q "Top 10 serviços mais caros nos últimos 3 meses"
cloud-analyzer -q "Como evoluiu o custo do EC2 nos últimos 6 meses?"

# Via MCP (no Cursor/Claude)
"Encontre instâncias subutilizadas e calcule economia potencial"
"Analise custos por tag Environment e Project"

🏗️ Governança e Compliance

# CLI Local
cloud-analyzer -q "Audite recursos sem tags de governança"
cloud-analyzer -q "Encontre volumes EBS não anexados e Elastic IPs não utilizados"

# Via MCP
"Verifique se recursos seguem políticas de nomenclatura"
"Liste recursos órfãos por categoria de impacto"

📈 Performance e Monitoring

# CLI Local
cloud-analyzer -q "Analise CPU e memória das instâncias EC2"
cloud-analyzer -q "Mostre métricas da instância Valhalla nos últimos 7 dias"

# Via MCP
"Preveja crescimento de custos para o próximo trimestre"
"Analise performance de rede das instâncias de produção"

🔍 Análise Específica por Recurso

# Instância específica
cloud-analyzer -q "Analise custos da instância com nome WebServer-Prod"

# Serviço específico
cloud-analyzer -q "Detalhamento completo de custos do RDS"

# Por região
cloud-analyzer -q "Compare custos entre us-east-1 e us-west-2"

🏗️ Arquitetura e Comparação dos Modos

📊 CLI vs MCP Server - Quando Usar?

Aspecto 🖥️ CLI Local 🐳 MCP Server
Melhor para Análises pontuais, scripts, debugging Integração contínua com IDEs, IA assistants
Setup ⚡ Rápido (pip install) 🔧 Médio (Docker required)
Performance 🚀 Nativo, sem overhead 📡 Network calls, leve overhead
Escalabilidade 👤 Single user 👥 Multi-user, concurrent
Integração 📝 Terminal, scripts 🤖 Cursor, Claude, outros LLMs
Recursos 💾 Low memory usage 🐋 Containerizado, resource limits
Logs 📄 Local files 🗂️ Container logs, centralized
Updates 🔄 Manual pip upgrade 🏗️ Docker rebuild

🔧 Arquitetura Técnica

CLI Mode

User Command → CLI Parser → AI Agent → AWS APIs → Results
     ↓              ↓            ↓          ↓
   Terminal      Python      OpenAI    boto3

MCP Server Mode

IDE/LLM → HTTP Request → MCP Server → AI Agent → AWS APIs → JSON Response
   ↓           ↓             ↓           ↓          ↓           ↓
Cursor     Docker        FastMCP     OpenAI    boto3    HTTP/JSON

🔑 Configuração de Credenciais

🥇 AWS SSO (Recomendado - Empresarial)

# Se você usa jera-cli
jera-cli aws-login

# Ou AWS SSO nativo
aws sso configure
aws sso login

🥈 Variáveis de Ambiente

# No arquivo .env
AWS_ACCESS_KEY_ID=...
AWS_SECRET_REMOVED=...
AWS_DEFAULT_REGION=us-east-1

🛠️ Comandos Avançados

Ajuda e Exemplos

# Ver exemplos práticos
cloud-analyzer --examples

# Informações da versão
cloud-analyzer --version

# Ajuda completa
cloud-analyzer --help

Consultas Avançadas

# Análise temporal específica
cloud-analyzer -q "Custos de janeiro a março de 2024 por serviço"

# Comparação entre períodos
cloud-analyzer -q "Compare custos de Q1 2024 vs Q1 2023"

# Análise preditiva
cloud-analyzer -q "Com base nos padrões atuais, preveja custos para dezembro"

# Deep dive técnico
cloud-analyzer -q "Analise tipos de instância EC2 e recomende otimizações"

🏢 Para Equipes Empresariais

🎯 Para FinOps Teams

  • Relatórios automáticos de custos em linguagem natural
  • Identificação proativa de anomalias de gastos
  • Análise de ROI de Reserved Instances e Savings Plans
  • Tracking de budgets e alertas personalizados

🔧 Para DevOps/SRE

  • Correlação entre performance e custos
  • Identificação de recursos subutilizados
  • Análise de impacto de mudanças na infraestrutura
  • Otimização de right-sizing automática

📊 Para Gestores e C-Level

  • Dashboards executivos em linguagem de negócio
  • Análise de custos por departamento/projeto
  • Projeções financeiras baseadas em tendências
  • ROI de iniciativas de cloud optimization

🏗️ Arquitetura e Segurança

🔒 Segurança Empresarial

  • Zero dados persistidos: Todas as consultas são temporárias
  • Credenciais seguras: Uso de AWS IAM, SSO e roles
  • Logs auditáveis: Rastreamento completo de operações
  • Permissões mínimas: Apenas leitura necessária

⚡ Performance

  • Cache inteligente: Respostas instantâneas para consultas repetidas
  • Processing paralelo: Múltiplas APIs AWS simultâneas
  • Rate limiting: Respeitosos com limites da AWS
  • Fallback automático: Degradação graceful em caso de errors

📦 Dependências Mínimas

# Core requirements
boto3>=1.34.0          # AWS SDK
openai>=1.0.0          # GPT integration
haystack-ai>=2.0.0     # AI orchestration
python-dotenv>=1.0.0   # Environment management

🚦 Permissões IAM Necessárias

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CostExplorerFullAccess",
            "Effect": "Allow",
            "Action": [
                "ce:GetCostAndUsage",
                "ce:GetDimensionValues",
                "ce:GetCostForecast",
                "ce:GetTags",
                "ce:ListCostCategoryDefinitions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "CloudWatchMetricsReadOnly",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricData"
            ],
            "Resource": "*"
        },
        {
            "Sid": "EC2ReadOnlyExtended",
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances",
                "ec2:DescribeInstanceStatus",
                "ec2:DescribeInstanceTypes",
                "ec2:DescribeInstanceCreditSpecifications",
                "ec2:DescribeVolumes",
                "ec2:DescribeSnapshots",
                "ec2:DescribeImages",
                "ec2:DescribeVpcs",
                "ec2:DescribeSubnets",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DescribeRouteTables",
                "ec2:DescribeInternetGateways",
                "ec2:DescribeNatGateways",
                "ec2:DescribeVpcPeeringConnections",
                "ec2:DescribeAddresses",
                "ec2:DescribeNetworkAcls",
                "ec2:DescribeVpcEndpoints",
                "ec2:DescribeCustomerGateways",
                "ec2:DescribeVpnGateways",
                "ec2:DescribeVpnConnections",
                "ec2:DescribeKeyPairs",
                "ec2:DescribeRegions",
                "ec2:DescribeAvailabilityZones",
                "ec2:DescribeTags",
                "ec2:DescribeAccountAttributes"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ELBv2ReadOnly",
            "Effect": "Allow",
            "Action": [
                "elasticloadbalancing:DescribeLoadBalancers",
                "elasticloadbalancing:DescribeTargetGroups",
                "elasticloadbalancing:DescribeListeners",
                "elasticloadbalancing:DescribeTargetHealth"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ResourceGroupsTaggingAPI",
            "Effect": "Allow",
            "Action": [
                "tag:GetTagValues",
                "tag:GetTagKeys",
                "tag:GetResources"
            ],
            "Resource": "*"
        },
        {
            "Sid": "STSIdentityVerification",
            "Effect": "Allow",
            "Action": [
                "sts:GetCallerIdentity"
            ],
            "Resource": "*"
        },
        {
            "Sid": "OptionalSupportAccess",
            "Effect": "Allow",
            "Action": [
                "support:DescribeCases",
                "support:DescribeTrustedAdvisorChecks",
                "support:DescribeTrustedAdvisorCheckResult"
            ],
            "Resource": "*"
        }
    ]
}

💡 Para ambientes corporativos, recomendamos usar a política ReadOnlyAccess

🔄 Desenvolvimento e Contribuição

Executar em Modo de Desenvolvimento

# Clonar repositório
git clone https://github.com/jera/jera-cloud-analyzer
cd jera-cloud-analyzer

# Instalar em modo editável
pip install -e .

# Testar
cloud-analyzer -q "Teste de funcionamento"

Estrutura do Projeto

cloud-analyzer/
├── cli.py                    # 🚀 Interface CLI principal
├── src/
│   ├── ia/
│   │   ├── agent.py         # 🤖 Motor de IA
│   │   └── tools/           # 🛠️ 28 ferramentas especializadas
│   ├── clouds/aws/          # ☁️ Integrações AWS
│   └── mcp/
│       └── server.py        # 🐳 Servidor MCP
├── docker-compose.yml       # 🐋 Configuração Docker
├── Dockerfile              # 📦 Imagem Docker
├── setup.py                 # 📦 Configuração do pacote
└── env.example              # ⚙️ Template de configuração

🔧 Troubleshooting

🖥️ Problemas Comuns - CLI

Erro: "No AWS credentials found"

# Verificar credenciais
aws sts get-caller-identity

# Configurar SSO
aws sso configure
aws sso login

# Ou exportar variáveis
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_DEFAULT_REGION=us-east-1

Erro: "OpenAI API key not found"

# Verificar .env
cat .env | grep OPENAI

# Exportar temporariamente
export OPENAI_API_KEY=your_key_here

# Verificar se está carregando
cloud-analyzer --version

Erro: "Permission denied" em APIs AWS

# Verificar permissões IAM
aws iam get-user

# Testar com política ReadOnlyAccess
aws iam attach-user-policy \
  --user-name your-user \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

🐳 Problemas Comuns - MCP Server

Container não inicia

# Verificar logs detalhados
docker-compose logs cloud-insights-mcp

# Rebuild imagem
docker-compose build --no-cache

# Verificar variáveis de ambiente
docker-compose config

Erro de conexão MCP

# Testar conectividade
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Verificar porta
netstat -tulpn | grep 8000

# Verificar firewall
sudo ufw status

Health check falhando

# Debug manual
docker-compose exec cloud-insights-mcp curl http://localhost:8000/health

# Verificar logs da aplicação
docker-compose exec cloud-insights-mcp python -c "
import src.mcp.server
print('✅ MCP Server OK')
"

# Restart forçado
docker-compose restart cloud-insights-mcp

Problemas de performance

# Monitorar recursos
docker stats cloud-insights-mcp-server

# Ajustar limits no docker-compose.yml
deploy:
  resources:
    limits:
      memory: 2G
      cpus: '1.0'

# Verificar AWS rate limits
docker-compose logs | grep -i "rate\|throttl"

🔍 Debug Avançado

Modo Debug Interativo

# Iniciar container em modo debug
docker-compose --profile debug up cloud-insights-debug

# Entrar no container
docker-compose exec cloud-insights-debug bash

# Executar testes manuais
python -c "
from src.ia.tools.aws_data_tools import get_top_services
print(get_top_services(limit=3))
"

Logs Estruturados

# Ver logs em tempo real com timestamps
docker-compose logs -f --timestamps cloud-insights-mcp

# Filtrar logs por nível
docker-compose logs cloud-insights-mcp | grep ERROR

# Exportar logs para análise
docker-compose logs cloud-insights-mcp > debug.log

Teste de Integração Completo

# Script de teste completo
#!/bin/bash
echo "🧪 Testando integração completa..."

# 1. Testar CLI
echo "📝 Testando CLI..."
cloud-analyzer -q "teste básico" || echo "❌ CLI failed"

# 2. Testar Docker
echo "🐳 Testando Docker..."
docker-compose up -d
sleep 10

# 3. Testar MCP
echo "🔧 Testando MCP..."
curl -s http://localhost:8000/health | grep "OK" || echo "❌ MCP failed"

# 4. Testar ferramentas
echo "🛠️ Testando ferramentas..."
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  jq '.result | length' || echo "❌ Tools failed"

echo "✅ Teste concluído!"

📊 Métricas de Uso

🎯 ROI Típico

  • Economia identificada: 15-30% dos custos AWS
  • Tempo de setup: < 5 minutos
  • Payback: Primeira semana de uso
  • Produtividade: 10x mais rápido que análise manual

📈 Casos de Sucesso

  • Startup SaaS: Reduziu 40% dos custos EC2 identificando right-sizing
  • E-commerce: Economizou $15k/mês otimizando RDS e storage
  • Fintech: Implementou governança que evita 25% de waste mensal

🆘 Suporte e Documentação

📧 Suporte Empresarial

📚 Recursos Adicionais

  • Best Practices: Guias de otimização de custos AWS
  • Templates: Políticas de governança e tagging
  • Integrações: APIs para dashboards personalizados

📝 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

🚀 Transforme sua gestão de custos AWS hoje mesmo!
💡 De perguntas simples a insights complexos em segundos
🏢 Feito para empresas que levam FinOps a sério

GitHub stars License: MIT Python 3.8+

About

Agente especializado em analisar custos de infraestrutura

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

Jera Cloud Analyzer - 1.0.0 Latest
May 26, 2025
+ 2 releases

Packages

No packages published

Contributors 2

  •  
  •  

Languages