Variáveis e segredos

A aba Configuração de cada aplicação guarda, por ambiente, dois tipos de valor:

• Variáveis de configuração: valores não sensíveis, como LOG_LEVEL ou FEATURE_X. O valor fica visível no portal.
• Segredos: strings de conexão, chaves de API e senhas. Depois de gravado, o valor de um segredo nunca é mostrado de novo.

Nunca coloque segredos dentro da imagem ou em variáveis comuns.

Nomes

Variáveis e segredos seguem o padrão ^[A-Z_][A-Z0-9_]{0,63}$ (letras maiúsculas, dígitos e _, até 64 caracteres) e são únicos por aplicação e ambiente.

Como os segredos são protegidos

• O valor do segredo é aceito apenas na criação e na rotação. Nenhuma resposta da API, listagem, evento de auditoria ou log devolve o valor; o portal mostra o segredo sempre mascarado, com nome, versão atual, autor e datas.
• O valor fica somente no cofre da sua organização, em um caminho separado por projeto, ambiente e aplicação, e separado dos segredos da própria plataforma. O banco de dados guarda apenas metadados.
• A instância obtém os segredos em tempo de execução com uma identidade de workload limitada à própria aplicação e ao ambiente, usando credencial de curta duração. O manifesto do workload referencia os segredos sem conter valores.
• O build nunca recebe variáveis nem segredos de runtime. Código-fonte não confiável não tem como lê-los durante o build.

Rotacionar e remover

Ação	Quem pode	Efeito
Criar e alterar variável	Owner, Admin, Developer	Nova configuração pendente.
Criar e rotacionar segredo	Owner, Admin, Developer	A rotação gera uma nova versão. O histórico lista versões com autor e data, sem valores.
Remover segredo	Owner, Admin	Apaga o valor do cofre e mantém o registro na auditoria.
Consultar	Todos os papéis	Viewer apenas lê nomes e metadados.

As mudanças valem no próximo deploy

Cada deploy congela o conjunto de variáveis e as versões de segredos vigentes naquele momento. Alterações feitas depois só chegam às instâncias com um novo deploy; até lá, a aplicação mostra o aviso "alterações pendentes". Isso também vale para o rollback, que volta com a configuração da versão escolhida.

Cofre da organização e configuração compartilhada

Cada organização tem um cofre dedicado (um namespace próprio no OpenBao), criado junto com ela. Segredos de aplicação, segredos compartilhados e credenciais ficam só nele; apagar a organização apaga o cofre inteiro de uma vez, e a chave de dados da organização é destruída antes, o que torna ilegíveis também as cópias em backup.

Além das variáveis e segredos da aplicação, há variáveis compartilhadas na organização, no projeto e no ambiente. Vale a definição mais específica: aplicação, depois ambiente, depois projeto, depois organização. A aba Configuração mostra a configuração efetiva com a origem de cada valor.

Segredos compartilhados não são herdados: cada aplicação recebe só os que forem vinculados a ela, com um apelido (o nome da variável de ambiente). A identidade da aplicação lê apenas o caminho exato dos segredos vinculados, e desvincular revoga a leitura no próximo deploy.

Ação	Quem pode
Variável da organização	Owner, Admin
Variável de projeto ou ambiente	Owner, Admin, Developer do projeto
Segredo compartilhado (criar, rotacionar, remover, fonte externa)	Owner, Admin (com confirmação recente do segundo fator)
Vincular segredo da organização	Owner, Admin
Vincular segredo de projeto ou ambiente	Owner, Admin, Developer do projeto

Segredos com fonte externa

Um segredo compartilhado pode vir de um cofre que você já usa: Azure Key Vault, AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault ou OpenBao. Em Fonte externa, informe o provedor, a referência e o intervalo de sincronização (mínimo de 5 minutos).

• A plataforma lê o valor só para leitura, com a identidade da aplicação da sua organização (federação OIDC, sem chave estática), e grava uma nova versão no cofre da organização quando o valor muda. O valor nunca passa pela API nem aparece no portal.
• Na federação do provedor, cadastre o emissor mostrado na aba Identidade de uma aplicação (o da primeira região da plataforma) e o sub org:<id da organização>; a audiência é a que o provedor pede (por exemplo api://AzureADTokenExchange no Azure).
• Se a leitura falhar, o último valor bom continua em uso e o portal mostra o motivo (por exemplo, auth_failed ou not_found) até a próxima sincronização bem-sucedida.
• Remover a fonte externa mantém a última versão sincronizada como valor atual.

Provedor	Referência
Azure Key Vault	https://<cofre>.vault.azure.net/secrets/<nome>?tenant=<tenantId>&client=<clientId>
AWS Secrets Manager	arn:aws:secretsmanager:<região>:<conta>:secret:<nome>?role=arn:aws:iam::<conta>:role/<papel>
GCP Secret Manager	projects/<projeto>/secrets/<nome>/versions/<versão>?audience=//iam.googleapis.com/projects/<n>/locations/global/workloadIdentityPools/<pool>/providers/<provedor>
HashiCorp Vault e OpenBao	https://<host>/v1/<mount>/data/<caminho>?role=<papel JWT>&field=<campo> (opcional: namespace)

Como em qualquer segredo, a nova versão chega às instâncias no próximo deploy.

Fora do escopo atual

• Importação em massa de arquivos .env.
• Rotação automática de credenciais de bancos gerenciados.