Especificação — serviço de deploy multiservidor

Estado implementado (2026-07-20): deploy-agent/ entrega POST /v1/deploy async (202) + GET /v1/deploy/{id}, pipeline sync→recreate→stabilize→verify, lock, auditoria. CI DEV usa gate #publish + poll. Ambientes: dev e qas. HMAC/TLS no agent e publish em feature/*/feat/ = MVP2 / evolução.

Doc operacional do pacote: deploy-agent/docs/README.md · Guia: guia-atualizacao-servidor.md.

Este documento define um processo completo, seguro e replicavel para automatizar deploy em servidores de teste (DEV/QAS), usando um microservico Python de deploy acionado por pipeline CI/CD.

Objetivo principal: eliminar operacao manual de git pull, rebuild e restart, com padrao unico para varios servidores.

1) Escopo e Objetivos

Objetivos

• Automatizar atualizacao de codigo e servicos Docker por requisicao autenticada.
• Permitir deploy por servico especifico ou deploy completo.
• Padronizar o processo para varios servidores de teste.
• Reduzir risco operacional com lock, timeout, auditoria e rollback.

Fora de escopo (neste primeiro ciclo)

• Deploy de producao com estrategia blue/green.
• Orquestracao Kubernetes.
• Auto rollback por analise funcional (somente rollback tecnico basico).

2) Arquitetura de Referencia

Componentes

• CI/CD (GitHub Actions): build/push de imagens e gatilho de deploy.
• Deploy Agent (Python): API HTTP interna para disparar deploy no servidor.
• Host Executor (shell scripts): usa scripts existentes em ecosif-structure/scripts.
• Docker Compose Stack: servicos da plataforma ECOSIF.
• Observabilidade: logs estruturados + healthcheck + metricas basicas.

Fluxo de alto nivel

1. push em develop (ou branch de ambiente).
2. CI valida build e publica imagens.
3. CI chama endpoint do Deploy Agent no(s) servidor(es) de teste.
4. Agent valida autenticacao/autorizacao.
5. Agent executa pipeline local: - atualizar git/submodulos; - atualizar servico alvo (ou todos); - reiniciar servico(s); - validar health; - registrar auditoria.
6. Agent retorna status detalhado para o CI.

3) Contrato da API de Deploy

Endpoint principal

• POST /v1/deploy

Request body

{
  "user": "nome-ou-sistema",
  "key": "token-ou-assinatura",
  "service": "ecosif-auth",
  "branch": "develop",
  "environment": "dev"  // ou "qas",
  "request_id": "uuid-opcional"
}

Regras de negocio

• user: obrigatorio, usado para auditoria.
• key: obrigatorio, validado por segredo no servidor.
• service:
• vazio/null => deploy completo;
• preenchido => deploy apenas daquele servico.
• branch: opcional, default develop.
• environment: opcional, default dev.
• request_id: opcional, se ausente o servidor gera um UUID.

Response

{
  "request_id": "4b4b7b6e-....",
  "status": "success",
  "server": "dev-01",
  "branch": "develop",
  "service": "ecosif-auth",
  "steps": [
    {"name":"git_update","status":"ok","duration_ms":4212},
    {"name":"service_update","status":"ok","duration_ms":80125},
    {"name":"restart","status":"ok","duration_ms":15000},
    {"name":"healthcheck","status":"ok","duration_ms":3200}
  ],
  "started_at": "2026-05-05T12:00:00Z",
  "finished_at": "2026-05-05T12:01:45Z"
}

Codigos HTTP sugeridos

• 200: concluido com sucesso.
• 202: aceito e executando em background (modo async).
• 400: payload invalido.
• 401: autenticacao invalida.
• 403: usuario sem permissao.
• 409: deploy em execucao (lock ativo).
• 422: servico nao permitido.
• 500: erro interno.

4) Seguranca (Obrigatorio para "sem dor")

Controles minimos

