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¶

push em develop (ou branch de ambiente).
CI valida build e publica imagens.
CI chama endpoint do Deploy Agent no(s) servidor(es) de teste.
Agent valida autenticacao/autorizacao.
Agent executa pipeline local:
atualizar git/submodulos;
atualizar servico alvo (ou todos);
reiniciar servico(s);
validar health;
registrar auditoria.
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¶

Receber request e validar schema.
Autenticar user e key.
Validar service na allowlist (se informado).
Adquirir lock global de deploy.
Registrar auditoria started.
Executar:
etapa A: atualizar git/submodulos;
etapa B: atualizar servico(s);
etapa C: reiniciar servico(s);
etapa D: validar healthchecks.
Registrar auditoria finished com resultado.
Liberar lock.
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):
deploy dev-01;
validar;
deploy dev-02;
validar.
Paralelo (mais rapido) apenas apos maturidade operacional.

8) Integracao CI/CD¶

Gatilho recomendado¶

Workflow para develop:
validar/testar;
build/push imagens;
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:

Registrar falha.
Tentar reiniciar stack uma vez.
Se falhar novamente:
voltar para tag anterior de imagens (ou commit anterior);
docker compose up -d;
validar healthchecks.
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.