Archon/DOCKER_K8S_BUILD_STRATEGY.md

Docker vs Kubernetes Build Strategy

Overview

O projeto Archon agora mantém duas versões de imagens Docker para cada serviço:

1. Docker Version - Imagens originais para uso com Docker Compose
2. Kubernetes Version - Imagens otimizadas para produção em Kubernetes

Arquivos Dockerfile

Docker Compose (Original)

• python/Dockerfile.server → server:latest, server:docker-latest
• python/Dockerfile.mcp → mcp:latest, mcp:docker-latest
• python/Dockerfile.agents → agents:latest, agents:docker-latest
• archon-ui-main/Dockerfile.production → frontend:latest, frontend:docker-latest

Kubernetes (Optimized)

• python/Dockerfile.k8s.server → server:k8s-latest
• python/Dockerfile.k8s.mcp → mcp:k8s-latest
• python/Dockerfile.k8s.agents → agents:k8s-latest
• archon-ui-main/Dockerfile.k8s.production → frontend:k8s-latest

Image Tags

Docker Version Tags

git.automatizase.com.br/luis.erlacher/archon/server:latest
git.automatizase.com.br/luis.erlacher/archon/server:docker-latest
git.automatizase.com.br/luis.erlacher/archon/server:docker-{commit-sha}

# Mesma estrutura para: mcp, agents, frontend

Kubernetes Version Tags

git.automatizase.com.br/luis.erlacher/archon/server:k8s-latest
git.automatizase.com.br/luis.erlacher/archon/server:k8s-{commit-sha}

# Mesma estrutura para: mcp, agents, frontend

Diferenças Entre as Versões

Docker Version (Original)

• ✅ Compatível com Docker Compose
• ✅ Roda como root (compatibilidade)
• ✅ Inclui HEALTHCHECK no Dockerfile
• ✅ Estrutura simplificada para desenvolvimento local

Kubernetes Version (Optimized)

• ✅ Non-root user (UID/GID 1001) - Segurança
• ✅ Proper signal propagation - Graceful shutdown em rolling updates
• ✅ No HEALTHCHECK - K8s usa liveness/readiness probes
• ✅ Cache cleanup - Imagens menores (remove ~/.cache/pip, ~/.cache/uv)
• ✅ Production-only - Não inclui tests/ directory
• ✅ Optimized layers - Melhor aproveitamento de cache

Otimizações Kubernetes

1. Non-Root User

# Cria usuário e grupo com IDs fixos
RUN groupadd -r appuser -g 1001 && \
    useradd -r -g appuser -u 1001 appuser && \
    chown -R appuser:appuser /app

USER appuser

Benefícios:

• Segurança: Reduz risco de container escape
• Compliance: Atende policies de segurança K8s (PodSecurityStandards)
• Best Practice: Recomendado pela OWASP e CIS Benchmarks

2. Signal Propagation

# ✅ CORRETO - Propagation com exec
CMD ["sh", "-c", "exec python -m uvicorn ..."]

# ❌ INCORRETO - Shell não propaga sinais
CMD sh -c "python -m uvicorn ..."

Benefícios:

• Graceful shutdown: SIGTERM chega ao processo Python
• Zero downtime: Rolling updates funcionam corretamente
• Connection draining: Conexões fecham gracefully

3. No HEALTHCHECK

# Docker version tem:
HEALTHCHECK --interval=30s CMD ...

# K8s version NÃO tem (redundante)
# K8s já define em livenessProbe/readinessProbe

Benefícios:

• Menor tamanho de imagem
• Menos processos rodando no container
• Health checks gerenciados pelo K8s (mais flexível)

4. Cache Cleanup

RUN uv pip install --system --group mcp && \
    rm -rf ~/.cache/uv ~/.cache/pip

Benefícios:

• Imagens 10-15% menores
• Menos I/O no registry
• Pull mais rápido nos nodes K8s

Como Usar

Para Docker Compose (Desenvolvimento Local)

# docker-compose.yml
services:
  archon-server:
    image: git.automatizase.com.br/luis.erlacher/archon/server:latest
    # ou
    image: git.automatizase.com.br/luis.erlacher/archon/server:docker-latest

Para Kubernetes (Produção)