• Endpoint exposto apenas em rede interna/VPN.
• TLS (reverse proxy com certificado).
• Autenticacao por token forte (minimo 32 bytes) ou HMAC.
• Lista de usuarios permitidos (allowlist).
• Lista de servicos permitidos (allowlist fixa):
• ecosif-auth
• ecosif-masterdata
• ecosif-moviments
• ecosif-querys
• ecosif-reports
• ecosif-compliance
• ecosif-angular
• (ecosif-automations fora — Lambda AWS)
• Nunca interpolar service em shell com shell=True.
• Timeout por etapa + timeout total.
• Lock de concorrencia para impedir dois deploys simultaneos.
• Logs sem segredos (mascarar token/chave).

Recomendacao de autenticacao

• Curto prazo: X-API-Key + user com allowlist.
• Medio prazo: assinatura HMAC com timestamp e nonce:
• previne replay;
• dispensa envio de segredo no body.

5) Implementacao do Deploy Agent (Python)

Stack recomendada (leve)

• Python 3.11+
• FastAPI + Uvicorn
• Pydantic para validacao
• subprocess.run(..., shell=False) para comandos
• filelock (ou lockfile manual)

Estrutura minima de codigo

• app/main.py - API e middlewares
• app/auth.py - validacao de credenciais
• app/deploy_service.py - orquestracao dos passos
• app/executor.py - execucao segura de comandos
• app/settings.py - configuracoes por ambiente
• app/models.py - request/response schema

Comandos base (usando scripts existentes)

• Atualizacao git/submodulos:
• bash scripts/update-submodules.sh <branch>
• Atualizacao deploy:
• servico especifico:
  • bash scripts/update.sh --dev --branch <branch> <service>
• completo:
  • bash scripts/update.sh --dev --branch <branch> --yes
• Reinicio:
• servico especifico:
  • bash scripts/restart.sh --dev <service>
• completo:
  • bash scripts/restart.sh --dev

Importante: para automacao sem interacao, o update.sh deve suportar flag --yes (nao perguntar confirmacao).

6) Processo Operacional (Passo a Passo)

Processo de deploy por requisicao

1. Receber request e validar schema.
2. Autenticar user e key.
3. Validar service na allowlist (se informado).
4. Adquirir lock global de deploy.
5. Registrar auditoria started.
6. Executar: - etapa A: atualizar git/submodulos; - etapa B: atualizar servico(s); - etapa C: reiniciar servico(s); - etapa D: validar healthchecks.
7. Registrar auditoria finished com resultado.
8. Liberar lock.
9. Retornar resultado detalhado.

Healthcheck minimo

• docker compose ps sem servico critico em estado exited/unhealthy.
• Endpoints:
• /ecosif-auth/actuator/health
• /ecosif-masterdata/actuator/health
• /ecosif-moviments/actuator/health
• /ecosif-querys/actuator/health
• /ecosif-reports/actuator/health
• /ecosif-compliance/health

7) Topologia Multiservidor

Padrao de replicacao

• Instalar o mesmo Deploy Agent em cada servidor:
• dev-01, dev-02, qas-01, etc.
• Cada servidor com:
• SERVER_NAME
• ENVIRONMENT
• ALLOWED_BRANCHES (ex.: develop em DEV, qas em QAS)

Modelos de disparo

• Modelo A (recomendado): CI chama cada servidor explicitamente.
• simples, controle total, facil auditoria.
• Modelo B: um orchestrator central chama servidores em lote.
• util quando quantidade de hosts crescer.

Estrategia de rollout

• Sequencial por servidor (mais seguro): 1. deploy dev-01; 2. validar; 3. deploy dev-02; 4. validar.
• Paralelo (mais rapido) apenas apos maturidade operacional.

8) Integracao CI/CD

Gatilho recomendado

• Workflow para develop: 1. validar/testar; 2. build/push imagens; 3. chamar Deploy Agent em DEV.

Exemplo de chamada no CI (conceitual)

curl -X POST "https://deploy.dev-01.interno/v1/deploy" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${DEPLOY_API_KEY}" \
  -d '{
    "user": "github-actions",
    "service": "",
    "branch": "develop",
    "environment": "dev"  // ou "qas"
  }'

Segredos no CI

• DEPLOY_API_KEY_DEV_01
• DEPLOY_API_KEY_DEV_02
• DEPLOY_URL_DEV_01
• DEPLOY_URL_DEV_02

9) Observabilidade e Auditoria

Logs estruturados (JSON)

Campos obrigatorios:

