Variáveis de ambiente

O Lerian STA é o trilho de propriedade da Lerian que transmite e recebe arquivos com o hub STA do BACEN. Você define essas variáveis no momento do deploy. Um restart do serviço as torna efetivas. Todo serviço Go da Lerian compartilha uma base universal: servidor, armazenamentos de dados, telemetria e autenticação de plugin. A referência de configuração BYOC documenta essa base uma única vez. Esta página cobre as variáveis específicas do Lerian STA. Para instalar ou atualizar o Lerian STA, consulte o README do chart do Lerian STA. Nas tabelas abaixo, a coluna Padrão / Obrigatório mostra o valor padrão. Um qualificador em negrito marca uma variável que você deve definir, como Obrigatório ou Obrigatório em produção. — significa que não há padrão. Uma variável marcada como Sensível carrega credencial ou material de chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Nunca faça commit de um valor. Um valor que não pode ser lido como o tipo da sua variável interrompe o boot. Uma variável booleana aceita apenas true ou false.

Serviço e runtime

Variável	Padrão / Obrigatório	Descrição
`SERVER_ADDRESS`	`:4028`	Endereço HTTP principal de escuta. As sondas de liveness, readiness, metrics e version se ligam a essa mesma porta.
`DEPLOYMENT_MODE`	`local`	Modelo de deploy: `local`, `byoc` ou `saas`, em maiúsculas ou minúsculas. Outro valor interrompe o boot. Com `saas`, o boot falha quando uma conexão configurada com PostgreSQL, Redis, RabbitMQ, armazenamento de objetos ou os brokers de streaming não exige TLS.
`PLUGIN_AUTH_ENABLED`	Obrigatório	`true` ou `false`. Um valor vazio ou outro valor interrompe o boot. `true` ativa a autorização pelo Lerian Access Manager. O Lerian STA aceita `false` apenas quando `ENV_NAME` é `development`, `develop`, `dev`, `local` ou `test`, e `DEPLOYMENT_MODE` não é `saas`. Com `false`, cada requisição protegida ainda precisa de um bearer token que nomeia um principal, e o Lerian STA pula apenas a chamada ao Access Manager.
`PLUGIN_AUTH_HOST`	Obrigatório quando `PLUGIN_AUTH_ENABLED` é `true`	Endereço do Lerian Access Manager.
`SYSTEMPLANE_ENABLED`	`false`	Habilita a API administrativa de configuração em runtime do Systemplane sob o prefixo `/system` na porta principal. Desativada por padrão (modo apenas variável de ambiente).
`BACEN_ENVIRONMENT`	`homologation`	Seleciona o ambiente do STA do BACEN que toda chamada ao BACEN usa como alvo: `homologation` (homologação) ou `production` (produção). Um valor não reconhecido cai para `homologation`, para que uma stack fora de produção não consiga rotear tráfego para o serviço BACEN em produção.
`SCHEDULER_ENABLED`	`false`	Roda os jobs agendados do worker, incluindo os pollers de status de saída, a varredura de credenciais para rotações travadas e a exclusão de transferências canceladas e inconsistentes depois de 7 dias.

O Lerian STA expõe /health (liveness) e /readyz (readiness) na porta principal, além de /version e /metrics. Veja Health e readiness para o contrato da sonda.

Licença

Variável	Padrão / Obrigatório	Descrição
`LICENSE_FILE_PATH`	Obrigatório sem `LICENSE_KEY`	Caminho do arquivo de licença assinado que a Lerian emite. O Lerian STA verifica o arquivo localmente e não chama o serviço de licenças. Se o arquivo não licencia o Lerian STA, o boot falha. O Lerian STA não tenta usar `LICENSE_KEY` no lugar dele. O Lerian STA lê o arquivo de novo aproximadamente a cada hora, então um arquivo renovado entra em vigor sem restart. O arquivo contém a chave de licença, então guarde-o em um secret. No Kubernetes, monte esse Secret como um diretório, sem `subPath`, porque o Kubernetes não atualiza uma montagem `subPath`.
`LICENSE_KEY`	Obrigatório sem `LICENSE_FILE_PATH`	Chave de licença emitida pela Lerian. O Lerian STA a ignora quando `LICENSE_FILE_PATH` está definida. Sensível.
`ORGANIZATION_IDS`	Obrigatório	Escopo de organização que a licença cobre.

Transferências

Variável	Padrão / Obrigatório	Descrição
`TRANSFER_SCHEDULER_ENABLED`	`false`	Roda o loop do worker que envia as transferências de saída ao BACEN. Enquanto for `false`, o Lerian STA aceita e armazena novas transferências de saída, mas não envia nenhuma delas.
`TRANSFER_INBOUND_ENABLED`	`false`	Habilita o pipeline de transferência de entrada (baixado do BACEN). Não muda a exigência do bucket em produção, porque as transferências de saída também usam o bucket.
`TRANSFER_MAX_ATTEMPTS`	`5`	Tentativas que uma transferência de saída recebe antes que o Lerian STA a cancele, de 1 a 10. Chave de runtime: `sta.upload.max_attempts`.
`TRANSFER_TTL_HOURS`	`44`	Tempo de vida em tempo real de uma transferência de saída depois que o BACEN atribui seu protocolo, de 1 a 44 horas. Chave de runtime: `sta.upload.ttl_hours`.
`TRANSFER_MAX_FILE_SIZE_BYTES`	`5368709120`	Tamanho máximo do arquivo que uma nova transferência de saída referencia, em bytes (5 GiB).

