Quando um secret precisa ser um arquivo, não uma variável de ambiente

A maior parte do que uma aplicação precisa é um simples par KEY=VALUE, e a maioria das plataformas PaaS é construída inteiramente em torno dessa suposição. Daí aparece um JSON de service account do Google Cloud — alguns kilobytes de credencial estruturada que os próprios SDKs do Google esperam encontrar num caminho de arquivo, não dentro de uma variável de ambiente — e a saída de sempre é codificar tudo em base64 numa variável e decodificar num script de entrypoint. Funciona, mas é um workaround, não uma funcionalidade.

O mecanismo de verdade

Variables → File secrets recebe um nome e o conteúdo direto — até 64 KB, o suficiente para um JSON de service account, um certificado de cliente, ou credenciais estruturadas parecidas. É armazenado criptografado, igual a qualquer outro secret, e montado como somente leitura dentro do container em /etc/railyard/secrets/<name> — sem ida e volta em base64, sem script de entrypoint decodificando uma variável antes da aplicação poder iniciar.

A parte que elimina o segundo passo de sempre: o caminho dele também é exposto como a própria variável de ambiente, RAILYARD_SECRET_FILE_<NAME>. Uma biblioteca cliente do Google que espera que GOOGLE_APPLICATION_CREDENTIALS aponte para um arquivo simplesmente recebe:

GOOGLE_APPLICATION_CREDENTIALS=${RAILYARD_SECRET_FILE_GCP_KEY_JSON}

Nenhum passo extra resolve essa referência — é o mesmo mecanismo de referência de variável de tudo mais, só que apontando para um caminho em vez de um valor. Remover um secret em arquivo entra em vigor no próximo deploy, igual a qualquer outra mudança de variável.

Onde isso se encaixa junto com tudo que já é automático

Os serviços provisionados já injetam suas próprias variáveis sem precisar ser pedidos — DATABASE_URL, os campos individuais DATABASE_HOST/PORT/USER/PASSWORD/NAME, REDIS_URL, chaves de storage, RAILYARD_URL e companhia. As variáveis documentadas da própria aplicação (os nomes específicos que ela lista precisar, como PGHOST ou BIND_ADDRESS) são preenchidas a partir desses serviços automaticamente onde os nomes coincidem, e os secrets que a própria aplicação é dona — SECRET_KEY_BASE, APP_KEY, JWT_SECRET — são gerados uma vez em vez de ficarem em branco. O que esse mecanismo deliberadamente não faz é inventar uma credencial de terceiro em seu nome — uma service account do GCP, uma chave do Stripe, qualquer coisa que pertence de verdade a uma conta externa. Essas são sempre suas para fornecer, que é exatamente a categoria pra qual os secrets em arquivo existem.

Referenciando um serviço em vez de fixar um host

A mesma sintaxe de referência ${{...}} usada para caminhos de secrets em arquivo funciona entre serviços em geral: ${{api.RAILYARD_PRIVATE_URL}} resolve para o endereço privado daquele serviço dentro do mesmo ambiente, e ${config.KEY} busca de uma configuração compartilhada pela equipe inteira, disponível pra qualquer aplicação — o mesmo padrão, três fontes diferentes, então uma aplicação nunca tem um host fixo no código ou um secret copiado e colado que fica dessincronizado de onde o valor real mora.

Referência completa: Variables and secrets.