Tags
Table of contents
In terms of Docker Swarm services, a secret is a blob of data, such as apassword, SSH private key, SSL certificate, or another piece of data that shouldnot be transmitted over a network or stored unencrypted in a Dockerfile or inyour application's source code. You can use Docker secrets to centrally managethis data and securely transmit it to only those containers that need access toit. Secrets are encrypted during transit and at rest in a Docker swarm. A givensecret is only accessible to those services which have been granted explicitaccess to it, and only while those service tasks are running.
You can use secrets to manage any sensitive data which a container needs atruntime but you don't want to store in the image or in source control, such as:
- Usernames and passwords
- TLS certificates and keys
- SSH keys
- Other important data such as the name of a database or internal server
- Generic strings or binary content (up to 500 kb in size)
Note
Docker secrets are only available to swarm services, not tostandalone containers. To use this feature, consider adapting your containerto run as a service. Stateful containers can typically run with a scale of 1without changing the container code.
Another use case for using secrets is to provide a layer of abstraction betweenthe container and a set of credentials. Consider a scenario where you haveseparate development, test, and production environments for your application.Each of these environments can have different credentials, stored in thedevelopment, test, and production swarms with the same secret name. Yourcontainers only need to know the name of the secret to function in allthree environments.
You can also use secrets to manage non-sensitive data, such as configurationfiles. However, Docker supports the use ofconfigsfor storing non-sensitive data. Configs are mounted into the container'sfilesystem directly, without the use of a RAM disk.
Windows support
Docker includes support for secrets on Windows containers. Where there aredifferences in the implementations, they are called out in theexamples below. Keep the following notable differences in mind:
Microsoft Windows has no built-in driver for managing RAM disks, so withinrunning Windows containers, secrets are persisted in clear text to thecontainer's root disk. However, the secrets are explicitly removed when acontainer stops. In addition, Windows does not support persisting a runningcontainer as an image using
docker commit
or similar commands.On Windows, we recommend enablingBitLockeron the volume containing the Docker root directory on the host machine toensure that secrets for running containers are encrypted at rest.
Secret files with custom targets are not directly bind-mounted into Windowscontainers, since Windows does not support non-directory file bind-mounts.Instead, secrets for a container are all mounted in
C:\ProgramData\Docker\internal\secrets
(an implementation detail whichshould not be relied upon by applications) within the container. Symboliclinks are used to point from there to the desired target of the secret withinthe container. The default target isC:\ProgramData\Docker\secrets
.When creating a service which uses Windows containers, the options to specifyUID, GID, and mode are not supported for secrets. Secrets are currently onlyaccessible by administrators and users with
system
access within thecontainer.
How Docker manages secrets
When you add a secret to the swarm, Docker sends the secret to the swarm managerover a mutual TLS connection. The secret is stored in the Raft log, which isencrypted. The entire Raft log is replicated across the other managers, ensuringthe same high availability guarantees for secrets as for the rest of the swarmmanagement data.
When you grant a newly-created or running service access to a secret, thedecrypted secret is mounted into the container in an in-memory filesystem. Thelocation of the mount point within the container defaults to/run/secrets/<secret_name>
in Linux containers, orC:\ProgramData\Docker\secrets
in Windows containers. You can also specify acustom location.
You can update a service to grant it access to additional secrets or revoke itsaccess to a given secret at any time.
A node only has access to (encrypted) secrets if the node is a swarm manager orif it is running service tasks which have been granted access to the secret.When a container task stops running, the decrypted secrets shared to it areunmounted from the in-memory filesystem for that container and flushed from thenode's memory.
If a node loses connectivity to the swarm while it is running a task containerwith access to a secret, the task container still has access to its secrets, butcannot receive updates until the node reconnects to the swarm.
You can add or inspect an individual secret at any time, or list allsecrets. You cannot remove a secret that a running service isusing. SeeRotate a secret for a way toremove a secret without disrupting running services.
To update or roll back secrets more easily, consider adding a versionnumber or date to the secret name. This is made easier by the ability to controlthe mount point of the secret within a given container.
Use these links to read about specific commands, or continue to theexample about using secrets with a service.
- docker secret create
- docker secret inspect
- docker secret ls
- docker secret rm
- --secret flag for
docker service create
- --secret-add and --secret-rm flags for
docker service update
Examples
This section includes three graduated examples which illustrate how to useDocker secrets. The images used in these examples have been updated to make iteasier to use Docker secrets. To find out how to modify your own images ina similar way, seeBuild support for Docker Secrets into your images.
Note
These examples use a single-Engine swarm and unscaled services forsimplicity. The examples use Linux containers, but Windows containers alsosupport secrets. SeeWindows support.
Defining and using secrets in compose files
Both the docker-compose
and docker stack
commands support defining secretsin a compose file. Seethe Compose file reference for details.
Simple example: Get started with secrets
This simple example shows how secrets work in just a few commands. For areal-world example, continue toIntermediate example: Use secrets with a Nginx service.
Add a secret to Docker. The
docker secret create
command reads standardinput because the last argument, which represents the file to read thesecret from, is set to-
.$ printf "This is a secret" | docker secret create my_secret_data -
Create a
redis
service and grant it access to the secret. By default,the container can access the secret at/run/secrets/<secret_name>
, butyou can customize the file name on the container using thetarget
option.$ docker service create --name redis --secret my_secret_data redis:alpine
Verify that the task is running without issues using
docker service ps
. Ifeverything is working, the output looks similar to this:$ docker service ps redisID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTSbkna6bpn8r1a redis.1 redis:alpine ip-172-31-46-109 Running Running 8 seconds ago
If there were an error, and the task were failing and repeatedly restarting,you would see something like this:
$ docker service ps redisNAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTSredis.1.siftice35gla redis:alpine moby Running Running 4 seconds ago \_ redis.1.whum5b7gu13e redis:alpine moby Shutdown Failed 20 seconds ago "task: non-zero exit (1)" \_ redis.1.2s6yorvd9zow redis:alpine moby Shutdown Failed 56 seconds ago "task: non-zero exit (1)" \_ redis.1.ulfzrcyaf6pg redis:alpine moby Shutdown Failed about a minute ago "task: non-zero exit (1)" \_ redis.1.wrny5v4xyps6 redis:alpine moby Shutdown Failed 2 minutes ago "task: non-zero exit (1)"
Get the ID of the
redis
service task container usingdocker ps
, so thatyou can usedocker container exec
to connect to the container and read the contentsof the secret data file, which defaults to being readable by all and has thesame name as the name of the secret. The first command below illustrateshow to find the container ID, and the second and third commands use shellcompletion to do this automatically.$ docker ps --filter name=redis -q5cb1c2348a59$ docker container exec $(docker ps --filter name=redis -q) ls -l /run/secretstotal 4-r--r--r-- 1 root root 17 Dec 13 22:48 my_secret_data$ docker container exec $(docker ps --filter name=redis -q) cat /run/secrets/my_secret_dataThis is a secret
Verify that the secret is not available if you commit the container.
$ docker commit $(docker ps --filter name=redis -q) committed_redis$ docker run --rm -it committed_redis cat /run/secrets/my_secret_datacat: can't open '/run/secrets/my_secret_data': No such file or directory
Try removing the secret. The removal fails because the
redis
service isrunning and has access to the secret.$ docker secret lsID NAME CREATED UPDATEDwwwrxza8sxy025bas86593fqs my_secret_data 4 hours ago 4 hours ago$ docker secret rm my_secret_dataError response from daemon: rpc error: code = 3 desc = secret'my_secret_data' is in use by the following service: redis
Remove access to the secret from the running
redis
service by updating theservice.$ docker service update --secret-rm my_secret_data redis
Repeat steps 3 and 4 again, verifying that the service no longer has accessto the secret. The container ID is different, because the
service update
command redeploys the service.$ docker container exec -it $(docker ps --filter name=redis -q) cat /run/secrets/my_secret_datacat: can't open '/run/secrets/my_secret_data': No such file or directory
Stop and remove the service, and remove the secret from Docker.
$ docker service rm redis$ docker secret rm my_secret_data
Simple example: Use secrets in a Windows service
This is a very simple example which shows how to use secrets with a MicrosoftIIS service running on Docker for Windows running Windows containers onMicrosoft Windows 10. It is a naive example that stores the webpage in a secret.
This example assumes that you have PowerShell installed.
Save the following into a new file
index.html
.<html lang="en"> <head><title>Hello Docker</title></head> <body> <p>Hello Docker! You have deployed a HTML page.</p> </body></html>
If you have not already done so, initialize or join the swarm.
> docker swarm init
Save the
index.html
file as a swarm secret namedhomepage
.> docker secret create homepage index.html
Create an IIS service and grant it access to the
homepage
secret.> docker service create ` --name my-iis ` --publish published=8000,target=8000 ` --secret src=homepage,target="\inetpub\wwwroot\index.html" ` microsoft/iis:nanoserver
Note
There is technically no reason to use secrets for thisexample;configs are a better fit. This example isfor illustration only.
Access the IIS service at
http://localhost:8000/
. It should servethe HTML content from the first step.Remove the service and the secret.
> docker service rm my-iis> docker secret rm homepage> docker image remove secret-test
Intermediate example: Use secrets with a Nginx service
This example is divided into two parts.The first part is all about generatingthe site certificate and does not directly involve Docker secrets at all, butit sets upthe second part, where you storeand use the site certificate and Nginx configuration as secrets.
Generate the site certificate
Generate a root CA and TLS certificate and key for your site. For productionsites, you may want to use a service such as Let’s Encrypt
to generate theTLS certificate and key, but this example uses command-line tools. This stepis a little complicated, but is only a set-up step so that you havesomething to store as a Docker secret. If you want to skip these sub-steps,you canuse Let's Encrypt togenerate the site key and certificate, name the files site.key
andsite.crt
, and skip toConfigure the Nginx container.
Generate a root key.
$ openssl genrsa -out "root-ca.key" 4096
Generate a CSR using the root key.
$ openssl req \ -new -key "root-ca.key" \ -out "root-ca.csr" -sha256 \ -subj '/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA'
Configure the root CA. Edit a new file called
root-ca.cnf
and pastethe following contents into it. This constrains the root CA to signing leafcertificates and not intermediate CAs.[root_ca]basicConstraints = critical,CA:TRUE,pathlen:1keyUsage = critical, nonRepudiation, cRLSign, keyCertSignsubjectKeyIdentifier=hash
Sign the certificate.
$ openssl x509 -req -days 3650 -in "root-ca.csr" \ -signkey "root-ca.key" -sha256 -out "root-ca.crt" \ -extfile "root-ca.cnf" -extensions \ root_ca
Generate the site key.
$ openssl genrsa -out "site.key" 4096
Generate the site certificate and sign it with the site key.
$ openssl req -new -key "site.key" -out "site.csr" -sha256 \ -subj '/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost'
Configure the site certificate. Edit a new file called
site.cnf
andpaste the following contents into it. This constrains the sitecertificate so that it can only be used to authenticate a server andcan't be used to sign certificates.[server]authorityKeyIdentifier=keyid,issuerbasicConstraints = critical,CA:FALSEextendedKeyUsage=serverAuthkeyUsage = critical, digitalSignature, keyEnciphermentsubjectAltName = DNS:localhost, IP:127.0.0.1subjectKeyIdentifier=hash
Sign the site certificate.
$ openssl x509 -req -days 750 -in "site.csr" -sha256 \ -CA "root-ca.crt" -CAkey "root-ca.key" -CAcreateserial \ -out "site.crt" -extfile "site.cnf" -extensions server
The
site.csr
andsite.cnf
files are not needed by the Nginx service, butyou need them if you want to generate a new site certificate. Protecttheroot-ca.key
file.
Configure the Nginx container
Produce a very basic Nginx configuration that serves static files over HTTPS.The TLS certificate and key are stored as Docker secrets so that theycan be rotated easily.
In the current directory, create a new file called
site.conf
with thefollowing contents:server { listen 443 ssl; server_name localhost; ssl_certificate /run/secrets/site.crt; ssl_certificate_key /run/secrets/site.key; location / { root /usr/share/nginx/html; index index.html index.htm; }}
Create three secrets, representing the key, the certificate, and the
site.conf
. You can store any file as a secret as long as it is smallerthan 500 KB. This allows you to decouple the key, certificate, andconfiguration from the services that use them. In each of thesecommands, the last argument represents the path to the file to read thesecret from on the host machine's filesystem. In these examples, the secretname and the file name are the same.$ docker secret create site.key site.key$ docker secret create site.crt site.crt$ docker secret create site.conf site.conf
$ docker secret lsID NAME CREATED UPDATED2hvoi9mnnaof7olr3z5g3g7fp site.key 58 seconds ago 58 seconds agoaya1dh363719pkiuoldpter4b site.crt 24 seconds ago 24 seconds agozoa5df26f7vpcoz42qf2csth8 site.conf 11 seconds ago 11 seconds ago
Create a service that runs Nginx and has access to the three secrets. Thelast part of the
docker service create
command creates a symbolic linkfrom the location of thesite.conf
secret to/etc/nginx.conf.d/
, whereNginx looks for extra configuration files. This step happens before Nginxactually starts, so you don't need to rebuild your image if you change theNginx configuration.Note
Normally you would create a Dockerfile which copies the
site.conf
into place, build the image, and run a container using your custom image.This example does not require a custom image. It puts thesite.conf
into place and runs the container all in one step.Secrets are located within the
/run/secrets/
directory in the containerby default, which may require extra steps in the container to make thesecret available in a different path. The example below creates a symboliclink to the true location of thesite.conf
file so that Nginx can read it:$ docker service create \ --name nginx \ --secret site.key \ --secret site.crt \ --secret site.conf \ --publish published=3000,target=443 \ nginx:latest \ sh -c "ln -s /run/secrets/site.conf /etc/nginx/conf.d/site.conf && exec nginx -g 'daemon off;'"
Instead of creating symlinks, secrets allow you to specify a custom locationusing the
target
option. The example below illustrates how thesite.conf
secret is made available at/etc/nginx/conf.d/site.conf
inside the containerwithout the use of symbolic links:$ docker service create \ --name nginx \ --secret site.key \ --secret site.crt \ --secret source=site.conf,target=/etc/nginx/conf.d/site.conf \ --publish published=3000,target=443 \ nginx:latest \ sh -c "exec nginx -g 'daemon off;'"
The
site.key
andsite.crt
secrets use the short-hand syntax, without acustomtarget
location set. The short syntax mounts the secrets in `/run/secrets/with the same name as the secret. Within the running containers, the followingthree files now exist:/run/secrets/site.key
/run/secrets/site.crt
/etc/nginx/conf.d/site.conf
Verify that the Nginx service is running.
$ docker service lsID NAME MODE REPLICAS IMAGEzeskcec62q24 nginx replicated 1/1 nginx:latest$ docker service ps nginxNAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTSnginx.1.9ls3yo9ugcls nginx:latest moby Running Running 3 minutes ago
Verify that the service is operational: you can reach the Nginxserver, and that the correct TLS certificate is being used.
$ curl --cacert root-ca.crt https://localhost:3000<!DOCTYPE html><html><head><title>Welcome to nginx!</title><style> body { width: 35em; margin: 0 auto; font-family: Tahoma, Verdana, Arial, sans-serif; }</style></head><body><h1>Welcome to nginx!</h1><p>If you see this page, the nginx web server is successfully installed andworking. Further configuration is required.</p><p>For online documentation and support. refer to<a href="https://nginx.org">nginx.org</a>.<br/>Commercial support is available at<a href="https://www.nginx.com">nginx.com</a>.</p><p><em>Thank you for using nginx.</em></p></body></html>
$ openssl s_client -connect localhost:3000 -CAfile root-ca.crtCONNECTED(00000003)depth=1 /C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CAverify return:1depth=0 /C=US/ST=CA/L=San Francisco/O=Docker/CN=localhostverify return:1---Certificate chain 0 s:/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost i:/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA---Server certificate-----BEGIN CERTIFICATE-----…-----END CERTIFICATE-----subject=/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhostissuer=/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA---No client certificate CA names sent---SSL handshake has read 1663 bytes and written 712 bytes---New, TLSv1/SSLv3, Cipher is AES256-SHAServer public key is 4096 bitSecure Renegotiation IS supportedCompression: NONEExpansion: NONESSL-Session: Protocol : TLSv1 Cipher : AES256-SHA Session-ID: A1A8BF35549C5715648A12FD7B7E3D861539316B03440187D9DA6C2E48822853 Session-ID-ctx: Master-Key: F39D1B12274BA16D3A906F390A61438221E381952E9E1E05D3DD784F0135FB81353DA38C6D5C021CB926E844DFC49FC4 Key-Arg : None Start Time: 1481685096 Timeout : 300 (sec) Verify return code: 0 (ok)
To clean up after running this example, remove the
nginx
service and thestored secrets.$ docker service rm nginx$ docker secret rm site.crt site.key site.conf
Advanced example: Use secrets with a WordPress service
In this example, you create a single-node MySQL service with a custom rootpassword, add the credentials as secrets, and create a single-node WordPressservice which uses these credentials to connect to MySQL. Thenext example builds on this one and shows you how torotate the MySQL password and update the services so that the WordPress servicecan still connect to MySQL.
This example illustrates some techniques to use Docker secrets to avoid savingsensitive credentials within your image or passing them directly on the commandline.
Note
This example uses a single-Engine swarm for simplicity, and uses asingle-node MySQL service because a single MySQL server instance cannot bescaled by simply using a replicated service, and setting up a MySQL cluster isbeyond the scope of this example.
Also, changing a MySQL root passphrase isn’t as simple as changinga file on disk. You must use a query or a
mysqladmin
command to change thepassword in MySQL.
Generate a random alphanumeric password for MySQL and store it as a Dockersecret with the name
mysql_password
using thedocker secret create
command. To make the password shorter or longer, adjust the last argument oftheopenssl
command. This is just one way to create a relatively randompassword. You can use another command to generate the password if youchoose.Note
After you create a secret, you cannot update it. You can onlyremove and re-create it, and you cannot remove a secret that a service isusing. However, you can grant or revoke a running service's access tosecrets using
docker service update
. If you need the ability to update asecret, consider adding a version component to the secret name, so that youcan later add a new version, update the service to use it, then remove theold version.The last argument is set to
-
, which indicates that the input is read fromstandard input.$ openssl rand -base64 20 | docker secret create mysql_password -l1vinzevzhj4goakjap5ya409
The value returned is not the password, but the ID of the secret. In theremainder of this tutorial, the ID output is omitted.
Generate a second secret for the MySQL
root
user. This secret isn'tshared with the WordPress service created later. It's only needed tobootstrap themysql
service.$ openssl rand -base64 20 | docker secret create mysql_root_password -
List the secrets managed by Docker using
docker secret ls
:$ docker secret lsID NAME CREATED UPDATEDl1vinzevzhj4goakjap5ya409 mysql_password 41 seconds ago 41 seconds agoyvsczlx9votfw3l0nz5rlidig mysql_root_password 12 seconds ago 12 seconds ago
The secrets are stored in the encrypted Raft logs for the swarm.
Create a user-defined overlay network which is used for communicationbetween the MySQL and WordPress services. There is no need to expose theMySQL service to any external host or container.
$ docker network create -d overlay mysql_private
Create the MySQL service. The MySQL service has the followingcharacteristics:
Because the scale is set to
1
, only a single MySQL task runs.Load-balancing MySQL is left as an exercise to the reader and involvesmore than just scaling the service.Only reachable by other containers on the
mysql_private
network.Uses the volume
mydata
to store the MySQL data, so that it persistsacross restarts to themysql
service.The secrets are each mounted in a
tmpfs
filesystem at/run/secrets/mysql_password
and/run/secrets/mysql_root_password
.They are never exposed as environment variables, nor can they be committedto an image if thedocker commit
command is run. Themysql_password
secret is the one used by the non-privileged WordPress container toconnect to MySQL.Sets the environment variables
MYSQL_PASSWORD_FILE
andMYSQL_ROOT_PASSWORD_FILE
to point to thefiles/run/secrets/mysql_password
and/run/secrets/mysql_root_password
.Themysql
image reads the password strings from those files wheninitializing the system database for the first time. Afterward, thepasswords are stored in the MySQL system database itself.Sets environment variables
MYSQL_USER
andMYSQL_DATABASE
. A newdatabase calledwordpress
is created when the container starts, and thewordpress
user has full permissions for this database only. Thisuser cannot create or drop databases or change the MySQLconfiguration.$ docker service create \ --name mysql \ --replicas 1 \ --network mysql_private \ --mount type=volume,source=mydata,destination=/var/lib/mysql \ --secret source=mysql_root_password,target=mysql_root_password \ --secret source=mysql_password,target=mysql_password \ -e MYSQL_ROOT_PASSWORD_FILE="/run/secrets/mysql_root_password" \ -e MYSQL_PASSWORD_FILE="/run/secrets/mysql_password" \ -e MYSQL_USER="wordpress" \ -e MYSQL_DATABASE="wordpress" \ mysql:latest
Verify that the
mysql
container is running using thedocker service ls
command.$ docker service lsID NAME MODE REPLICAS IMAGEwvnh0siktqr3 mysql replicated 1/1 mysql:latest
Now that MySQL is set up, create a WordPress service that connects to theMySQL service. The WordPress service has the following characteristics:
- Because the scale is set to
1
, only a single WordPress task runs.Load-balancing WordPress is left as an exercise to the reader, because oflimitations with storing WordPress session data on the containerfilesystem. - Exposes WordPress on port 30000 of the host machine, so that you can accessit from external hosts. You can expose port 80 instead if you do not havea web server running on port 80 of the host machine.
- Connects to the
mysql_private
network so it can communicate with themysql
container, and also publishes port 80 to port 30000 on all swarmnodes. - Has access to the
mysql_password
secret, but specifies a differenttarget file name within the container. The WordPress container usesthe mount point/run/secrets/wp_db_password
. - Sets the environment variable
WORDPRESS_DB_PASSWORD_FILE
to the filepath where the secret is mounted. The WordPress service reads theMySQL password string from that file and add it to thewp-config.php
configuration file. - Connects to the MySQL container using the username
wordpress
and thepassword in/run/secrets/wp_db_password
and creates thewordpress
database if it does not yet exist. - Stores its data, such as themes and plugins, in a volume called
wpdata
so these files persist when the service restarts.
$ docker service create \ --name wordpress \ --replicas 1 \ --network mysql_private \ --publish published=30000,target=80 \ --mount type=volume,source=wpdata,destination=/var/www/html \ --secret source=mysql_password,target=wp_db_password \ -e WORDPRESS_DB_USER="wordpress" \ -e WORDPRESS_DB_PASSWORD_FILE="/run/secrets/wp_db_password" \ -e WORDPRESS_DB_HOST="mysql:3306" \ -e WORDPRESS_DB_NAME="wordpress" \ wordpress:latest
- Because the scale is set to
Verify the service is running using
docker service ls
anddocker service ps
commands.$ docker service lsID NAME MODE REPLICAS IMAGEwvnh0siktqr3 mysql replicated 1/1 mysql:latestnzt5xzae4n62 wordpress replicated 1/1 wordpress:latest
$ docker service ps wordpressID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTSaukx6hgs9gwc wordpress.1 wordpress:latest moby Running Running 52 seconds ago
At this point, you could actually revoke the WordPress service's access tothe
mysql_password
secret, because WordPress has copied the secret to itsconfiguration filewp-config.php
. Don't do that for now, because weuse it later to facilitate rotating the MySQL password.Access
http://localhost:30000/
from any swarm node and set up WordPressusing the web-based wizard. All of these settings are stored in the MySQLwordpress
database. WordPress automatically generates a password for yourWordPress user, which is completely different from the password WordPressuses to access MySQL. Store this password securely, such as in a passwordmanager. You need it to log into WordPress afterrotating the secret.Go ahead and write a blog post or two and install a WordPress plugin ortheme to verify that WordPress is fully operational and its state is savedacross service restarts.
Do not clean up any services or secrets if you intend to proceed to the nextexample, which demonstrates how to rotate the MySQL root password.
Example: Rotate a secret
This example builds upon the previous one. In this scenario, you create a newsecret with a new MySQL password, update the mysql
and wordpress
services touse it, then remove the old secret.
Note
Changing the password on a MySQL database involves running extraqueries or commands, as opposed to just changing a single environment variableor a file, since the image only sets the MySQL password if the database doesn’talready exist, and MySQL stores the password within a MySQL database by default.Rotating passwords or other secrets may involve additional steps outside ofDocker.
Create the new password and store it as a secret named
mysql_password_v2
.$ openssl rand -base64 20 | docker secret create mysql_password_v2 -
Update the MySQL service to give it access to both the old and new secrets.Remember that you cannot update or rename a secret, but you can revoke asecret and grant access to it using a new target filename.
$ docker service update \ --secret-rm mysql_password mysql$ docker service update \ --secret-add source=mysql_password,target=old_mysql_password \ --secret-add source=mysql_password_v2,target=mysql_password \ mysql
Updating a service causes it to restart, and when the MySQL service restartsthe second time, it has access to the old secret under
/run/secrets/old_mysql_password
and the new secret under/run/secrets/mysql_password
.Even though the MySQL service has access to both the old and new secretsnow, the MySQL password for the WordPress user has not yet been changed.
Note
This example does not rotate the MySQL
root
password.Now, change the MySQL password for the
wordpress
user using themysqladmin
CLI. This command reads the old and new password from the filesin/run/secrets
but does not expose them on the command line or save themin the shell history.Do this quickly and move on to the next step, because WordPress losesthe ability to connect to MySQL.
First, find the ID of the
mysql
container task.$ docker ps --filter name=mysql -qc7705cf6176f
Substitute the ID in the command below, or use the second variant whichuses shell expansion to do it all in a single step.
$ docker container exec <CONTAINER_ID> \ bash -c 'mysqladmin --user=wordpress --password="$(< /run/secrets/old_mysql_password)" password "$(< /run/secrets/mysql_password)"'
Or:
$ docker container exec $(docker ps --filter name=mysql -q) \ bash -c 'mysqladmin --user=wordpress --password="$(< /run/secrets/old_mysql_password)" password "$(< /run/secrets/mysql_password)"'
Update the
wordpress
service to use the new password, keeping the targetpath at/run/secrets/wp_db_password
. This triggers a rolling restart ofthe WordPress service and the new secret is used.$ docker service update \ --secret-rm mysql_password \ --secret-add source=mysql_password_v2,target=wp_db_password \ wordpress
Verify that WordPress works by browsing to http://localhost:30000/ on anyswarm node again. Use the WordPress username and passwordfrom when you ran through the WordPress wizard in the previous task.
Verify that the blog post you wrote still exists, and if you changed anyconfiguration values, verify that they are still changed.
Revoke access to the old secret from the MySQL service andremove the old secret from Docker.
$ docker service update \ --secret-rm mysql_password \ mysql$ docker secret rm mysql_password
Run the following commands to remove the WordPress service, the MySQL container,the
mydata
andwpdata
volumes, and the Docker secrets:$ docker service rm wordpress mysql$ docker volume rm mydata wpdata$ docker secret rm mysql_password_v2 mysql_root_password
If you develop a container that can be deployed as a service and requiressensitive data, such as a credential, as an environment variable, consideradapting your image to take advantage of Docker secrets. One way to do this isto ensure that each parameter you pass to the image when creating the containercan also be read from a file.
Many of the Docker Official Images in theDocker library, such as thewordpressimage used in the above examples, have been updated in this way.
When you start a WordPress container, you provide it with the parameters itneeds by setting them as environment variables. The WordPress image has beenupdated so that the environment variables which contain important data forWordPress, such as WORDPRESS_DB_PASSWORD
, also have variants which can readtheir values from a file (WORDPRESS_DB_PASSWORD_FILE
). This strategy ensuresthat backward compatibility is preserved, while allowing your container to readthe information from a Docker-managed secret instead of being passed directly.
Note
Docker secrets do not set environment variables directly. This was aconscious decision, because environment variables can unintentionally be leakedbetween containers (for instance, if you use
--link
).
Use Secrets in Compose
services: db: image: mysql:latest volumes: - db_data:/var/lib/mysql environment: MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password MYSQL_DATABASE: wordpress MYSQL_USER: wordpress MYSQL_PASSWORD_FILE: /run/secrets/db_password secrets: - db_root_password - db_password wordpress: depends_on: - db image: wordpress:latest ports: - "8000:80" environment: WORDPRESS_DB_HOST: db:3306 WORDPRESS_DB_USER: wordpress WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password secrets: - db_passwordsecrets: db_password: file: db_password.txt db_root_password: file: db_root_password.txtvolumes: db_data:
This example creates a simple WordPress site using two secrets ina Compose file.
The top-level element secrets
defines two secrets db_password
anddb_root_password
.
When deploying, Docker creates these two secrets and populates them with thecontent from the file specified in the Compose file.
The db
service uses both secrets, and wordpress
is using one.
When you deploy, Docker mounts a file under /run/secrets/<secret_name>
in theservices. These files are never persisted on disk, but are managed in memory.
Each service uses environment variables to specify where the service should lookfor that secret data.
More information on short and long syntax for secrets can be found in theCompose Specification.