GitLab CI Openstack

This Ansible role provides a setup for GitLab CI in Openstack.

Requirements

None.

Role Variables

GitLab-Runner variables

gitlab_runner_version: 15.3.0

The version of GitLab-Runner to install.

gitlab_runner_apt_repo: "deb https://packages.gitlab.com/runner/gitlab-runner/{{ ansible_distribution | lower }}/ {{ ansible_distribution_release }} main"

If this is specified the package will be installed from a .deb-file. If :// is in the path, Ansible will attempt to download deb before installing.

gitlab_runner_deb_file: ""

Identifier of GPG key that was used to sign the packages.

gitlab_gpg_key_id: "F6403F6544A38863DAA0B6E03F01618A51312F3F"

A list to specify expired GPG keys that should be absent.

gitlab_gpg_old_key_ids: []

The repository URL where to install the packages from.

gitlab_runner_concurrent: 1

Limits how many jobs can run concurrently. The maximum number is all defined runners. 0 does not mean unlimited.

gitlab_runner_install_docker: true

Decide wether to install Docker via geerlingguy.docker role. Docker is required for the docker executor but not for the docker+machine executor.

Docker-machine variables

gitlab_runner_docker_machine_binary_url: "https://gitlab.com/gitlab-org/ci-cd/docker-machine/-/releases/v0.16.2-gitlab.15/downloads/docker-machine-Linux-x86_64"

The URL where to download the docker-machine binary file from.

gitlab_runner_docker_machine_binary_checksum: "sha256:dc92e2d2a293d66545eb0719d4816d5ebc7ac9ba5495823bbf4eb01c6da37a6e"

The checksum of the downloaded docker-machine binary. This must correspond to the file downloaded via the gitlab_runner_docker_machine_binary_url variable.

Flatcar Linux configuration

gitlab_runner_transpiler_binary_url: https://github.com/coreos/container-linux-config-transpiler/releases/download/v0.9.0/ct-v0.9.0-x86_64-unknown-linux-gnu

The URL to the configuration transpiler binary that shall be used.

gitlab_runner_transpiler_binary_checksum: "sha256:31f4c3bd2219ba82b743bcbb4afab34a3e11e8a6512cefef407d9b6da0192adb"

The checksum of the download transpiler binary. This must correspond to the file downloaded via the gitlab_runner_transpiler_binary_url variable.

gitlab_runner_namerservers:
    - 9.9.9.9
    - 149.112.112.112

The DNS nameservers to be used by the Openstack Flatcar virtual machine.

gitlab_runner_registry_mirror: "https://registry-mirror.example"

(Optional) The Docker registry mirror to be used.

gitlab_runner_mtu: 1450

Configure the MTU (Maximum Transmission Unit) for the docker daemon in Flatcar linux running in Openstack. The default of 1450 is proven to work for default Openstack configurations. If you have a different setup, feel free to update this value.
Please note: This value can cause strange network issues if not configured properly.

gitlab_runner_ssh_public_key: "./files/id_ed25519.pub"
gitlab_runner_ssh_private_key: "./files/id_ed25519"

The (optional) file path to the SSH key pair on the Ansible controller used for communicating with Runners. If this is left empty the role creates a new SSH key pair at /etc/gitlab-runner/gitlab_runner_key(.pub).

gitlab_runner_ssh_key_type: "ed25519"

Specifies the type of SSH key to create. The possible values are ed25519 (default), ecdsa or rsa.

gitlab_runner_ssh_private_key_path: "/etc/gitlab-runner/gitlab_runner_key"
gitlab_runner_ssh_public_key_path: "/etc/gitlab-runner/gitlab_runner_key.pub"

The file paths to the SSH key pair on the Runner host.

GitLab-Runner registration

In order to register a runner with the GitLab instance of your choice, you need to edit the gitlab_runner_list variable and add a list entry. Each list entry corresponds to one registered GitLab-Runner.

Below table lists and describes all available configuration options you can specify for registering your GitLab-Runner with this Ansible role.

