Ir para o conteúdo
Promovaweb

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
  1. Por que o Swarm tem um lugar para segredos
  2. O caminho de um secret
  3. Como o app lê o secret
  4. Configs, os arquivos sem sigilo
  5. Autolock e a chave de desbloqueio

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:

  1. Criação

    docker secret create

    O valor chega a um manager por TLS mútuo.

  2. Log do Raft

    /var/lib/docker/swarm

    O secret fica cifrado e replicado entre os managers.

  3. Acesso

    secrets: [db_password]

    O serviço declara o nome do secret que pode ler.

  4. Montagem

    /run/secrets/db_password

    A tarefa recebe o arquivo decifrado num sistema de arquivos em memória.

  5. Fim da tarefa

    tmpfs desmontado

    O secret sai da memória do nó junto com a tarefa.

O secret viaja cifrado do comando até o manager e fica cifrado no log do Raft. Só a tarefa com acesso recebe o valor decifrado, montado em memória e apagado quando a tarefa para.

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 (modo 0444) 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.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.