Referência de values de produção

Os values crm mantidos nesta página configuram a carga de trabalho de compatibilidade legada do Helm chart. O Midaz v4 faz deploy do CRM pelo Ledger unificado, não por essa carga de trabalho.

Esta é uma referência completa e anotada de values.yaml para deploys em produção. Copie, adapte os placeholders ao seu ambiente e faça o deploy.

Esta é uma configuração de referência. Você deve substituir todos os valores de placeholder (marcados com {...}) pelos dados reais da sua infraestrutura antes do deploy.

Como usar

Copie a configuração completa abaixo para um arquivo chamado values-production.yaml
Substitua todos os placeholders {...} pelos seus valores reais
Revise cada seção e ajuste os limites de recursos para a carga que você espera
Faça o deploy:

helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <version> \
  -n midaz \
  --create-namespace \
  -f values-production.yaml

Values completos de produção

A Ledger Settings API substitui as variáveis de ambiente obsoletas ACCOUNT_TYPE_VALIDATION e TRANSACTION_ROUTE_VALIDATION. Use PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings para configurar a validação contábil por ledger.

# =============================================================================
# Midaz Production Values Reference
# =============================================================================
# This file configures Midaz for a production Kubernetes environment with:
# - Unified Ledger service
# - External databases (PostgreSQL, MongoDB, RabbitMQ, Valkey/Redis)
# - Ingress with TLS
# - Observability enabled
# - CRM enabled
# - High availability with autoscaling
# =============================================================================

# -- Global name overrides
nameOverride: "midaz"
fullnameOverride: ""
namespaceOverride: "midaz"

# =============================================================================
# GLOBAL: External database bootstrap jobs
# =============================================================================
# These jobs run once on install to create databases, users, and permissions.
# Enable them when using external (non-bundled) databases.

global:
  # -- Bootstrap job for external PostgreSQL
  externalPostgresDefinitions:
    enabled: true
    connection:
      host: "{your-postgres-host}"       # e.g., "prod-postgres.example.com"
      port: "5432"
    postgresAdminLogin:
      # Recommended: use an existing Kubernetes Secret
      useExistingSecret:
        name: "{your-postgres-admin-secret}"  # Must contain DB_USER_ADMIN and DB_ADMIN_PASSWORD keys
      # Alternative: inline credentials (NOT recommended for production)
      # username: "postgres"
      # password: "{your-admin-password}"
    midazCredentials:
      useExistingSecret:
        name: "{your-midaz-credentials-secret}"  # Must contain DB_PASSWORD_MIDAZ key
      # Alternative: inline
      # password: "{your-midaz-password}"

  # -- Bootstrap job for external RabbitMQ
  externalRabbitmqDefinitions:
    enabled: true
    connection:
      protocol: "https"                   # Use "https" for production
      host: "{your-rabbitmq-host}"        # e.g., "prod-rabbitmq.example.com"
      port: "15672"                       # HTTP management port
      portAmqp: "5672"                    # AMQP port
    rabbitmqAdminLogin:
      useExistingSecret:
        name: "{your-rabbitmq-admin-secret}"  # Must contain RABBITMQ_ADMIN_USER and RABBITMQ_ADMIN_PASS
    appCredentials:
      useExistingSecret:
        name: "{your-rabbitmq-app-credentials}"  # Must contain RABBITMQ_DEFAULT_PASS and RABBITMQ_CONSUMER_PASS

# =============================================================================
# LEDGER: Unified service (recommended for new installations)
# =============================================================================
# The Ledger service combines onboarding and transaction into a single
# deployment. This is the recommended approach for all new installations.