# k8s-manifests.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: archon-server
spec:
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        runAsGroup: 1001
        fsGroup: 1001
      containers:
      - name: server
        image: git.automatizase.com.br/luis.erlacher/archon/server:k8s-latest
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
              - ALL

CI/CD Workflow

O workflow .gitea/workflows/build-images.yml constrói ambas as versões automaticamente:

Trigger

• Push para branch main
• Workflow manual dispatch

Jobs Executados

Docker Version (4 jobs):

• build-server-docker
• build-mcp-docker
• build-agents-docker
• build-frontend-docker

Kubernetes Version (4 jobs):

• build-server-k8s
• build-mcp-k8s
• build-agents-k8s
• build-frontend-k8s

Total: 8 jobs paralelos (quando possível)

Atualizar Manifests Kubernetes

Para usar as imagens K8s otimizadas, atualize k8s-manifests-complete.yaml:

# ANTES (versão Docker)
image: git.automatizase.com.br/luis.erlacher/archon/server:latest

# DEPOIS (versão K8s)
image: git.automatizase.com.br/luis.erlacher/archon/server:k8s-latest

Faça isso para todos os deployments:

• archon-server
• archon-mcp
• archon-agents
• archon-frontend

Tamanhos das Imagens

Estimativa de Redução (K8s vs Docker)

Service	Docker	K8s	Redução
Server	~1.2GB	~1.1GB	~8%
MCP	~450MB	~420MB	~7%
Agents	~480MB	~450MB	~6%
Frontend	~50MB	~48MB	~4%

Economia total: ~100MB por deploy completo

Testes

Verificar Non-Root

# Docker
docker run --rm git.automatizase.com.br/luis.erlacher/archon/server:k8s-latest id
# Esperado: uid=1001(appuser) gid=1001(appuser)

# Kubernetes
kubectl exec -it deployment/archon-server -n archon -- id
# Esperado: uid=1001(appuser) gid=1001(appuser)

Testar Graceful Shutdown

# Docker
docker run -d --name test git.automatizase.com.br/luis.erlacher/archon/server:k8s-latest
docker stop test  # Deve parar em ~2-3 segundos

# Kubernetes
kubectl rollout restart deployment/archon-server -n archon
kubectl rollout status deployment/archon-server -n archon
# Deve ser smooth, sem downtime

Verificar Tamanho das Imagens

docker images | grep archon
# Compare tags 'latest' vs 'k8s-latest'

Migration Checklist

Se você está migrando de Docker para K8s:

• Pull das novas imagens K8s
• Atualizar manifests K8s para usar :k8s-latest
• Adicionar securityContext nos deployments (veja exemplo acima)
• Adicionar terminationGracePeriodSeconds: 30
• Remover HEALTHCHECKs se você tinha configurado manualmente
• Testar rolling updates funcionam corretamente
• Verificar logs não mostram permission errors

Manutenção

Quando Modificar Dockerfiles

Docker Version (Original):

• Modificar apenas para compatibilidade com Docker Compose
• Manter simples e focado em desenvolvimento local

Kubernetes Version (Optimized):

• Aplicar todas as otimizações de produção
• Seguir best practices de segurança
• Manter alinhado com Docker version (funcionalidades)

Sincronização

As duas versões devem ter as mesmas funcionalidades, apenas diferindo em:

• User (root vs non-root)
• Signal propagation (CMD format)
• Health checks (Dockerfile vs K8s)
• Optimizations (cache cleanup, layer ordering)

Troubleshooting

Erro: Permission Denied no K8s

Error: EACCES: permission denied, open '/app/file'

Solução: Verifique se todos os arquivos foram copiados com --chown=appuser:appuser

Erro: Rolling Update com Downtime

502 Bad Gateway durante deploy

Solução: Verifique se CMD usa exec form para propagação de sinais

Erro: Imagem Pull Failed

ImagePullBackOff

Solução: Verifique se as imagens K8s foram construídas e pushed:

# No servidor Gitea Actions
docker images | grep k8s-latest

Referências

• DOCKERFILE_K8S_IMPROVEMENTS.md - Análise detalhada
• Kubernetes Best Practices
• OWASP Docker Security
• 12 Factor App