Troubleshooting

Este guia cobre problemas comuns que você pode encontrar ao usar o Infra Operator e como resolvê-los.

Comandos de Diagnóstico

Verificar Status do Operator

Comando:

# Verificar se operator está rodando
kubectl get pods -n infra-operator

# Verificar logs do operator
kubectl logs -n infra-operator deploy/infra-operator --tail=100

# Acompanhar logs em tempo real
kubectl logs -n infra-operator deploy/infra-operator -f

Verificar Status dos Recursos

Comando:

# Listar todos os recursos
kubectl get vpc,subnet,sg,s3,ec2 -A

# Obter status detalhado
kubectl describe vpc my-vpc

# Verificar eventos
kubectl get events -n infra-operator --sort-by='.lastTimestamp'

Verificar AWSProvider

Comando:

# Verificar se provider está ready
kubectl get awsprovider

# Verificar detalhes do provider
kubectl describe awsprovider aws-production

Problemas Comuns

Operator Não Está Iniciando

Sintomas: Pod do operator em estado CrashLoopBackOff ou Error

Verificar logs:

kubectl logs -n infra-operator deploy/infra-operator --previous

Causas comuns:

CRDs Faltando

Comando:

# Verificar se CRDs estão instalados
kubectl get crds | grep aws-infra-operator.runner.codes

# Reinstalar se estiver faltando
kubectl apply -f chart/crds/

RBAC Inválido

Comando:

# Verificar ServiceAccount
kubectl get sa -n infra-operator

# Verificar ClusterRole
kubectl get clusterrole | grep infra-operator

Limites de recursos muito baixos

Exemplo:

# Aumentar em values.yaml
operator:
  resources:
    limits:
      memory: 512Mi
    requests:
      memory: 256Mi

AWSProvider Não Ready

Sintomas: AWSProvider com ready: false

Verificar:

kubectl describe awsprovider aws-production

Causas comuns:

Credenciais inválidas

Comando:

# Verificar se Secret existe
kubectl get secret aws-credentials -n infra-operator

# Testar credenciais
AWS_ACCESS_KEY_ID=$(kubectl get secret aws-credentials -n infra-operator \
  -o jsonpath='{.data.AWS_ACCESS_KEY_ID}' | base64 -d)
AWS_SECRET_ACCESS_KEY=$(kubectl get secret aws-credentials -n infra-operator \
  -o jsonpath='{.data.AWS_SECRET_ACCESS_KEY}' | base64 -d)
aws sts get-caller-identity

Região errada

Exemplo:

# Verificar região no provider
spec:
  region: us-east-1  # Deve corresponder aos seus recursos AWS

IRSA não configurado (EKS)

Comando:

# Verificar anotação do ServiceAccount
kubectl get sa infra-operator -n infra-operator -o yaml | grep eks.amazonaws.com

# Verificar trust policy do IAM role
aws iam get-role --role-name infra-operator-role

Recurso Preso em Pending

Sintomas: Recurso permanece em estado pending indefinidamente

Verificar:

kubectl describe vpc my-vpc
kubectl logs -n infra-operator deploy/infra-operator | grep "my-vpc"

Causas comuns:

AWSProvider não ready

Comando:

kubectl get awsprovider
# Garantir que o provider referenciado pelo recurso está ready

Erros de API AWS

Comando:

# Verificar logs do operator por erros AWS
kubectl logs -n infra-operator deploy/infra-operator | grep -i "error\|failed"

Rate limiting

Comando:

# Procurar por erros de throttling
kubectl logs -n infra-operator deploy/infra-operator | grep -i "throttl"

Recurso Não Deleta

Sintomas: Recurso preso em estado Terminating

Verificar:

kubectl get vpc my-vpc -o yaml | grep -A 10 finalizers

Soluções:

Verificar recursos dependentes

Comando:

# VPC não pode ser deletado se tiver subnets, IGWs, etc.
aws ec2 describe-subnets --filters "Name=vpc-id,Values=vpc-xxx"
aws ec2 describe-internet-gateways --filters "Name=attachment.vpc-id,Values=vpc-xxx"

Remover finalizer (último recurso)

Comando:

# AVISO: Isso pode deixar recursos AWS órfãos
kubectl patch vpc my-vpc -p '{"metadata":{"finalizers":[]}}' --type=merge

Forçar deleção com timeout

Comando:
```
kubectl delete vpc my-vpc --timeout=30s
```

Drift Detectado

Sintomas: Recurso mostra drift entre spec do Kubernetes e AWS

Verificar:

kubectl describe vpc my-vpc | grep -A 5 "Drift"

Soluções:

Atualizar spec para corresponder à AWS

Comando:

# Obter estado atual da AWS
aws ec2 describe-vpcs --vpc-ids vpc-xxx

# Atualizar recurso Kubernetes para corresponder
kubectl edit vpc my-vpc

Forçar reconciliação

Comando:

# Adicionar anotação para disparar reconcile
kubectl annotate vpc my-vpc force-reconcile="$(date +%s)" --overwrite

Habilitar auto-remediação

Exemplo:

spec:
  driftDetection:
    enabled: true
    autoRemediate: true

