diff --git a/engine/swarm/configs.md b/engine/swarm/configs.md index b00bfc9e15..509ed6b3ae 100644 --- a/engine/swarm/configs.md +++ b/engine/swarm/configs.md @@ -13,9 +13,10 @@ as possible, without the need to bind-mount configuration files into the containers or use environment variables. Configs operate in a similar way to [secrets](secrets.md), except that they are -not encrypted at rest. Configs can be added or removed from a service at any -time, and services can share a config. You can even use configs in conjunction -with environment variables or labels, for maximum flexibility. +not encrypted at rest and are mounted directly into the container's filesystem +without the use of RAM disks. Configs can be added or removed from a service at +any time, and services can share a config. You can even use configs in +conjunction with environment variables or labels, for maximum flexibility. > **Note**: Docker configs are only available to swarm services, not to > standalone containers. To use this feature, consider adapting your container @@ -32,12 +33,12 @@ encrypted. The entire Raft log is replicated across the other managers, ensuring the same high availability guarantees for configs as for the rest of the swarm management data. -When you grant a newly-created or running service access to a config, the -config is mounted as a file in the container, in an in-memory filesystem. The -location of the mount point within the container defaults to -`/` in Linux containers. In Windows containers, configs are all -mounted into `C:\ProgramData\Docker\configs` and symbolic links are created to -the desired location, which defaults to `C:\`. +When you grant a newly-created or running service access to a config, the config +is mounted as a file in the container. The location of the mount point within +the container defaults to `/` in Linux containers. In Windows +containers, configs are all mounted into `C:\ProgramData\Docker\configs` and +symbolic links are created to the desired location, which defaults to +`C:\`. You can update a service to grant it access to additional configs or revoke its access to a given config at any time. @@ -98,7 +99,7 @@ real-world example, continue to you can customize the file name on the container using the `target` option. ```bash - $ docker service create --name="redis" --config="my-config" redis:alpine + $ docker service create --name redis --config my-config redis:alpine ``` 3. Verify that the task is running without issues using `docker service ps`. If @@ -155,14 +156,14 @@ real-world example, continue to $ docker config rm my-config - Error response from daemon: rpc error: code = 3 desc = config 'my-config' is in use by the following service: redis - ``` + Error response from daemon: rpc error: code = 3 desc = config 'my-config' is + in use by the following service: redis ``` 7. Remove access to the config from the running `redis` service by updating the service. ```bash - $ docker service update --config-rm="my-config" redis + $ docker service update --config-rm my-config redis ``` 8. Repeat steps 3 and 4 again, verifying that the service no longer has access @@ -183,6 +184,57 @@ real-world example, continue to $ docker config rm my-config ``` +### Simple example: Use configs in a Windows service + +This is a very simple example which shows how to use configs with a Microsoft +IIS service running on Docker 17.06 EE on Microsoft Windows Server 2016 or Docker +for Mac 17.06 on Microsoft Windows 10. It stores the webpage in a config. + +This example assumes that you have PowerShell installed. + +1. Save the following into a new file `index.html`. + + ```html + + Hello Docker + +

Hello Docker! You have deployed a HTML page.

