Gerenciamento de Tenants¶

Guia passo a passo para criar, manter e remover tenants nos ambientes HML e NOX.

Criar Novo Tenant¶

Banco Compartilhado (Shared)¶

Para tenants que compartilham o banco de dados existente:

1. Acesse GitHub Actions do repositório ads-oci-infra-pipeline
2. Execute o workflow "01 Tenant → Criar Nova APP Config" com os inputs:

1. O workflow:

   • Cria arquivo .hcl em config/{env}/tenants/
   • Copia secrets do Vault do tenant de origem
   • Abre PR no repositório de infra com labels new_tenant, tenant=X, env=Y
   • Dispara preview do Terraform
   • Abre PR no ads-tenants-config com configs de app

2. Revise e aprove o PR de infra → merge → deploy

3. Revise e aprove o PR de tenants-config → merge → ArgoCD sync

Banco Dedicado (Dedicated)¶

Para tenants que precisam de banco de dados próprio:

Passo 0 — Infraestrutura do banco:

1. Execute workflow "00 Tenant → Criar Novo Dedicado":

1. Revise PR → merge → deploy cria infraestrutura do banco (PostgreSQL 16 + 9.6)

Passo 1 — Config de aplicação:

1. Execute workflow "01 Tenant → Criar Nova APP Config" com database_type: dedicated
2. Mesmo fluxo do banco compartilhado a partir daqui

flowchart TB
    A{Tipo de Banco?}
    A -->|Shared| B[01: Criar APP Config]
    A -->|Dedicated| C[00: Criar Dedicado]
    C --> D[PR Infra → Merge → Deploy DB]
    D --> B
    B --> E[PR Infra + PR Tenants Config]
    E --> F[Merge Infra PR]
    F --> G[Merge Tenants Config PR]
    G --> H[ArgoCD Sync Automático]

Manutenção de Tenant¶

Atualizar Versão de Aplicação¶

HML (automático): O merge pipeline atualiza automaticamente todos os tenants HML.

NOX (manual):

1. Edite tenants/oci/nox/{tenant}/{app}/values.yaml: yaml image: tag: v8.0.0@sha256:abc123...
2. Commit e push para main
3. ArgoCD sincroniza automaticamente

Alterar Versão do Chart¶

Se uma nova versão do Helm chart precisar ser adotada:

1. Edite app-config.yaml do tenant/app: yaml chartVersion: 2.0.0
2. Commit e push para main

Bloquear Deploy Temporariamente¶

Para manutenções que exigem parar o auto-sync:

1. Execute workflow "02 Tenant → Desativar Auto-Sync":

   • Selecione o ambiente e tenant
   • O ApplicationSet será patcheado removendo o sync automático
   • Os deployments do tenant serão deletados

2. Realize a manutenção necessária

3. Execute workflow "03 Tenant → Re-Ativar Auto-Sync":

   • O ApplicationSet será restaurado com auto-sync
   • O ArgoCD recriará os deployments

Remover Tenant¶

Remove do ads-tenants-config¶

1. Delete o diretório do tenant: bash rm -rf tenants/oci/{env}/{tenant}/
2. Commit e push para main
3. O ArgoCD detecta a remoção e com prune: true deleta automaticamente os recursos do cluster

Remover do ads-oci-infra-pipeline¶

1. Delete o arquivo .hcl do tenant em config/{env}/tenants/
2. Crie PR → preview → merge → Terraform destroy dos recursos de infra

Cancelar Criação de Tenant¶

Se um PR de criação de tenant for fechado sem merge:

O workflow cleanup-tenant-config.yml executa automaticamente:

1. Encontra e fecha o PR relacionado no ads-tenants-config
2. Deleta os secrets criados no Vault (identificados pela metadata pr_number)
3. Comenta resumo de cleanup no PR

Nenhuma ação manual necessária — o cleanup é automático.

Vault e Secrets¶

Cada tenant possui secrets no HashiCorp Vault organizados por:

secret/{ENV}/tenants/{tenant}/ ├── auth-api/ # Credenciais do banco, JWT secrets ├── is-core-api/ # Credenciais, configs de integração └── ...

Na criação do tenant, os secrets são copiados do tenant de origem (source_tenant) via pipeline backup → transform → restore:

1. Backup dos secrets do tenant de origem
2. Transformação de paths e valores (substituição de nomes)
3. Restore no novo mount do tenant
4. Adição de metadata de tracking (created_by, managed_by, pr_number)