EC2 Instance Não Inicia

Sintomas: EC2Instance presa em pending ou stopped

Verificar:

kubectl describe ec2instance my-instance
aws ec2 describe-instances --instance-ids i-xxx

Causas comuns:

AMI inválida

Comando:

# Verificar se AMI existe na região
aws ec2 describe-images --image-ids ami-xxx

Tipo de instância inválido

Comando:

# Verificar tipos de instância disponíveis
aws ec2 describe-instance-types --instance-types t3.micro

Problemas com Subnet/Security Group

Comando:

# Verificar se subnet existe
aws ec2 describe-subnets --subnet-ids subnet-xxx

# Verificar security group
aws ec2 describe-security-groups --group-ids sg-xxx

Capacidade insuficiente

Comando:

# Tentar AZ diferente ou tipo de instância
aws ec2 describe-instance-type-offerings \
  --location-type availability-zone \
  --filters Name=instance-type,Values=t3.micro

S3 Bucket Permissão Negada

Sintomas: Criação de S3Bucket falha com access denied

Verificar:

kubectl logs -n infra-operator deploy/infra-operator | grep "s3\|bucket"

Soluções:

Verificar permissões IAM

JSON:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:DeleteBucket",
        "s3:GetBucketLocation",
        "s3:GetBucketTagging",
        "s3:PutBucketTagging",
        "s3:GetBucketVersioning",
        "s3:PutBucketVersioning",
        "s3:GetEncryptionConfiguration",
        "s3:PutEncryptionConfiguration"
      ],
      "Resource": "*"
    }
  ]
}

Nome do bucket já existe

Comando:

# Nomes de bucket S3 são globalmente únicos
aws s3api head-bucket --bucket my-bucket-name

Problemas de Conexão com LocalStack

Sintomas: Recursos falham ao usar LocalStack

Verificar:

# Verificar se LocalStack está rodando
kubectl get pods | grep localstack

# Testar conectividade
kubectl run test --rm -it --image=curlimages/curl -- \
  curl http://localstack.default.svc.cluster.local:4566/_localstack/health

Soluções:

Verificar URL do endpoint

Exemplo:

# No AWSProvider
spec:
  endpoint: http://localstack.default.svc.cluster.local:4566

Verificar serviços do LocalStack

Comando:

# Listar serviços em execução
curl http://localhost:4566/_localstack/health | jq

Problemas de Performance

Reconciliação Lenta

Sintomas: Recursos levam muito tempo para sincronizar

Soluções:

Aumentar concorrência

Exemplo:

# No deployment do operator
args:
  - --max-concurrent-reconciles=10

Verificar rate limits

Comando:

# Monitorar chamadas de API AWS
kubectl logs -n infra-operator deploy/infra-operator | grep -i "rate\|limit"

Alto Uso de Memória

Sintomas: Operator usando memória excessiva

Soluções:

Aumentar limites de memória

Exemplo:

operator:
  resources:
    limits:
      memory: 1Gi

Reduzir tamanho do cache

Exemplo:
```
args:
  - --cache-size=100
```

Obtendo Ajuda

Coletar Informações de Debug

Comando:

# Criar bundle de debug
mkdir debug-bundle
kubectl get pods -n infra-operator -o yaml > debug-bundle/pods.yaml
kubectl logs -n infra-operator deploy/infra-operator > debug-bundle/logs.txt
kubectl get crds | grep aws-infra-operator.runner.codes > debug-bundle/crds.txt
kubectl get awsprovider,vpc,subnet,sg -A -o yaml > debug-bundle/resources.yaml
kubectl get events -n infra-operator > debug-bundle/events.txt

Reportar Problemas

Ao reportar problemas, inclua:

Versão do operator
Versão do Kubernetes
Provedor de cloud (AWS/LocalStack)
YAML do recurso (credenciais removidas)
Logs do operator
Mensagens de erro

GitHub Issues: https://github.com/andrebassi/infra-operator/issues

Comandos de Diagnóstico​

Verificar Status do Operator​

Verificar Status dos Recursos​

Verificar AWSProvider​

Problemas Comuns​

Operator Não Está Iniciando​

AWSProvider Não Ready​

Recurso Preso em Pending​

Recurso Não Deleta​

Drift Detectado​

EC2 Instance Não Inicia​

S3 Bucket Permissão Negada​

Problemas de Conexão com LocalStack​

Problemas de Performance​

Reconciliação Lenta​

Alto Uso de Memória​

Obtendo Ajuda​

Coletar Informações de Debug​

Reportar Problemas​

Comandos de Diagnóstico

Verificar Status do Operator

Verificar Status dos Recursos

Verificar AWSProvider

Problemas Comuns

Operator Não Está Iniciando

AWSProvider Não Ready

Recurso Preso em Pending

Recurso Não Deleta

Drift Detectado

EC2 Instance Não Inicia

S3 Bucket Permissão Negada

Problemas de Conexão com LocalStack

Problemas de Performance

Reconciliação Lenta

Alto Uso de Memória

Obtendo Ajuda

Coletar Informações de Debug

Reportar Problemas