CI/CD e Kubernetes do EcomSmart Flow¶

Este é o guia operacional do fluxo que leva uma alteração do Merge Request até os ambientes de homologação e produção. Ele também registra os controles de segurança, o rollback e os procedimentos operacionais.

Nunca coloque tokens, senhas, kubeconfigs ou o conteúdo real dos arquivos de secrets neste documento ou no repositório.

Estado atual¶

Situação conferida em 14/10/2026 (não é monitoramento em tempo real):

Item	Situação
Repositório principal	`gitlab.ecomsmart.com.br/ecomsmart/flow`
Homologação	desligada para separar dados e credenciais; namespace previsto `flow-hml`
URL de homologação	`https://flow-hml.ecomsmart.com.br`
Build de imagens	runner dedicado `flow-build` operacional
Registry	`registry.ecomsmart.com.br/ecomsmart/flow`
Release de staging	automática depois de merge na `develop`
Deploy de staging	manual, com aprovação pelo botão do job
Produção Kubernetes	ativa no namespace `flow-prd`
Ambiente anterior	`ecomsmart-staging`: histórico de migração; inventariar antes de reutilizar

Não reativar HML com as credenciais antigas. Consulte a preparação da homologação. Os procedimentos de staging abaixo pressupõem que o isolamento esteja concluído.

Visão geral¶

O modo atual é RELEASE_WORKFLOW=trunk: a entrega não depende de HML.

MR de qualquer branch para main
  -> valida título, testes e revisão
  -> merge na main
  -> testes do commit integrado
  -> build das imagens com o SHA da main
  -> release de produção baseada no título do MR
  -> deploy_production manual
  -> verify_production_stability

O roteiro abaixo descreve o caminho staging/promotion, mantido para quando a homologação estiver isolada. Não é necessário executá-lo no modo trunk:

MR para develop
  -> valida título
  -> executa testes
  -> valida manifests quando houver alteração Kubernetes
  -> revisão e merge

Push do merge na develop
  -> executa testes novamente sobre o commit definitivo
  -> constrói e publica as imagens com CI_COMMIT_SHA
  -> promove as imagens para uma versão staging
  -> cria a Git tag de staging
  -> aguarda aprovação manual de deploy

Deploy manual
  -> atualiza secrets do namespace
  -> garante Redis, MinIO e Weaviate
  -> executa migrations
  -> atualiza aplicações
  -> espera os rollouts
  -> executa smoke test interno
  -> agenda verificacao de estabilidade para cinco minutos depois

O mesmo conjunto de imagens é promovido no Registry sem rebuild. Isso evita que staging e produção recebam binários diferentes para o mesmo código.

Guias por responsabilidade¶

O procedimento curto para implementar uma alteração e abrir um Merge Request fica em fluxo-desenvolvedor.md. Ele é o documento que deve ser entregue ao time de desenvolvimento.

Este documento permanece destinado aos responsáveis por CI/CD e infraestrutura: build, Registry, versões, GitLab, Kubernetes, deploy, rollback e produção.

O contrato dos logs, a correlação de requisições e o limite entre aplicação e infraestrutura estão em observabilidade-e-logs.md.

O que aparece nas pipelines¶

Merge Request¶

release_title_policy: valida título, origem e destino do MR;
python_unit_tests: três shards paralelos cobrindo sete módulos Python;
release_versioning_tests: aparece quando a implementação de versões muda;
kubernetes_manifests: aparece quando CI/CD ou Kubernetes muda.
docs_build: valida o site quando a documentação/configuração muda.
panel_unit_tests: testes e build do frontend quando o painel muda;
panel_assets_tests: regressão do Nginx e verificação de assets quando esses arquivos mudam.

kubernetes_manifests apenas renderiza YAML com Kustomize e verifica a quantidade esperada de recursos. Ele não usa kubeconfig e não altera o cluster.

Merge concluído na `develop`¶

Este é o canal staging opcional, não uma etapa obrigatória do modo trunk.