Key	Example	Description
name	"my-docker-runner"	The name of the registered runner.
url	"https://gitlab.com"	The URL of the GitLab instance you want to register the runner with.
description	"My first Docker runner"	Description of the runner.
registration_token	"MY_SECURE_TOKEN"	The registration token required to register the runner.
tags	["docker", "hifis"]	List of runner tags.
executor	docker	Specify, the runner executor.
environment	["DOCKER_TLS_CERTDIR=/certs"]	Append or overwrite environment variables.
docker_image	"python:3.8"	Specify the default docker image to be used. Required for docker and docker+machine executor.
docker_volumes	["/cache", "/certs/client"]	Additional volumes that should be mounted. Same syntax as the Docker -v flag.
docker_shm_size	2147483648	Shared memory size for images (in bytes). Default is 0 resulting in a fallback to the Docker default.
docker_privileged	False	Specify, if the container runs in privileged mode (insecure). Default is False.
docker_tls_verify	True	Specify, if TLS connections to the Docker daemon should be verified. Default is False.
run_untagged	False	Specify, if the runner can run jobs without tags.
locked	True	Specify, whether the runner is locked to the current project.
limit	0	Limit how many jobs can be handled concurrently by this token. Default is 0 (no limit).
machine_driver	"openstack"	The driver to use when creating the machine via docker-machine.
machine_name	"auto-scale-%s"	The machine name template. (You need to include %s).
machine_options	See the machine example.	Additional machine creation options.
machine_idle_count	2	Number of machines that need to be created and waiting in Idle state. Default is 0.
machine_idle_time	1800	Time (in seconds) for machine to be in Idle state before it is removed. Default is 0.
machine_max_growth_rate	1	The maximum number of machines that can be added to the runner in parallel. Default is 0 (no limit).
machine_max_builds	1	Maximum job (build) count before machine is removed. Default is 0.
cache_type	"s3"	Type of caching to use. Currently only s3 is supported by this role.
cache_server_address	"https://s3.hifis.net"	A host:port for the S3-compatible server.
cache_access_key	"key"	The access key specified for your S3 instance..
cache_secret_key	"secret"	The secret key specified for your S3 instance.
cache_bucket_name	"bucket-name"	Name of the storage bucket where cache is stored.
cache_insecure	"false"	Set to "true" if the S3 service is available by HTTP. Default is "false".

Docker Example

gitlab_runner_list:
    - name: "my-docker-runner"
      url: "https://gitlab.com"
      description: "My first Docker runner via Ansible."
      registration_token: ${REGISTRATION_TOKEN}
      tags: ["docker", "hifis"]
      executor: "docker"
      environment: ["CI_CPUS=8", "DOCKER_TLS_CERTDIR=/certs"]
      docker_image: "python:3.8"
      docker_volumes: ["/cache", "/certs/client"]
      run_untagged: False
      locked: True
      limit: 5
      # Optional cache configuration, only S3 is supported for now
      cache_type: "s3"
      cache_server_address: "https://cache.example"
      cache_access_key: "key"
      cache_secret_key: "secret"
      cache_bucket_name: "bucket"
      cache_insecure: "false"

For registering a runner using the Docker backend, a sample configuration is given above. Therefore, you need to obtain a registration token. This can be either done on an instance, a group or a project level. Visit the GitLab documentation for further information. In a production setup, please make sure to encrypt the token using Ansible Vault.

Docker-machine Example

gitlab_runner_list:
    - name: "test01"
      url: "https://gitlab.com"
      description: "Molecule test runner"
      registration_token: "REGISTRATION_TOKEN"
      executor: "docker+machine"
      docker_image: "python:3.8"
      docker_volumes: ["/cache", "/certs/client"]
      tags: ["docker", "hifis"]
      run_untagged: False
      locked: True
      machine_idle_count: 2
      machine_idle_time: 3600
      machine_max_growth_rate: 2
      machine_max_builds: 5
      machine_driver: "openstack"
      machine_name: "auto-scale-%s"
      machine_options:
        - "openstack-auth-url=https://openstack.example:5000/v3"
        - "openstack-image-id=73f07dd3-fa8b-468f-b6bc-b0cd4510f5d0"
        - "openstack-flavor-name=m1.small"
        - "openstack-net-id=7834deeb-8bd5-4fc7-b35b-24035d8f47a7"
        - "openstack-username=gitlab-runner"
        - "openstack-password=secret"
        - "openstack-tenant-id=123456"
        - "openstack-domain-name=default"
        - "openstack-ssh-user=core"
        - "openstack-sec-groups=Internal"
        - "openstack-keypair-name=runners-internal"
        - "openstack-private-key-file=/etc/gitlab-runner/gitlab_runner_key"
        - "openstack-user-data-file=/etc/gitlab-runner/ignition.json"
        - "openstack-active-timeout=300"
        - "engine-registry-mirror=https://registry-mirror.example"

The most important changes compared to the docker runner registration is the configuration of docker-machine. Therefore, a suitable configuration for the driver of your choice needs to be created. This project focuses on providing the best integration with Openstack but is probably not limited to that. The Openstack driver lists all possible configuration options that can be specified via machine_options: https://docs.docker.com/machine/drivers/openstack/

Docker-in-Docker if MTU other than 1500

If the Docker-MTU does not match 1500 which is very often the case for Openstack installations, certain additional configuration is required. Please make sure to add

"engine-opt=mtu={{ gitlab_runner_mtu }}"

to the list of your runner's machine_options. gitlab_runner_mtu needs to be set to the correct value.

Also you can configure Docker-in-Docker to make use of a registry mirror by setting gitlab_runner_registry_mirror to the required value. This is optional.

To make this all work you finally need to mount a file in your runner volume configuration by adding

"/opt/docker/daemon.json:/etc/docker/daemon.json:ro"

to the list of configured volumes.

Dependencies

GitLab-Runner for Openstack depends on docker-machine requiring docker to be available on the system.

• Docker - geerlingguy.docker

Example Playbook

Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:

- hosts: servers
  roles:
     - { role: username.rolename, x: 42 }

License

Apache-2.0

Author Information

This role was created by HIFIS Software Services.