Docker Swarm - Managing Configurations

docker-swarm-configs.md

Docker Swarm - Managing Configurations

Docker allows storing configurations outside docker images and running containers. This feature, named configs, eliminates the need to use volumes, bind-mount, or environment variables to pass configurations to containers.

The configs have the following characteristics:

• Configs are not encrypted (secrets are encrypted)
• Config values can be strings or binary data
• Config values have maximum size of 500 kB
• Configs are mounted as a file in the container filesystem. The default location is /<config-name> in the container
• Configs can be added or removed from a service at any time

The configs feature are available in docker swarm.

Create a config

The syntax of the create command is as follows:

$ docker config create [options] <config-name> <filename> | -

A configuration can be read from the standard input:

$ echo "This is my config" | docker config create myconfig -

The second method of creating a config is to read it from a file:

$ echo "This is another config" > config.txt
$ docker config create myconfig_file ./config.txt 

List configs

The ls command lists all configs in a swarm.

$ docker config ls

Inspect a config

The inspect command displays detailed information about a configuration in JSON format.

$ docker config inspect [options] <config-name>
$ docker config inspect myconfig

In addition to metadata, the command shows the content of the config in Base64 format.

The option --pretty prints the output in a human readable format.

$ docker config inspect --pretty myconfig

The option --format, or -f, prints a specific information about a configuration. The option accepts a template.

$ docker config inspect -f '{{.Spec.Data}}' myconfig

Remove a config

The rm command removes an existing configuration. There is no confirmation before removing the configuration.

$ docker config rm myconfig

A config cannot be removed while it used by a service.

Examples: Use of configs with services

Example 1: Configs with the command line interface

Create a configuration named "test_config":

$ echo "test configuration" | docker config create test_config -
$ docker config ls
$ docker config inspect test_config

Create a service that uses the configuration "test_config":

$ docker service create --name mynginx --config test_config nginx:latest
$ docker service ls
$ docker service ps mynginx 

Check for the config content inside the container:

# Get first the container id
$ docker ps --filter name=mynginx -q  
$ docker container exec f8e5bebfc87a cat /test_config  

The configuration is mounted as /test_config file in the container filesystem.

Example 2: Update the config while the service is running

Create a second version of the configuration test_config. The new config name ends with the version number "v2":

$ echo "test configuration v2" | docker config create test_config_v2 -
$ docker config ls

Update the service with the new configuration:

$ docker service update --config-rm test_config --config-add source=test_config_v2,target=/test_config mynginx
# Get the container id
$ docker ps --filter name=mynginx -q
$ docker container exec 61dac2cd0f33 cat /test_config 

When you are done, remove the service and the configurations:

$ docker service rm mynginx
$ docker config rm test_config test_config_v2
$ docker config ls

Example 3: Configs with docker compose file

In this tutorial, you will create a stack with two services MySQL and Adminer. The Adminer service allows a web access to the MySQL database server. A MySQL config file is created and attached to the MySQL service.

Create a docker-compose.yml file with the following content:

# Use root/mysqlpass as user/password credentials
version: '3.8'

services:
  db:
    image: mysql
    environment:
      MYSQL_ROOT_PASSWORD: mysqlpass
    configs:
      - source: mysql_config
        target: /etc/mysql/conf.d/mysql.cnf

  adminer:
    image: adminer
    ports:
      - 8080:8080

configs:
  mysql_config:
    file: ./mysql.cnf

Create a configuration file, named mysql.cnf, with the content:

$ cat mysql.cnf
[mysqld]
max_allowed_packet=50M
max_connections=200
default-authentication-plugin=mysql_native_password

Deploy the stack based on the docker-compose.yml file:

$ docker stack deploy -c docker-compose.yml myapp
$ docker stack ls
$ docker stack ps myapp

To check the configuration, browse to the address http://localhost:8080 then login to the MySQL server using the below parameters:

• System: MySQL
• Server: db
• Username: root
• Password: mysqlpass
• Database: (leave empty)

After connecting to the MySQL server, click on variables link and search for max_connections and max_allowed_packet variables. The values of the variables should be similar to those defined in the above mysql.cnf file.

When finishing with the tutorial, you may remove the stack and clean the pulled images:

$ docker stack rm myapp
$ docker image prune -f