Archon/k8s/QUICKSTART.md

Guia Rápido de Deploy - Archon no Kubernetes

Este guia mostra o caminho mais rápido para fazer deploy do Archon em um cluster Kubernetes.

Pré-requisitos

• Cluster Kubernetes funcionando
• kubectl configurado e conectado ao cluster
• Namespace unlkd criado (ou será criado automaticamente)
• Nginx Ingress Controller instalado
• Cert Manager instalado com ClusterIssuer letsencrypt
• Docker instalado localmente (para build das imagens)
• Acesso a um Container Registry (Docker Hub, GCR, DigitalOcean, etc.)
• Conta Supabase com projeto criado

Passo 1: Build e Push das Imagens

# No diretório raiz do projeto Archon
cd /home/luis/projetos/Archon

# Execute o script de build (substitua pelo seu registry)
./k8s/build-and-push.sh docker.io/seuusuario latest

Ou para registries específicos:

# Docker Hub
./k8s/build-and-push.sh docker.io/seuusuario latest

# Google Container Registry
./k8s/build-and-push.sh gcr.io/seu-projeto latest

# DigitalOcean Registry
./k8s/build-and-push.sh registry.digitalocean.com/seu-registry latest

# AWS ECR
./k8s/build-and-push.sh 123456789.dkr.ecr.us-east-1.amazonaws.com/archon latest

Passo 2: Atualizar Referências das Imagens

cd k8s/

# Substituir 'your-registry' pelo registry real
sed -i 's|your-registry|docker.io/seuusuario|g' *-deployment-*.yaml

# Se não usou 'latest', substitua pela versão correta
sed -i 's|:latest|:v1.0.0|g' *-deployment-*.yaml

Passo 3: Configurar o Secret

Edite o arquivo 01-secret.yaml:

vi 01-secret.yaml

Configure as variáveis obrigatórias:

# Obrigatório
SUPABASE_URL: "https://seu-projeto.supabase.co"
SUPABASE_SERVICE_KEY: "eyJhbGc...sua-chave-service-role"
SUPABASE_ANON_KEY: "eyJhbGc...sua-chave-anon"

# Opcional mas recomendado
OPENAI_API_KEY: "sk-...sua-chave-openai"

Para obter as chaves do Supabase:

1. Acesse: https://supabase.com/dashboard/project/SEU_PROJECT_ID/settings/api
2. Copie a URL do projeto
3. Copie a chave service_role (NÃO a chave anon)
4. Copie a chave anon também

Passo 4: Configurar DNS

Configure os seguintes registros DNS A/CNAME apontando para o IP externo do seu Ingress Controller:

archon.digiworker.com.br    → <IP_DO_INGRESS>
server.digiworker.com.br    → <IP_DO_INGRESS>
mcp.digiworker.com.br       → <IP_DO_INGRESS>
agents.digiworker.com.br    → <IP_DO_INGRESS>

Para descobrir o IP do Ingress:

kubectl get svc -n ingress-nginx ingress-nginx-controller

Passo 5: Deploy

# Usando o script auxiliar (recomendado)
./deploy.sh apply

# Ou manualmente
kubectl apply -f .

Passo 6: Verificar o Deploy

# Verificar status dos pods
./deploy.sh status

# Ou manualmente
kubectl get pods -n unlkd -l app.kubernetes.io/instance=archon

Aguarde até todos os pods estarem em status Running:

NAME                               READY   STATUS    RESTARTS   AGE
archon-server-xxx                  1/1     Running   0          2m
archon-mcp-xxx                     1/1     Running   0          2m
archon-agents-xxx                  1/1     Running   0          2m
archon-frontend-xxx                1/1     Running   0          2m

Passo 7: Verificar Certificados TLS

kubectl get certificate -n unlkd

Os certificados devem estar com status Ready: True:

NAME                    READY   SECRET                  AGE
archon-frontend-tls     True    archon-frontend-tls     5m
archon-server-tls       True    archon-server-tls       5m
archon-mcp-tls          True    archon-mcp-tls          5m
archon-agents-tls       True    archon-agents-tls       5m

Se não estiverem prontos, aguarde alguns minutos. O Cert Manager precisa validar o domínio e emitir os certificados.

Passo 8: Acessar a Aplicação

Acesse no navegador:

• Frontend: https://archon.digiworker.com.br
• API: https://server.digiworker.com.br/health
• MCP: https://mcp.digiworker.com.br/health
• Agents: https://agents.digiworker.com.br/health

Comandos Úteis

Ver logs de um serviço

./deploy.sh logs
# Ou manualmente:
kubectl logs -n unlkd -l app.kubernetes.io/name=archon-server -f

Reiniciar um serviço

./deploy.sh restart
# Ou manualmente:
kubectl rollout restart deployment/archon-server -n unlkd

Atualizar uma imagem

# Build nova versão
./k8s/build-and-push.sh docker.io/seuusuario v1.1.0

# Atualizar deployment
kubectl set image deployment/archon-server -n unlkd \
  archon-server=docker.io/seuusuario/archon-server:v1.1.0

Escalar replicas

kubectl scale deployment/archon-server -n unlkd --replicas=3

Ver eventos do cluster

kubectl get events -n unlkd --sort-by='.lastTimestamp'

Troubleshooting

Pods com status CrashLoopBackOff

# Ver logs do pod
kubectl logs -n unlkd <pod-name>

# Ver detalhes do pod
kubectl describe pod -n unlkd <pod-name>

Causas comuns:

• Credenciais do Supabase incorretas
• Imagem não encontrada no registry
• Portas conflitantes

Certificados TLS não são emitidos

# Verificar status do certificado
kubectl describe certificate -n unlkd archon-frontend-tls

# Ver logs do cert-manager
kubectl logs -n cert-manager -l app=cert-manager -f

Causas comuns:

• DNS não está apontando corretamente
• ClusterIssuer letsencrypt não configurado
• Rate limit do Let's Encrypt (espere 1 hora)

Serviços não se comunicam

# Testar conectividade entre pods
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -n unlkd -- sh

# Dentro do pod:
curl http://archon-server:8181/health
curl http://archon-mcp:8051/health
curl http://archon-agents:8052/health

Ingress não roteia corretamente

# Verificar ingress
kubectl describe ingress archon -n unlkd

# Ver logs do nginx ingress
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller -f

Próximos Passos

1. Configurar Backup do Secret

   • Considere usar Sealed Secrets ou External Secrets Operator

2. Adicionar Monitoring

   • Configure Prometheus e Grafana para monitorar o cluster

3. Configurar Auto-scaling

   kubectl autoscale deployment archon-server -n unlkd --cpu-percent=70 --min=1 --max=5
   

4. Adicionar NetworkPolicies

   • Restrinja comunicação entre pods

5. Configurar Persistent Storage

   • Se precisar armazenar dados localmente

Limpeza

Para remover completamente a aplicação:

./deploy.sh delete

Ou manualmente:

kubectl delete -f k8s/

Suporte

Para mais detalhes, consulte:

• README.md - Documentação completa
• Docker Compose - Configuração de referência
• .env.example - Variáveis de ambiente disponíveis