• timestamp
• request_id
• user
• server
• environment
• branch
• service
• step
• status
• duration_ms
• error_code/error_message (quando falha)

Monitoracao minima

• Contador de deploys por status (success/fail).
• Duracao media de deploy.
• Numero de locks por concorrencia.
• Ultimo deploy por servidor.

10) Rollback e Recuperacao

Rollback tecnico imediato

Quando healthcheck falhar apos deploy:

1. Registrar falha.
2. Tentar reiniciar stack uma vez.
3. Se falhar novamente: - voltar para tag anterior de imagens (ou commit anterior); - docker compose up -d; - validar healthchecks.
4. Emitir alerta.

Politica

• Em ambiente de teste, rollback automatico pode ser habilitado apos fase piloto.
• Em fase inicial, usar rollback assistido (manual com comando guiado).

11) Requisitos de Infra

Servidor

• Linux com Docker + Docker Compose plugin.
• Acesso ao repositorio Git/submodulos.
• Python 3.11+.
• Usuario de sistema dedicado para deploy (ecosif-deploy).
• Permissao restrita ao diretorio do projeto.

Rede

• Endpoint acessivel apenas por rede interna/VPN.
• Firewall liberando apenas origem do CI e administradores.

12) Plano de Implantacao em Fases

Fase 0 - Preparacao (1 dia)

• Ajustar update.sh para modo nao interativo (--yes).
• Definir allowlist de servicos.
• Criar chave de API por servidor.

Fase 1 - Piloto em 1 servidor DEV (1-2 dias)

• Subir Deploy Agent com systemd.
• Integrar CI para chamar endpoint de 1 host.
• Validar lock, timeout, logs e healthchecks.

Fase 2 - Expansao para varios DEV (1-2 dias)

• Replicar servico nos demais servidores.
• Deploy sequencial via CI.
• Consolidar auditoria.

Fase 3 - Harden e padronizacao (2-4 dias)

• HMAC + anti-replay.
• Dashboard de monitoracao.
• Rollback automatico controlado.
• Playbook operacional final.

13) Criterios de Pronto para Uso ("sem dor")

Para considerar o servico pronto:

• Deploy por endpoint funciona em todos os servidores alvo.
• Nao ha deploy concorrente (lock validado).
• Todas as falhas retornam erro claro e auditavel.
• Healthcheck pos-deploy obrigatorio.
• Tempo total de deploy dentro de SLO definido.
• Processo de rollback documentado e testado.
• Chaves/segredos nao aparecem em log.

14) Riscos e Mitigacoes

• Risco: chamada maliciosa ao endpoint.
• Mitigacao: rede interna + API key/HMAC + allowlist.
• Risco: comando com injecao via service.
• Mitigacao: whitelist estrita + subprocess sem shell.
• Risco: deploy duplo simultaneo.
• Mitigacao: lockfile global.
• Risco: ambiente inconsistente entre servidores.
• Mitigacao: configuracao versionada e checklist unico.
• Risco: deploy sem visibilidade.
• Mitigacao: logs estruturados + request_id + alerta.

15) Decisoes Recomendadas para o Projeto ECOSIF

• Usar Deploy Agent Python (FastAPI) por servidor de teste.
• Integrar gatilho de deploy no pipeline develop.
• Reaproveitar scripts existentes em ecosif-structure/scripts.
• Comecar com API key e evoluir para HMAC.
• Rollout sequencial por servidor ate estabilizar.

16) Checklist de Execucao (Resumo)

Status implementação DEV (deploy-agent/ + workflow hub): concluído no código.
Itens de rede/TLS e rollback em servidor específico: revalidar por ambiente.

• [x] update.sh com --yes e retorno de erro consistente.
• [x] Deploy Agent com auth, lock, timeout e logs.
• [x] systemd service + restart automatico (unit documentada / ops).
• [ ] endpoint protegido por rede e TLS (por servidor).
• [x] CI chamando endpoint com segredo (deploy-dev-from-root.yml + #publish).
• [x] healthchecks e auditoria por request (pipeline async + verify).
• [ ] rollback tecnico validado em teste (por ambiente).

Status deste documento: especificacao implementada de forma faseada em DEV; promover com cautela a QAS/prod.