Pular para conteúdo

Deploy Kubernetes de producao

Este documento descreve a preparacao e a operacao do ambiente flow-prd. Produção já estava ativa no cluster na conferência de 14/10/2026. As seções de preparação inicial, bootstrap e virada de domínio são referências históricas; não reaplicá-las como parte de cada release. Para rotina, seguir publicação, deploy, verificação e rollback de aplicação conforme a pipeline.

Os manifests podem ser revisados e mergeados sem implantar workloads. O primeiro deploy permanece bloqueado ate que PRODUCTION_DEPLOY_ENABLED=true seja configurado no ambiente protegido production do GitLab.

Arquitetura e isolamento

  • namespace: flow-prd;
  • URL publica: https://flow.ecomsmart.com.br;
  • overlay: deploy/kubernetes/overlays/production;
  • PostgreSQL 16 interno em merchants-db.flow-prd.svc.cluster.local;
  • PVC de 20 GiB com tres replicas Longhorn e politica Retain;
  • kubeconfig exclusivo e limitado ao namespace;
  • secrets exclusivos de producao;
  • serializacao de deploy e rollback pelo resource_group flow-prd;
  • imagens imutaveis com tags formais X.Y.Z e Git tags vX.Y.Z;
  • PVCs dos StatefulSets retidos quando o StatefulSet for removido ou reduzido;
  • duas replicas para landing, painel, gateway e frontend-entrypoint, protegidas por PodDisruptionBudgets.

Uma réplica PostgreSQL adicional foi observada no cluster em 14/10/2026, mas não está definida neste overlay. Seu gerenciamento, failover e backups precisam ser confirmados com a infraestrutura antes de tratá-la como alta disponibilidade.

Redis, MinIO e Weaviate continuam com uma replica. Isso preserva o modelo ja validado em HML, mas nao representa alta disponibilidade desses componentes. Backup e restauracao devem estar validados antes da liberacao do primeiro deploy.

Preparacao pelo administrador do cluster

O administrador deve aplicar uma unica vez:

kubectl apply -f deploy/kubernetes/bootstrap/gitlab-deployer-production-rbac.yaml

Depois, deve gerar um kubeconfig para o ServiceAccount gitlab-deployer do namespace flow-prd. Esse kubeconfig nao deve possuir permissoes em outros namespaces e sera armazenado no GitLab como variavel File.

O manifesto concede somente os recursos usados pelo deploy dentro de flow-prd. Ele nao cria ClusterRole nem ClusterRoleBinding.

Variaveis do GitLab

Cadastre em Settings > CI/CD > Variables. Todas devem ser protegidas e ter escopo de ambiente production quando a edicao do GitLab permitir:

Variavel Tipo Valor inicial
KUBE_CONFIG_PRODUCTION File kubeconfig limitado a flow-prd
K8S_PRODUCTION_SECRETS File copia preenchida de production.env.example
KUBE_CONTEXT_PRODUCTION Variable opcional, contexto do kubeconfig
PRODUCTION_DEPLOY_ENABLED Variable false durante a preparacao
PRODUCTION_DATABASE_BOOTSTRAP_ENABLED Variable false; habilitar apenas para criar o banco inicial
PRODUCTION_DATABASE_READY Variable false ate restaurar e validar o banco
DEPLOY_PRODUCTION_INGRESS Variable false antes da virada de DNS
VERIFY_PRODUCTION_PUBLIC_HEALTH Variable false antes da virada de DNS

K8S_REGISTRY_USER e K8S_REGISTRY_PASSWORD tambem precisam estar disponiveis para o ambiente de producao. Nao copie automaticamente secrets de staging.

Em Settings > CI/CD > Protected environments, proteja production e restrinja o deploy aos Maintainers responsaveis. Se a edicao oferecer approvals, exija ao menos uma aprovacao adicional.

Checklist antes de habilitar

  1. Executar production_access_check em uma pipeline manual da main.
  2. Aplicar a StorageClass de producao e executar o bootstrap do PostgreSQL.
  3. Gerar um dump consistente da VPS, restaurar e validar no cluster.
  4. Executar production_database_access_check.
  5. Confirmar backup externo e um procedimento de restauracao do PostgreSQL.
  6. Confirmar backup dos volumes de MinIO e Weaviate.
  7. Confirmar que o banco e as integracoes de producao nao apontam para HML.
  8. Revisar os efeitos das migrations pendentes.
  9. Confirmar capacidade do cluster para as novas replicas e volumes.
  10. Manter o DNS atual durante o primeiro deploy sem trafego publico.
  11. Somente entao definir PRODUCTION_DATABASE_READY=true e PRODUCTION_DEPLOY_ENABLED=true.

PostgreSQL de producao

Um administrador do cluster aplica uma unica vez a StorageClass com retencao:

kubectl apply -f deploy/kubernetes/bootstrap/flow-prd-storage-class.yaml

Depois, com PRODUCTION_DATABASE_BOOTSTRAP_ENABLED=true, execute manualmente production_database_bootstrap na main. O job cria apenas o Secret, Services, StatefulSet e PVC do banco. Ele nao restaura dados, nao roda migrations da aplicacao e nao inicia os demais workloads.

Mantenha PRODUCTION_DATABASE_READY=false ate concluir a restauracao descrita em production-database-migration.md. Ao terminar o bootstrap, retorne PRODUCTION_DATABASE_BOOTSTRAP_ENABLED=false.

As tres replicas Longhorn protegem os blocos contra perda de um disco ou no, mas o PostgreSQL continua com uma unica instancia. Isso permite reagendamento com o mesmo volume; nao representa alta disponibilidade do processo e nao substitui backup externo.

Primeiro deploy

  1. No modo trunk atual, abra um MR de qualquer branch para main com título SemVer válido. No modo promotion, somente develop origina esse MR.
  2. Aguarde testes, revisao e merge.
  3. No modo trunk, confirme primeiro flow_build_all_images verde para o SHA integrado da main. Depois confira que publish_production_version publicou a Git tag vX.Y.Z e as imagens correspondentes com a tag X.Y.Z.
  4. Execute manualmente deploy_production.
  5. O job aplica infraestrutura, executa a migration, aplica as aplicacoes e valida o gateway dentro do cluster.
  6. verify_production_stability inicia cinco minutos depois e verifica replicas, imagens, reinicios e o health interno.

O Ingress nao e aplicado enquanto DEPLOY_PRODUCTION_INGRESS=false.

Virada de dominio

Depois de validar os workloads sem trafego publico:

  1. defina DEPLOY_PRODUCTION_INGRESS=true;
  2. execute novamente deploy_production para aplicar Ingress e Certificate;
  3. confirme certificado valido e endereco do Ingress;
  4. altere Cloudflare/DNS de flow.ecomsmart.com.br para o Ingress do cluster;
  5. valide /health, /, /login, onboarding e APIs;
  6. defina VERIFY_PRODUCTION_PUBLIC_HEALTH=true.

Nao remova imediatamente o destino legado. Mantenha-o como contingencia ate a nova publicacao completar a janela de observacao.

Rollback de aplicacao

Inicie uma pipeline manual da main informando:

ROLLBACK_IMAGE_TAG=X.Y.Z

Execute rollback_production. O job exige a tag formal da imagem, reaplica as imagens, aguarda os rollouts e executa smoke test interno. Ele deliberadamente nao reverte migrations do banco; portanto a versao escolhida precisa ser compativel com o schema atual.

Rollback destrutivo de banco nao e automatizado. Ele exige backup, plano especifico para a migration e janela de manutencao aprovada.