What's the use of the [runners.docker] section in config.toml for use case with docker machine?

Question

reading the documentation on autoscaling I can't figure the role of the [runner.docker] section when using docker+machine as executor :

  [runners.docker]
    image = "ruby:2.1"               # The default image used for builds is 'ruby:2.1'

In the executors documentation it says :

docker+machine : like docker, but uses auto-scaled docker machines - this requires the presence of [runners.docker] and [runners.machine]

I get I have to define this [runners.docker] section to be able to use [runners.machine] section, but what is the aim of this [runners.docker] ? I can't find how to configure it as I don't understand why to use it.

Our gitlab-runner runs on a vSphere VM and is configured to scale using docker+machine executor with MachineDriver using vmwarevsphere. All works nice but I would like to understand fully the configuration file.

Here is our "censored with stars" config.toml file with the [runners.docker] I can't understand (note that the guy that wrote it leaved the company, so I can't ask him):

[[runners]]
  name = "gitlab-runner"
  limit = 6
  output_limit = 102400
  url = "http://gitlab.**************.lan"
  token = "*******************"
  executor = "docker+machine"

  [runners.docker]
    tls_verify = false
    image = "docker:latest"
    dns = ["*.*.*.*"]
    privileged = true
    disable_cache = false
    volumes = ["/etc/localtime:/etc/localtime:ro", "/var/run/docker.sock:/var/run/docker.sock", "/etc/docker/certs.d:/etc/docker/certs.d", "/cache:/cache", "/builds:/builds"]
    cache_dir = "cache"
    shm_size = 0

  [runners.cache]
    Type = "s3"
    ServerAddress = "*.*.*.*"
    AccessKey = "*****************"
    SecretKey = "*****************"
    BucketName = "runner"
    Insecure = true

  [runners.machine]
    IdleCount = 4
    MaxBuilds = 10
    IdleTime = 3600
    MachineDriver = "vmwarevsphere"
    MachineName = "gitlab-runner-pool-1-%s"
    MachineOptions = ["vmwarevsphere-username=************", "vmwarevsphere-password=*****************", "vmwarevsphere-vcenter=*.*.*.*", "vmwarevsphere-datastore=*********", "vmwarevsphere-memory-size=3096", "vmwarevsphere-disk-size=40960", "vmwarevsphere-cpu-count=3", "vmwarevsphere-network=*****************", "vmwarevsphere-datacenter=**************", "vmwarevsphere-hostsystem=*******************", "engine-storage-driver=overlay2", "engine-insecure-registry=**************", "engine-insecure-registry=*******************"]
    OffPeakPeriods = ["* * 0-8,21-23 * * mon-fri *", "* * * * * sat,sun *"]
    OffPeakTimezone = "Local"
    OffPeakIdleCount = 1
    OffPeakIdleTime = 600

Answer 1

The [runners.machine] section defines how to start and provision your runner machines, the [runners.docker] section then defines how to configure the runner on that machine.

Docker-machine on its own only does the following (as you can read here):

"Docker Machine is a tool that lets you install Docker Engine on virtual hosts, and manage the hosts with docker-machine commands."

So this does nothing with the Gitlab runner, you still need to configure the runner after that and thats where the [runners.docker] section comes into play because the runner needs to know what default image to use and what volumes to mount etc.