Secrets e configs no Docker Swarm
Um secret do Docker Swarm é um bloco de até 500 KB, como uma senha, uma chave SSH ou um certificado TLS, que o cluster guarda cifrado no log do Raft dos managers. O Swarm monta o secret num sistema de arquivos em memória, só nas tarefas dos serviços com acesso a ele, por isso a senha decifrada chega só aos nós que rodam essas tarefas e sai da memória quando a tarefa para.
Ficha e sumário da página
- Referência técnica
- Docker Engine v29.9.3
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Por que o Swarm tem um lugar para segredos
Num cluster, a senha do banco de um serviço precisa chegar a qualquer nó onde uma réplica dele venha a rodar. Gravada na imagem, ela fica visível em qualquer cópia baixada da imagem. Escrita como variável de ambiente no arquivo da stack, ela aparece no docker service inspect e no histórico do repositório onde o arquivo fica versionado. O secret tira a senha desses lugares: o valor fica no estado do cluster, enquanto o arquivo da stack guarda só o nome do secret.
O nome também separa ambientes. Um cluster de teste e um cluster de produção podem ter um secret com o mesmo nome e valores diferentes, de modo que o mesmo arquivo de stack serve aos dois e cada cluster monta no container a senha do próprio ambiente.
O caminho de um secret
Quando você cria um secret com docker secret create, o comando chega a um manager por uma conexão TLS mútua. O manager grava o secret no log do Raft, que fica cifrado no disco. O log inteiro é replicado para os outros managers. Por isso um secret tem a mesma disponibilidade que o resto do estado do cluster: a queda de um manager não apaga nenhum secret. O percurso completo segue esta ordem:
Criação
docker secret createO valor chega a um manager por TLS mútuo.
Log do Raft
/var/lib/docker/swarmO secret fica cifrado e replicado entre os managers.
Acesso
secrets: [db_password]O serviço declara o nome do secret que pode ler.
Montagem
/run/secrets/db_passwordA tarefa recebe o arquivo decifrado num sistema de arquivos em memória.
Fim da tarefa
tmpfs desmontadoO secret sai da memória do nó junto com a tarefa.
Um nó só tem acesso aos secrets cifrados quando é manager ou quando roda uma tarefa de um serviço com acesso àquele secret. Um worker sem tarefas do serviço do banco não recebe a senha do banco. Se um nó perde a conexão com o cluster enquanto roda uma tarefa, o container continua lendo os secrets que já tinha, sem receber atualizações até o nó voltar.
Como o app lê o secret
O secret aparece para o container como um arquivo, por padrão em /run/secrets/<nome>, com caminho personalizável na declaração do serviço. Cabe ao app ler esse arquivo. Nos exemplos da documentação, as imagens do MySQL e do WordPress aceitam variáveis de ambiente terminadas em _FILE para esse fim: MYSQL_PASSWORD_FILE=/run/secrets/mysql_password e WORDPRESS_DB_PASSWORD_FILE apontam para o arquivo no lugar da senha em texto.
Um app que só aceita a senha em variável de ambiente comum não aproveita o secret sem ajuste. Nesse caso, um script de entrada na imagem lê o arquivo e exporta a variável antes de iniciar o processo, ou o app continua com a senha no ambiente e fica sem a proteção do secret.
Configs, os arquivos sem sigilo
Um config guarda um arquivo de configuração fora da imagem, como o arquivo de um proxy ou as opções de um banco. Ele tem o mesmo limite de 500 KB, fica no log do Raft e chega ao manager por TLS mútuo, como o secret. As diferenças aparecem no nó: o config fica sem cifragem em repouso e entra direto no sistema de arquivos do container, sem disco em memória.
Secret
- Senhas, chaves SSH, certificados e tokens.
- Fica cifrado em repouso.
- Montado num sistema de arquivos em memória.
- Caminho padrão
/run/secrets/<nome>no Linux.
Config
- Arquivos de configuração sem informação sigilosa.
- Fica sem cifragem em repouso.
- Montado direto no sistema de arquivos do container.
- Caminho padrão
/<nome>no Linux, com leitura para todos (modo0444) quando você não define o modo.
Os dois recursos têm o mesmo comportamento em três pontos. Vários serviços podem receber o mesmo secret ou config, nenhum dos dois sai do cluster enquanto um serviço em execução o usa e ambos somem da memória do nó quando a tarefa para.
Você define o dono (uid e gid) e as permissões (mode) do arquivo de um config na declaração do serviço. Sem essas opções, o arquivo pertence ao usuário que roda o comando do container, que em muitas imagens é o root. Os dois recursos existem só para serviços do Swarm. Um container avulso, criado com docker run, não recebe secrets nem configs. A documentação sugere rodar esse container como serviço com uma réplica, sem mudar o código dele.
Autolock e a chave de desbloqueio
O log do Raft fica cifrado no disco por padrão, mas as chaves que decifram o log e as chaves do TLS entre os nós ficam carregadas na memória de cada manager quando o Docker reinicia. Uma cópia do diretório /var/lib/docker/swarm de um manager leva junto o necessário para ler os secrets.
Com docker swarm update --autolock=true, o Docker gera uma chave de desbloqueio e cada manager reiniciado espera o comando docker swarm unlock com essa chave antes de voltar ao cluster. Você troca disponibilidade por proteção, porque um manager que reinicia fica fora do quórum até você rodar o desbloqueio. Os nós novos entram no cluster sem essa etapa.
O próximo passo é ver como o Swarm troca a versão de um serviço réplica por réplica e volta atrás quando a versão nova falha, na página Atualizações e rollback.