document refactoring of gitlab runner roles

service/ci.md

@@ -180,8 +180,8 @@ cluster, using this command:
           --backend-parameters memory=64g,vcpus=8 \
           ci-runner-01.torproject.org
 
-The `roles::gitlab::runner::docker` Puppet class deploys the GitLab
-runner code and hooks it into GitLab. It uses the
+The `role::gitlab::runner` Puppet class deploys the GitLab runner code
+and hooks it into GitLab. It uses the
 [gitlab_ci_runner](https://forge.puppet.com/modules/puppet/gitlab_ci_runner)
 module from Voxpupuli to avoid reinventing the wheel. But before
 enabling it on the instance, the following operations need to be
@@ -196,7 +196,7 @@ performed:
         mount /srv
         mount /var/lib/docker
 
- 3. disable module loading:
+ 2. disable module loading:
 
         touch /etc/no_modules_disabled
         reboot
@@ -204,8 +204,14 @@ performed:
     ... otherwise the Docker package will fail to install because it
     will try to load extra kernel modules.
 
- 4. *ONLY THEN* should you deploy `docker` and `gitlab-runner` through
-    Puppet.
+ 3. the default `gitlab::runner` role deploys a single docker runner
+    on the host. For group- or project-specific runners which need
+    special parameters (eg. for Docker), then a new role may be created
+    to pass those to the `profile::gitlab::runner` class using Hiera.
+    See `hiera/roles/gitlab::runner::shadow.yaml` for an example.
+
+ 4. *ONLY THEN* the Puppet agent may run to configure the executor,
+    install `gitlab-runner` and register it with GitLab.
 
 NOTE: we originally used the Debian packages ([docker.io](https://tracker.debian.org/pkg/docker.io) and
 [gitlab-runner](https://tracker.debian.org/gitlab-runner)) instead of the upstream official packages, because