repete os testes no commit definitivo criado pelo merge;
flow_build_all_images constrói e publica dez imagens;
publish_staging_version promove as imagens e cria a tag;
deploy_staging fica aguardando execução manual;
verify_staging_stability roda cinco minutos depois de um deploy concluído.

Os testes são repetidos porque o artefato deve corresponder exatamente ao commit integrado na develop, e não apenas à ponta anterior da branch do desenvolvedor.

Merge concluído na `main` em trunk¶

testes do commit integrado;
flow_build_all_images: build oficial com o SHA desse commit;
publish_production_version: depende do build e cria a versão formal;
deploy_production: aprovação manual mantida;
verify_production_stability: conferência após o deploy.

Quando RELEASE_WORKFLOW=promotion, produção volta a aceitar somente MRs de develop e reaproveita suas imagens, sem build na main. Veja versionamento para coordenar essa troca.

Pipeline manual de manutenção¶

Em Build > Pipelines > New pipeline, selecione uma branch protegida. Nessa pipeline ficam disponíveis, sem execução automática:

database_access_check: confirma uma consulta de leitura no PostgreSQL;
kubernetes_access_check: confirma contexto, API e permissão no namespace;
kubernetes_diagnostics: coleta workloads, eventos e logs para diagnóstico;
kubernetes_bootstrap: reaplica namespace e RBAC iniciais;
jobs manuais de contingência para build, release e deploy.

Não execute kubernetes_bootstrap como tentativa genérica de corrigir um deploy. Ele existe para preparação inicial ou reparação consciente do RBAC.

Build e Registry¶

O runner de projeto flow-build usa executor Kubernetes. O gerente permanece no namespace gitlab-runner-flow e cria um pod efêmero para cada job. Ele não é uma VPS separada e não possui permissão de deploy em flow-hml ou flow-prd.

O build usa BuildKit rootless, executa uma imagem por vez e publica todas com a tag imutável CI_COMMIT_SHA. As imagens promovidas em conjunto estão listadas em scripts/release/images.txt.

Para verificar o runner no cluster:

kubectl -n gitlab-runner-flow get pods -o wide
kubectl -n gitlab-runner-flow logs deployment/gitlab-runner-flow --tail=100

Detalhes de instalação e limites estão em deploy/kubernetes/runner/README.md.

Versões e tags¶

Uma release de staging possui dois identificadores relacionados:

Git tag:    v0.0.3-staging.70
Image tag:   0.0.3-staging.70

O prefixo v existe somente na Git tag. Todas as imagens de uma release recebem a mesma image tag. As imagens também continuam disponíveis pelo SHA de origem.

As tags podem ser vistas em Code > Tags. As imagens podem ser vistas em Deploy > Container Registry.

O job de publicação é idempotente: repetir o job para o mesmo commit não cria outra versão.

Configuração do GitLab¶

Proteções do repositório¶

proteja develop e main;
exija Merge Request para alterações nessas branches;
proteja o padrão de tags v*;
em Settings > CI/CD > Job token permissions, permita push do job token;
limite alterações das variáveis a Maintainers;
em Settings > CI/CD > Protected environments, proteja staging e permita deploy somente para Maintainers.

Variáveis¶

Chave	Tipo	Protegida	Observação
`ENABLE_AUTOMATIC_RELEASES`	Variable	sim	valor `true`; não é segredo
`RELEASE_WORKFLOW`	Variable	sim, se cadastrada	padrão YAML `trunk`; override `promotion` com escopo `*` para retomar HML
`KUBE_CONFIG_STAGING`	File	sim	kubeconfig limitado a `flow-hml`
`KUBE_CONTEXT_STAGING`	Variable	sim	opcional quando o arquivo tem um contexto
`K8S_STAGING_SECRETS`	File	sim	variáveis reais da aplicação
`K8S_REGISTRY_USER`	Variable	sim	Deploy Token com `read_registry`
`K8S_REGISTRY_PASSWORD`	Variable	sim	senha do Deploy Token; ocultar/mascarar
`DEPLOY_INGRESS`	Variable	sim	`true` depois de validar DNS, nginx e cert-manager