Armazenamento de objetos

O Lerian STA persiste os bytes de transferência e os downloads de entrada em um armazenamento de objetos compatível com S3.

Variável	Padrão / Obrigatório	Descrição
`TRANSFER_OBJECT_STORAGE_BUCKET`	Obrigatório em produção	Bucket que guarda as duas direções de transferência. O boot em produção é recusado se estiver vazio, independentemente de as transferências de entrada estarem habilitadas.
`TRANSFER_S3_REGION`	`us-east-1`	Região do bucket de transferências.
`TRANSFER_S3_ENDPOINT`	—	Endpoint de um armazenamento compatível com S3, como o MinIO. Deixe sem definir para o AWS S3.
`TRANSFER_S3_PATH_STYLE`	`false`	Usa endereçamento path-style, que a maioria dos armazenamentos compatíveis com S3 exige.
`TRANSFER_INBOUND_MAX_FILE_SIZE_BYTES`	`5368709120`	Tamanho máximo de arquivo de entrada anunciado pelo BACEN, em bytes (5 GiB). Um valor `0` ou menor desabilita esse limite de admissão.
`TRANSFER_INBOUND_EXTRACT_MAX_EXPANSION_RATIO`	`100`	Proporção máxima entre o tamanho da entrada extraída e seu envelope ZIP entregue. Um valor `0` ou menor desabilita a verificação de proporção.
`TRANSFER_INBOUND_EXTRACT_MAX_EXTRACTED_BYTES`	`5368709120`	Tamanho máximo absoluto da única entrada ZIP extraída, em bytes (5 GiB). Um valor `0` ou menor desabilita esse limite.
`AWS_REGION`	—	Região do AWS KMS quando `MASTER_KEY_KMS_REGION` está vazio. Não configura o armazenamento de objetos.
`AWS_ACCESS_KEY_ID`	—	Chave de acesso para o armazenamento de objetos. Sensível. Deixe sem definir quando uma role IAM anexada fornece as credenciais.
`AWS_SECRET_ACCESS_KEY`	—	Chave secreta para o armazenamento de objetos. Sensível. Deixe sem definir quando uma role IAM anexada fornece as credenciais.

Criptografia envelope

O Lerian STA protege as credenciais de operador com criptografia envelope AES-GCM. Todo processo do Lerian STA precisa do material de chave mestra. Um valor ausente ou malformado aborta o boot.

Variável	Padrão / Obrigatório	Descrição
`MASTER_KEY_PROVIDER`	`envvar`	Origem da chave de criptografia envelope: `envvar` (chave lida de `MASTER_KEYS`) ou `aws-kms` (chave envolvida por um KMS de nuvem).
`MASTER_KEY_VERSION`	Obrigatório	Seleciona a versão de chave mestra atualmente ativa. Deve corresponder a uma versão presente em `MASTER_KEYS`.
`MASTER_KEYS`	Obrigatório	Pares `version:key` separados por vírgula. Sensível. Com `envvar`, cada valor é uma chave AES-256 de 64 caracteres hex: `version:<64-hex-key>`. Com `aws-kms`, cada valor é um ciphertext KMS em base64: `version:<base64-ciphertext>`, decifrado no processo. Obtenha-a a partir do seu gerenciador de segredos. Um valor ausente ou malformado aborta o boot.
`MASTER_KEY_KMS_KEY_ID`	Obrigatório se `aws-kms`	Identificador da chave AWS KMS usada para decifrar o ciphertext de `MASTER_KEYS`. Com `aws-kms`, o ciphertext é decifrado no processo do STA.
`MASTER_KEY_KMS_REGION`	—	Região da chave AWS KMS. Quando vazia, o Lerian STA usa `AWS_REGION`.
`CREDENTIALS_RECOVERY_ON_BOOT`	`false`	Defina explicitamente como `true` para rodar, uma vez no boot, a varredura de recuperação de credenciais do lado do worker para credenciais deixadas em rotação por um processo anterior.

O Lerian STA roda seu pipeline de auditoria em um worker dedicado. O export generator também precisa do seu bucket S3.Configure as flags de habilitação e os parâmetros obrigatórios pelas famílias AUDIT_PUBLISHER_*, AUDIT_CONSUMER_*, AUDIT_PARTITION_*, AUDIT_VERIFIER_*, AUDIT_EXPORT_GENERATOR_* e AUDIT_EXPORT_RATE_LIMIT_*. O runtime aplica os padrões declarados delas. O partition manager e o verifier rodam por padrão. Habilite cada um dos outros jobs antes de esperar que ele rode.

Streaming

O Lerian STA e a biblioteca de streaming da Lerian leem a família STREAMING_. O Lerian Streaming Hub entrega os eventos publicados.