ledger:
  enabled: true

  # -- High availability: start with 3 replicas
  replicaCount: 3

  image:
    repository: lerianstudio/midaz-ledger
    pullPolicy: IfNotPresent
    tag: ""  # Defaults to Chart.AppVersion; pin a specific version for production

  # -- Security context (non-root, read-only filesystem)
  securityContext:
    runAsGroup: 1000
    runAsUser: 1000
    runAsNonRoot: true
    capabilities:
      drop:
        - ALL
    readOnlyRootFilesystem: true

  # -- PodDisruptionBudget: ensure at least 2 pods during disruptions
  pdb:
    enabled: true
    minAvailable: 2
    maxUnavailable: 1

  # -- Rolling update with zero downtime
  deploymentUpdate:
    type: RollingUpdate
    maxSurge: 1
    maxUnavailable: 0

  service:
    type: ClusterIP
    port: 3002

  # -- Ingress with TLS
  ingress:
    enabled: true
    className: "{your-ingress-class}"     # e.g., "nginx", "alb", "traefik"
    annotations:
      # NGINX example:
      nginx.ingress.kubernetes.io/proxy-body-size: "10m"
      nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
      # AWS ALB example (uncomment if using ALB):
      # alb.ingress.kubernetes.io/scheme: internal
      # alb.ingress.kubernetes.io/target-type: ip
      # alb.ingress.kubernetes.io/group.name: "midaz"
    hosts:
      - host: "{your-midaz-api-domain}"   # e.g., "api.midaz.example.com"
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: "{your-tls-secret}"   # e.g., "midaz-api-tls"
        hosts:
          - "{your-midaz-api-domain}"

  # -- Resource limits for production
  # Adjust based on your workload. These are starting recommendations.
  resources:
    requests:
      cpu: "1000m"
      memory: "512Mi"
    limits:
      cpu: "2000m"
      memory: "2Gi"

  # -- Autoscaling
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70
    targetMemoryUtilizationPercentage: 80

  # -- Pod anti-affinity: spread across nodes for high availability
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - ledger
            topologyKey: kubernetes.io/hostname

  # -- External database configuration
  configmap:
    ENABLE_TELEMETRY: "true"
    # Auth Plugin (enable if using access management)
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_HOST: ""
    # Accounting Configuration
    # Managed via Ledger Settings API. See PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings
    # Request body: {"accounting": {"validateRoutes": true, "validateAccountType": true}}
    # -- PostgreSQL: Onboarding module
    DB_ONBOARDING_HOST: "{your-postgres-host}"
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_REPLICA_HOST: "{your-postgres-replica-host}"
    DB_ONBOARDING_REPLICA_USER: "midaz"
    DB_ONBOARDING_REPLICA_NAME: "onboarding"
    DB_ONBOARDING_REPLICA_PORT: "5432"
    # -- MongoDB: Onboarding module
    MONGO_ONBOARDING_URI: "mongodb"
    MONGO_ONBOARDING_HOST: "{your-mongodb-host}"
    MONGO_ONBOARDING_NAME: "onboarding"
    MONGO_ONBOARDING_USER: "midaz"
    MONGO_ONBOARDING_PORT: "27017"
    # -- PostgreSQL: Transaction module
    DB_TRANSACTION_HOST: "{your-postgres-host}"
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_REPLICA_HOST: "{your-postgres-replica-host}"
    DB_TRANSACTION_REPLICA_USER: "midaz"
    DB_TRANSACTION_REPLICA_NAME: "transaction"
    DB_TRANSACTION_REPLICA_PORT: "5432"
    # -- MongoDB: Transaction module
    MONGO_TRANSACTION_URI: "mongodb"
    MONGO_TRANSACTION_HOST: "{your-mongodb-host}"
    MONGO_TRANSACTION_NAME: "transaction"
    MONGO_TRANSACTION_USER: "midaz"
    MONGO_TRANSACTION_PORT: "27017"
    # -- Redis/Valkey
    REDIS_HOST: "{your-redis-host}:6379"
    # -- RabbitMQ
    RABBITMQ_URI: "amqps"                 # Use "amqps" for TLS, "amqp" without
    RABBITMQ_HOST: "{your-rabbitmq-host}"
    RABBITMQ_PORT_HOST: "5672"
    RABBITMQ_PORT_AMQP: "15672"
    RABBITMQ_DEFAULT_USER: "transaction"
    RABBITMQ_CONSUMER_USER: "consumer"
    RABBITMQ_TRANSACTION_ASYNC: "false"
    # -- Audit
    AUDIT_LOG_ENABLED: "true"             # Enable audit logging for production
    # -- Balance Sync Worker
    BALANCE_SYNC_BATCH_SIZE: "100"
    BALANCE_SYNC_FLUSH_TIMEOUT_MS: "1000"
    BALANCE_SYNC_POLL_INTERVAL_MS: "500"

  # -- Use existing Kubernetes Secrets (recommended)
  useExistingSecret: true
  existingSecretName: "midaz-ledger"
  # Create this secret manually before deploying:
  # kubectl create secret generic midaz-ledger \
  #   --from-literal=DB_ONBOARDING_PASSWORD='{password}' \
  #   --from-literal=DB_ONBOARDING_REPLICA_PASSWORD='{password}' \
  #   --from-literal=MONGO_ONBOARDING_PASSWORD='{password}' \
  #   --from-literal=DB_TRANSACTION_PASSWORD='{password}' \
  #   --from-literal=DB_TRANSACTION_REPLICA_PASSWORD='{password}' \
  #   --from-literal=MONGO_TRANSACTION_PASSWORD='{password}' \
  #   --from-literal=REDIS_PASSWORD='{password}' \
  #   --from-literal=RABBITMQ_DEFAULT_PASS='{password}' \
  #   --from-literal=RABBITMQ_CONSUMER_PASS='{password}' \
  #   -n midaz

  serviceAccount:
    create: true
    annotations: {}