Deixe Expand variable reference desmarcado para credenciais. Use Masked and hidden quando o formato do valor for aceito pelo GitLab. Variáveis do tipo File com conteúdo multilinha podem não atender aos requisitos de mascaramento; nesse caso, mantenha-as protegidas e restrinja Maintainers.

DEPLOY_IMAGE_TAG não precisa ser uma variável permanente. Ela é usada como parâmetro temporário em rollback ou contingência.

Deploy de staging¶

Depois que flow_build_all_images e publish_staging_version estiverem verdes:

abra a pipeline do merge na develop;
confira a versão criada no log de publish_staging_version;
execute manualmente deploy_staging;
acompanhe migrations, rollouts e smoke test;
aguarde verify_staging_stability, iniciado automaticamente cinco minutos depois, sem ocupar runner durante a espera;
abra https://flow-hml.ecomsmart.com.br em janela anônima;
valide landing, login, painel, onboarding e integrações afetadas.

O deploy aplica as fases nesta ordem:

Secrets de aplicação e credencial de pull do Registry;
PostgreSQL interno, apenas em produção e somente depois do bootstrap;
Redis, MinIO, buckets e Weaviate;
migrations no PostgreSQL do ambiente;
aplicações e gateway;
verificação de rollout de cada Deployment;
teste interno de health, HTML de login, JavaScript/CSS e 404 de asset inexistente;
a mesma verificação pelo domínio público quando habilitada.

O job atrasado confirma novamente as réplicas, a tag das imagens, reinicializações dos containers e o health check público. Se um serviço degradar depois do rollout, a pipeline fica vermelha com o estado dos pods e os eventos recentes.

O overlay atual de HML espera PostgreSQL externo e ainda não provisiona seu próprio banco. Preparar um destino exclusivo antes de reativar. Produção usa o StatefulSet merchants-db. O bootstrap e a restauração iniciais estão documentados no histórico de migração; não são etapas a repetir em cada deploy.

Verificação e logs¶

Com acesso ao cluster:

kubectl -n flow-hml get deployments,statefulsets,pods,jobs,ingress
kubectl -n flow-hml get events --sort-by=.lastTimestamp
kubectl -n flow-hml logs deployment/flow-gateway --tail=100
kubectl -n flow-hml logs deployment/frontend-entrypoint --tail=100

Para acompanhar um componente específico:

kubectl -n flow-hml rollout status deployment/NOME --timeout=10m
kubectl -n flow-hml describe deployment/NOME
kubectl -n flow-hml logs deployment/NOME --all-containers=true --tail=200

Sem acesso local ao cluster, inicie uma pipeline manual na develop e execute kubernetes_diagnostics.

Rollback de staging¶

Escolha uma image tag conhecida em Deploy > Container Registry ou remova o prefixo v de uma Git tag de staging.

Exemplo:

Git tag: v0.0.2-staging.62
DEPLOY_IMAGE_TAG: 0.0.2-staging.62

Depois:

abra Build > Pipelines > New pipeline;
selecione develop;
adicione DEPLOY_IMAGE_TAG com a versão anterior;
crie a pipeline;
não execute build nem publicação de versão;
execute somente deploy_staging;
valide rollouts, health check e comportamento funcional.

Esse rollback reaplica também o job de migrations da versão escolhida. Se uma release introduzir migration destrutiva ou incompatível com versões anteriores, o rollback precisa de um plano específico de banco antes da execução.

Contingência de build¶

Se o runner dedicado estiver indisponível, altere temporariamente ENABLE_AUTOMATIC_RELEASES para false. Em uma estação autenticada no Registry:

git switch develop
git pull --ff-only origin develop
$tag = (git rev-parse HEAD).Trim()
./deploy/kubernetes/scripts/build-images.ps1 -Tag $tag -Push

Em seguida, inicie uma pipeline manual na develop, execute publish_staging_version e, após a publicação, deploy_staging. Reative a automação somente quando o runner estiver saudável.