+ + + ``` +2. If you have not already done so, initialize or join the swarm. + + ```powershell + PS> docker swarm init + ``` + +3. Save the `index.html` file as a swarm config named `homepage`. + + ```powershell + PS> docker config create homepage index.html + ``` + +4. Create an IIS service and grant it access to the `homepage` config. + + ```powershell + PS> docker service create + --name my-iis + -p 8000:8000 + --config src=homepage,target="\inetpub\wwwroot\index.html" + microsoft/iis:nanoserver + ``` + +5. Access the IIS service at `http://localhost:8000/`. It should serve + the HTML content from the first step. + +6. Remove the service and the config. + + ```powershell + PS> docker service rm my-iis + + PS> docker config rm homepage + ``` + ### Advanced example: Use configs with a Nginx service This example is divided into two parts. diff --git a/engine/swarm/secrets.md b/engine/swarm/secrets.md index e7e0f515aa..05096f2caa 100644 --- a/engine/swarm/secrets.md +++ b/engine/swarm/secrets.md @@ -37,6 +37,11 @@ development, test, and production swarms with the same secret name. Your containers only need to know the name of the secret in order to function in all three environments. +You can also use secrets to manage non-sensitive data, such as configuration +files. However, Docker 17.06 and higher support the use of [configs](configs.md) +for storing non-sensitive data. Configs are mounted into the container's +filesystem directly, without the use of a RAM disk. + ### Windows support Docker 17.06 and higher include support for secrets on Windows containers. @@ -49,6 +54,11 @@ examples below. Keep the following notable differences in mind: container stops. In addition, Windows does not support persisting a running container as an image using `docker commit` or similar commands. +- On Windows, we recommend enabling + [BitLocker](https://technet.microsoft.com/en-us/library/cc732774(v=ws.11).aspx) + on the volume containing the Docker root directory on the host machine to + ensure that secrets for running containers are encrypted at rest. + - Secret files with custom targets are not directly bind-mounted into Windows containers, since Windows does not support non-directory file bind-mounts. Instead, secrets for a container are all mounted in @@ -152,7 +162,7 @@ real-world example, continue to you can customize the file name on the container using the `target` option. ```bash - $ docker service create --name="redis" --secret="my_secret_data" redis:alpine + $ docker service create --name redis --secret my_secret_data redis:alpine ``` 3. Verify that the task is running without issues using `docker service ps`. If @@ -224,14 +234,15 @@ real-world example, continue to $ docker secret rm my_secret_data - Error response from daemon: rpc error: code = 3 desc = secret 'my_secret_data' is in use by the following service: redis + Error response from daemon: rpc error: code = 3 desc = secret + 'my_secret_data' is in use by the following service: redis ``` 7. Remove access to the secret from the running `redis` service by updating the service. ```bash - $ docker service update --secret-rm="my_secret_data" redis + $ docker service update --secret-rm my_secret_data redis ``` 8. Repeat steps 3 and 4 again, verifying that the service no longer has access @@ -254,64 +265,58 @@ real-world example, continue to ### Simple example: Use secrets in a Windows service -This is a very simple example which shows how to use secrets with a Windows -container running on Docker 17.06 EE on Microsoft Windows Server 2013 or Docker -for Mac 17.06 on Microsoft Windows 10. This example simply dumps the contents of -all secrets granted to the container. +This is a very simple example which shows how to use secrets with a Microsoft +IIS service running on Docker 17.06 EE on Microsoft Windows Server 2016 or Docker +for Mac 17.06 on Microsoft Windows 10. It is a naive example that stores the +webpage in a secret. This example assumes that you have PowerShell installed. -1. If you have not already done so, initialize or join the swarm. +1. Save the following into a new file `index.html`. + + ```html + + Hello Docker + +

Hello Docker! You have deployed a HTML page.

+ + + ``` +2. If you have not already done so, initialize or join the swarm. ```powershell PS> docker swarm init ``` -2. Copy the following into a file called `Dockerfile`: - - ```conf - FROM microsoft/nanoserver - RUN ["powershell", "cat, "C:\\ProgramData\Docker\secrets\*.*"] - ``` - - The `RUN` line will output the contents of any files within the default - secrets directory within Windows containers. If no secrets have been - granted to the service, no output will be shown. - -3. Build the Dockerfile with the tag `secret-test`. +3. Save the `index.html` file as a swarm secret named `homepage`. ```powershell - PS> docker build -t secret-test . + PS> docker secret create homepage index.html ``` -4. Create a secret: +4. Create an IIS service and grant it access to the `homepage` secret. ```powershell - PS> "this is a test" | docker secret create win-secret - + PS> docker service create + --name my-iis + -p 8000:8000 + --secret src=homepage,target="\inetpub\wwwroot\index.html" + microsoft/iis:nanoserver ``` -5. Create a service using the `secret-test` image and grant it access to the - `win-secret` secret. + > **Note**: There is technically no reason to use secrets for this + > example. With Docker 17.06 and higher, [configs](configs.md) are + > a better fit. This example is for illustration only. + +5. Access the IIS service at `http://localhost:8000/`. It should serve + the HTML content from the first step. + +6. Remove the service and the secret. ```powershell - PS> docker service create --name my-win-service --secret win-secret secret-test - ``` - -6. View the logs for the service: - - ```powershell - PS> docker service logs my-win-service - ``` - - The contents of the secret should be shown. - -7. Remove the service, the secret, and the image. - - ```powershell - PS> docker service rm my-win-service - - PS> docker secret rm win-secret + PS> docker service rm my-iis + PS> docker secret rm homepage PS> docker image remove secret-test ```