# =============================================================================
# CRM: Customer Relationship Management
# =============================================================================

crm:
  enabled: true

  replicaCount: 2

  image:
    repository: lerianstudio/midaz-crm
    pullPolicy: IfNotPresent
    tag: ""  # Defaults to Chart.AppVersion

  securityContext:
    runAsGroup: 1000
    runAsUser: 1000
    runAsNonRoot: true
    capabilities:
      drop:
        - ALL
    readOnlyRootFilesystem: true

  pdb:
    enabled: true
    minAvailable: 1
    maxUnavailable: 1

  service:
    type: ClusterIP
    port: 4003

  ingress:
    enabled: true
    className: "{your-ingress-class}"
    hosts:
      - host: "{your-crm-api-domain}"     # e.g., "crm.midaz.example.com"
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: "{your-crm-tls-secret}"
        hosts:
          - "{your-crm-api-domain}"

  resources:
    requests:
      cpu: "200m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 80

  configmap:
    ENV_NAME: "production"
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_ADDRESS: ""
    MONGO_HOST: "{your-mongodb-host}"
    MONGO_NAME: "crm"
    MONGO_PORT: "27017"
    MONGO_USER: "midaz"

  useExistingSecret: true
  existingSecretName: "midaz-crm"
  # Create this secret manually before deploying:
  # kubectl create secret generic midaz-crm \
  #   --from-literal=LCRYPTO_HASH_SECRET_KEY='{generate-a-random-64-hex-string}' \
  #   --from-literal=LCRYPTO_ENCRYPT_SECRET_KEY='{generate-a-random-64-hex-string}' \
  #   --from-literal=MONGO_PASSWORD='{password}' \
  #   -n midaz

# =============================================================================
# BUNDLED DEPENDENCIES: All disabled (using external databases)
# =============================================================================
# In production, use managed database services (AWS RDS, Atlas, etc.)
# instead of bundled containers.

postgresql:
  enabled: false

mongodb:
  enabled: false

rabbitmq:
  enabled: false

valkey:
  enabled: false

# =============================================================================
# OBSERVABILITY
# =============================================================================

# -- Inject OTEL env vars into the ledger, crm and tracer deployments.
# The schema accepts ONLY `enabled`. The exporter endpoint is fixed at
# $(HOST_IP):4317, so this needs an OTLP collector on every node.
# To export elsewhere, set enabled: false and put
# OTEL_EXPORTER_OTLP_ENDPOINT in each component's configmap instead.
otel-collector-lerian:
  enabled: true

Não adicione external, extraEnvs, exporters ou opentelemetry-collector em otel-collector-lerian. O schema do chart é estrito e o helm install/helm upgrade falha com additional properties … not allowed. Você configura o roteamento do collector (processors, exporters, chaves de API) no chart do próprio collector, não aqui. Consulte Configurar a observabilidade.

O chart não traz templates de Grafana. Um bloco grafana: no seu arquivo de values não renderiza nada.

Decisões principais explicadas

Por que Ledger em vez de Onboarding + Transaction?

O serviço ledger unificado é a abordagem recomendada para todas as novas instalações. Ele combina os dois módulos em um único deployment, o que reduz o custo operacional:

Menos pods para gerenciar e monitorar
Configuração simplificada (um único configmap/secret)
Um único endpoint de ingress
Melhor uso de recursos
Vai se tornar a única opção em releases futuros