DNS e HTTPS de homologação¶

O hostname flow-hml.ecomsmart.com.br deve permanecer com proxy da Cloudflare ativo e apontar para a entrada pública do Ingress. No cluster, o overlay espera:

IngressClass nginx;
ClusterIssuer letsencrypt-prod;
Secret TLS flow-hml-tls;
namespace flow-hml.

Uma falha de DNS, certificado ou proxy deve ser investigada separadamente dos pods. Antes de alterar o cluster, confira DNS, status do certificado e o Ingress.

Segurança operacional¶

nunca versione deploy/kubernetes/secrets/staging.env;
nunca cole tokens em commits, logs, documentação ou comandos persistentes;
use Deploy Token somente com read_registry para os pods;
mantenha kubeconfig limitado ao namespace do ambiente;
não execute workloads simultâneos em flow-hml e no namespace legado quando ambos consumirem o mesmo banco, filas ou integrações;
não remova PVCs durante investigação ou rollback;
não use latest para deploy;
não aplique os manifests de staging em flow-prd.

Credenciais compartilhadas fora do gerenciador de secrets devem ser rotacionadas. Antes de tratar HML como ambiente isolado, confirme que banco, webhooks, telefones e integrações externas usam contas de teste. Se algum deles for compartilhado com produção, documente os efeitos permitidos e limite os testes aos lojistas autorizados.

Manutenção do Registry¶

Cada merge conserva uma tag SemVer e uma tag imutável com o SHA. Configure no GitLab uma política de limpeza para remover SHAs antigos que não estejam mais associados a releases em uso. Preserve sempre:

todas as tags vX.Y.Z e X.Y.Z de produção;
as versões de staging usadas para rollback;
a versão atualmente implantada em cada namespace;
um período de retenção suficiente para investigação.

Revise a seleção antes de habilitar exclusão automática. A limpeza do Registry não deve ser usada para remover uma imagem referenciada pelo Kubernetes.

Checklist de fechamento da homologação¶

pipeline de MR, build e release automática verdes;
deploy_staging e verify_staging_stability verdes;
todos os pods prontos e sem novas reinicializações;
certificado TLS válido e health check público respondendo;
login, painel, onboarding e integrações principais validados;
ambiente staging protegido no GitLab;
credenciais expostas rotacionadas;
isolamento de dados e integrações confirmado;
política de retenção do Registry definida;
data para revisar ou remover o namespace legado registrada;
rollback de uma versão testado em janela controlada.

Produção¶

O overlay, o RBAC limitado, os jobs de deploy e verificacao e o rollback de aplicacao estao descritos em docs/production-deployment.md. O deploy depende de PRODUCTION_DEPLOY_ENABLED e da conclusao do checklist de secrets, acesso, backup, restauracao e protecao do ambiente no GitLab.

Os secrets de staging nao devem ser reaproveitados automaticamente em producao.

Versão exibida no painel¶

O rodapé da barra lateral do painel mostra a versão realmente implantada, por exemplo Homologação · v0.1.0-staging.73. Ao manter o cursor sobre o texto, o painel também informa o SHA de origem e a data do deploy.

No staging, deploy-staging.sh cria ou atualiza o ConfigMap ecomsmart-release-info no namespace flow-hml. O arquivo release.json desse ConfigMap é montado no contêiner do painel em /usr/share/nginx/html/runtime/release.json. A resposta é entregue com Cache-Control: no-store, evitando que o navegador continue mostrando uma versão anterior depois de um deploy ou rollback.

O campo version usa a imagem selecionada por RELEASE_IMAGE_TAG, DEPLOY_IMAGE_TAG ou CI_COMMIT_SHA, na mesma precedência usada pelo deploy. O campo commit_sha usa SOURCE_IMAGE_TAG quando a release foi promovida pelo pipeline. Em execuções locais, o painel usa os metadados de desenvolvimento em modules/panel/public/runtime/release.json.