Variável	Padrão / Obrigatório	Descrição
`STREAMING_ENABLED`	`false`	Chave mestra para a emissão de eventos de negócio para os brokers de streaming. Ela também exige `BUSINESS_EVENTS_ENABLED` e `RABBITMQ_ENABLED`, ambas `true` por padrão. Enquanto ela está desativada, o serviço não envia nenhum evento aos brokers.
`STREAMING_BROKERS`	Obrigatório quando o streaming está ativado	Lista de bootstrap de brokers separada por vírgulas. Uma configuração ativada com uma lista vazia recusa o boot.
`STREAMING_CLOUDEVENTS_SOURCE`	`br-sta` (fixo)	A fonte CloudEvents deste serviço. Ela define o namespace do tópico e o prefixo do tipo de evento. Deixe-a sem definir. Qualquer valor não vazio diferente de `br-sta` recusa o boot, mesmo quando o streaming está desativado.
`STREAMING_CLIENT_ID`	`br-sta`	Identificador de cliente do broker usado para diagnósticos do lado do broker.
`STREAMING_CB_FAILURE_RATIO`	`0.5`	Proporção de falhas que abre o circuit breaker do produtor. Com o streaming ativado, um valor igual ou menor que 0, ou maior que 1, recusa o boot.
`STREAMING_CB_MIN_REQUESTS`	`10`	Mínimo de requisições antes que o circuit breaker do produtor avalie a proporção de falhas. Com o streaming ativado, um valor negativo recusa o boot.
`STREAMING_CB_TIMEOUT_S`	`30`	Tempo de resfriamento no estado aberto, em segundos, para o circuit breaker do produtor. Com o streaming ativado, um valor negativo recusa o boot.
`STREAMING_CLOSE_TIMEOUT_S`	`30`	Janela máxima de drenagem e flush, em segundos, quando o produtor encerra. Com o streaming ativado, um valor de 0 ou menos recusa o boot.
`STREAMING_TOPIC_AUTO_PROVISION`	`true`	Com o streaming ativado, o serviço cria o seu tópico de eventos `lerian.streaming.br-sta` e o seu tópico de dead-letter `lerian.streaming.br-sta.dlq` nos brokers durante a inicialização, quando eles não existem. Uma criação com falha registra um aviso e o boot continua. Defina-a como `false` quando você cria os tópicos com antecedência.
`STREAMING_TOPIC_PARTITIONS`	`-1`	Número de partições de um tópico que o serviço cria. Um valor menor que 1 usa o padrão do broker.
`STREAMING_TOPIC_REPLICATION_FACTOR`	`-1`	Fator de replicação de um tópico que o serviço cria. Um valor menor que 1 usa o padrão do broker.
`STREAMING_TLS_ENABLED`	`false` (Obrigatório como `true` com `DEPLOYMENT_MODE=saas` quando o streaming está ativado)	Ativa o TLS na conexão com o broker. A versão mínima é TLS 1.2.
`STREAMING_TLS_CA_CERT`	—	Autoridade certificadora PEM para um broker privado ou on-premises, em PEM puro ou codificado em base64. Ela vale quando `STREAMING_TLS_ENABLED` é `true`. Um valor vazio usa o trust store do host.
`STREAMING_SASL_MECHANISM`	— (Obrigatório com `DEPLOYMENT_MODE=saas` quando o streaming está ativado)	Mecanismo de autenticação do broker: `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`. Um valor vazio desativa a autenticação do broker. Com o streaming ativado, um mecanismo sem as credenciais dele, ou sem `STREAMING_TLS_ENABLED=true`, recusa o boot.
`STREAMING_SASL_USERNAME`	— (Obrigatório com `DEPLOYMENT_MODE=saas` quando o streaming está ativado)	Nome de usuário de autenticação do broker.
`STREAMING_SASL_PASSWORD`	— (Obrigatório com `DEPLOYMENT_MODE=saas` quando o streaming está ativado)	Senha de autenticação do broker. Sensível.

Envios do Reporter

Estas variáveis controlam o consumidor que envia ao BACEN os relatórios regulatórios aprovados no Reporter. Veja Envios regulatórios do Reporter.

Variável	Padrão / Obrigatório	Descrição
`REPORTER_EVENTS_CONSUMER_ENABLED`	`false`	Consome as aprovações de envio regulatório do Reporter e envia os relatórios aprovados ao BACEN.
`REPORTER_EVENTS_CONSUMER_EXCHANGE`	Obrigatório se o consumidor estiver habilitado	Exchange de eventos do Reporter à qual o consumidor se vincula.
`REPORTER_EVENTS_DOCTYPE_RESOLVER`	Obrigatório se o consumidor estiver habilitado	Como o Lerian STA obtém o tipo de documento do BACEN de um relatório. Defina `payload` para lê-lo do evento.

​Serviço e runtime

​Licença

​Transferências

​Armazenamento de objetos

​Criptografia envelope

​Streaming

​Envios do Reporter

Serviço e runtime

Licença

Transferências

Armazenamento de objetos

Criptografia envelope

Streaming

Envios do Reporter