Por que bancos de dados externos?

Recomenda-se que deploys em produção usem serviços de banco de dados gerenciados para:

Backups automatizados e recuperação point-in-time
Alta disponibilidade com failover automático
Monitoramento e alertas integrados
Escala sem downtime da aplicação
Correções de segurança gerenciadas pelo provedor

Serviços gerenciados recomendados:

Dependência	AWS	GCP	Azure
PostgreSQL	Amazon RDS	Cloud SQL	Azure Database for PostgreSQL
MongoDB	Amazon DocumentDB ou MongoDB Atlas	MongoDB Atlas	Azure Cosmos DB (MongoDB API)
RabbitMQ	Amazon MQ	Autogerenciado no GKE	Autogerenciado no AKS
Redis/Valkey	Amazon ElastiCache	Memorystore	Azure Cache for Redis

Por que usar Secrets do Kubernetes em vez de senhas inline?

Senhas inline em values.yaml ficam visíveis no histórico de releases do Helm e podem ser commitadas no controle de versão. Usar useExistingSecret: true com Secrets do Kubernetes criados previamente:

Mantém as credenciais fora dos values do Helm
Permite a rotação sem upgrade do Helm
Integra com ferramentas de gestão de secrets (Vault, External Secrets Operator, Sealed Secrets)

Anti-affinity de pods

A regra podAntiAffinity distribui os pods do Ledger por nós diferentes, então a falha de um único nó não derruba o serviço inteiro.

Checklist antes do deploy

Criar os Secrets do Kubernetes

Crie todos os secrets necessários no namespace midaz antes de rodar helm install:

midaz-ledger (credenciais do banco de dados e do message broker)
midaz-crm (chaves de criptografia e senha do MongoDB)
otel-api-key (se você usa a telemetria da Lerian)

Configurar o DNS

Aponte seus domínios para o IP externo do ingress controller:

{your-midaz-api-domain} → IP do ingress
{your-crm-api-domain} → IP do ingress
{your-grafana-domain} → IP do ingress (apenas se você roda o Grafana de forma independente, já que este chart não renderiza nenhum)

Provisionar os certificados TLS

Use o cert-manager para o provisionamento automático de certificados ou crie manualmente os secrets TLS de cada domínio.

Verificar a conectividade com os bancos de dados

Garanta que seu cluster Kubernetes alcança todos os bancos de dados externos. Teste com:

kubectl run test-pg --rm -it --image=postgres:17 -- \
  psql -h {your-postgres-host} -U midaz -d onboarding -c "SELECT 1"

Revisar os limites de recursos

Ajuste os limites de CPU e memória conforme o volume de transações que você espera. Use os valores desta referência como ponto de partida para cargas moderadas.

Fazer o deploy

helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <version> \
  -n midaz \
  --create-namespace \
  -f values-production.yaml

Verificar o deploy

kubectl get pods -n midaz -o wide
kubectl get ingress -n midaz
helm list -n midaz

Recursos relacionados

Usar o Helm - Guia de instalação completo com todas as opções de configuração
Fazer upgrade do Midaz - Procedimentos de upgrade passo a passo
Solução de problemas - Diagnóstico de problemas comuns de deploy
Desinstalar o Midaz - Procedimentos de limpeza
Código-fonte do Helm chart - values.yaml completo com todos os parâmetros disponíveis

Introdução

Midaz

Outros produtos

Referência de values de produção

Como usar

Values completos de produção

Decisões principais explicadas

Por que Ledger em vez de Onboarding + Transaction?

Por que bancos de dados externos?

Por que usar Secrets do Kubernetes em vez de senhas inline?

Anti-affinity de pods

Checklist antes do deploy

Recursos relacionados

​Como usar

​Values completos de produção

​Decisões principais explicadas

​Por que Ledger em vez de Onboarding + Transaction?

​Por que bancos de dados externos?

​Por que usar Secrets do Kubernetes em vez de senhas inline?

​Anti-affinity de pods

​Checklist antes do deploy

​Recursos relacionados

Como usar

Values completos de produção

Decisões principais explicadas

Por que Ledger em vez de Onboarding + Transaction?

Por que bancos de dados externos?

Por que usar Secrets do Kubernetes em vez de senhas inline?

Anti-affinity de pods

Checklist antes do deploy

Recursos relacionados