github.com/nilium/gitlab-runner@v12.5.0+incompatible/docs/executors/docker_machine.md (about)

     1  # Install and register GitLab Runner for autoscaling with Docker Machine
     2  
     3  > The auto scale feature was introduced in GitLab Runner 1.1.0.
     4  
     5  For an overview of the autoscale architecture, take a look at the
     6  [comprehensive documentation on autoscaling](../configuration/autoscale.md).
     7  
     8  ## Forked version of Docker machine
     9  
    10  Because `docker-machine` is in [maintenance
    11  mode](https://github.com/docker/machine/issues/4537), GitLab is
    12  providing it's [own fork of
    13  `docker-machine`](https://gitlab.com/gitlab-org/ci-cd/docker-machine),
    14  which is based on the latest `master` branch of `docker-machine` with
    15  some additional patches for the following bugs:
    16  
    17  - [Make DigitalOcean driver RateLimit aware](https://gitlab.com/gitlab-org/ci-cd/docker-machine/merge_requests/2)
    18  - [Add backoff to google driver operations check](https://gitlab.com/gitlab-org/ci-cd/docker-machine/merge_requests/7)
    19  - [Add `--google-min-cpu-platform` option for machine creation](https://gitlab.com/gitlab-org/ci-cd/docker-machine/merge_requests/9)
    20  
    21  The intent of this fork is to fix critical and bugs affecting running
    22  costs only. No new features will be added.
    23  
    24  ## Preparing the environment
    25  
    26  In order to use the autoscale feature, Docker and GitLab Runner must be
    27  installed in the same machine:
    28  
    29  1. Log in to a new Linux-based machine that will serve as a bastion server
    30     where Docker will spawn new machines from
    31  1. [Install GitLab Runner](../install/index.md)
    32  1. [Install Docker Machine](https://docs.docker.com/machine/install-machine/)
    33  1. Optionally but recommended, prepare a
    34     [proxy container registry and a cache server](../install/registry_and_cache_servers.md)
    35     to be used with the autoscaled Runners
    36  
    37  If you need to use any virtualization/cloud providers that aren't handled by
    38  Docker's Machine internal drivers, the appropriate driver plugin must be
    39  installed. The Docker Machine driver plugin installation and configuration is
    40  out of the scope of this documentation. For more details please read the
    41  [Docker Machine documentation](https://docs.docker.com/machine/)
    42  
    43  ## Configuring GitLab Runner
    44  
    45  1. [Register a GitLab Runner](../register/index.md#gnulinux) and select the
    46     `docker+machine` executor when asked.
    47  1. Edit [`config.toml`](../commands/README.md#configuration-file) and configure
    48     the Runner to use Docker machine. Visit the dedicated page covering detailed
    49     information about [GitLab Runner Autoscaling](../configuration/autoscale.md).
    50  1. The **first time** you're using Docker Machine, it's best to execute manually
    51     `docker-machine create ...` with your chosen driver and all options from the
    52     `MachineOptions` section. This will set up the Docker Machine environment
    53     properly and will also be a good validation of the specified options.
    54     After this, you can destroy the machine with `docker-machine rm [machine_name]`
    55     and start the Runner.
    56  
    57     NOTE: **Note:**
    58     Multiple concurrent requests to `docker-machine create` that are done
    59     **at first usage** are not good. When the `docker+machine` executor is used,
    60     the Runner may spin up few concurrent `docker-machine create` commands. If
    61     Docker Machine was not used before in this environment, each started process
    62     tries to prepare SSH keys and SSL certificates (for Docker API authentication
    63     between Runner and Docker Engine on the autoscaled spawned machine), and these
    64     concurrent processes are disturbing each other. This can end with a non-working
    65     environment. That's why it's important to create a test machine manually the
    66     very first time you set up the Runner with Docker Machine.
    67  
    68  1. Now, you can try and start a new pipeline in your project. In a few seconds,
    69     if you run `docker-machine ls` you should see a new machine being created.
    70  
    71  ## Upgrading the Runner
    72  
    73  1. Check if your operating system is configured to automatically restart the
    74     Runner (for example, by checking its service file):
    75     - **if yes**, ensure that service manager is [configured to use `SIGQUIT`](../configuration/init.md)
    76       and use the service's tools to stop the process:
    77  
    78       ```
    79       # For systemd
    80       sudo systemctl stop gitlab-runner
    81  
    82       # For upstart
    83       sudo service gitlab-runner stop
    84       ```
    85  
    86     - **if no**, you may stop the Runner's process manually:
    87  
    88       ```bash
    89       sudo killall -SIGQUIT gitlab-runner
    90       ```
    91  
    92     NOTE: **Note:**
    93     Sending the [`SIGQUIT` signal](../commands/README.md#signals) will make the
    94     Runner to stop gracefully. It will stop accepting new jobs, and will exit
    95     as soon as the current jobs are finished.
    96  
    97  1. Wait until the Runner exits. You can check its status with `gitlab-runner status`
    98     or await a graceful shutdown for up to 30 minutes with:
    99  
   100     ```bash
   101     for i in `seq 1 180`; do # 1800 seconds = 30 minutes
   102         gitlab-runner status || break
   103         sleep 10
   104     done
   105     ```
   106  
   107  1. You can now safely install the new Runner without interrupting any jobs