Skip to content

Latest commit

 

History

History
859 lines (523 loc) · 24.7 KB

REFERENCE.md

File metadata and controls

859 lines (523 loc) · 24.7 KB
Raw

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • gitlab_ci_runner::config: Manages the configuration of Gitlab runner
  • gitlab_ci_runner::install: Manages the package of Gitlab runner
  • gitlab_ci_runner::repo: Manages the repository for Gitlab runner
  • gitlab_ci_runner::service: Manages the service of Gitlab runner

Defined types

Functions

Data types

Tasks

Classes

gitlab_ci_runner

This module installs and configures Gitlab CI Runners.

Examples

Simple runner registration
class { 'gitlab_ci_runner':
  runners => {
 	 example_runner => {
 		 'registration-token' => 'gitlab-token',
 		 'url'                => 'https://gitlab.com',
 		 'tag-list'           => 'docker,aws',
 	 },
  },
}

Parameters

The following parameters are available in the gitlab_ci_runner class:

runners

Data type: Hash

Hashkeys are used as $title in runners.pp. The subkeys have to be named as the parameter names from ´gitlab-runner register´ command cause they're later joined to one entire string using 2 hyphen to look like shell command parameters. See ´https://docs.gitlab.com/runner/register/#one-line-registration-command´ for details.

Default value: {}

runner_defaults

Data type: Hash

A hash with defaults which will be later merged with $runners.

Default value: {}

xz_package_name

Data type: String

The name of the 'xz' package. Needed for local docker installations.

concurrent

Data type: Optional[Integer]

Limits how many jobs globally can be run concurrently. The most upper limit of jobs using all defined runners. 0 does not mean unlimited!

Default value: undef

log_level

Data type: Optional[Gitlab_ci_runner::Log_level]

Log level (options: debug, info, warn, error, fatal, panic). Note that this setting has lower priority than level set by command line argument --debug, -l or --log-level

Default value: undef

log_format

Data type: Optional[Gitlab_ci_runner::Log_format]

Log format (options: runner, text, json). Note that this setting has lower priority than format set by command line argument --log-format

Default value: undef

check_interval

Data type: Optional[Integer]

Defines the interval length, in seconds, between new jobs check. The default value is 3; if set to 0 or lower, the default value will be used.

Default value: undef

shutdown_timeout

Data type: Optional[Integer]

Number of seconds until the forceful shutdown operation times out and exits the process.

Default value: undef

sentry_dsn

Data type: Optional[String]

Enable tracking of all system level errors to sentry.

Default value: undef

listen_address

Data type: Optional[Pattern[/.*:.+/]]

Address (:) on which the Prometheus metrics HTTP server should be listening.

Default value: undef

session_server

Data type: Optional[Gitlab_ci_runner::Session_server]

Session server lets users interact with jobs, for example, in the interactive web terminal.

Default value: undef

manage_docker

Data type: Boolean

If docker should be installs (uses the puppetlabs-docker).

Default value: false

manage_repo

Data type: Boolean

If the repository should be managed.

Default value: true

package_ensure

Data type: String

The package 'ensure' state.

Default value: installed

package_name

Data type: String

The name of the package.

Default value: 'gitlab-runner'

repo_base_url

Data type: Stdlib::HTTPUrl

The base repository url.

Default value: 'https://packages.gitlab.com'

repo_keyserver

Data type: Optional[Gitlab_ci_runner::Keyserver]

The keyserver which should be used to get the repository key.

Default value: undef

config_path

Data type: String

The path to the config file of Gitlab runner.

Default value: '/etc/gitlab-runner/config.toml'

config_owner

Data type: String[1]

The user owning the config file. (and config directory if managed).

Default value: 'root'

config_group

Data type: String[1]

The group ownership assigned to the config file (and config directory if managed).

Default value: 'root'

config_mode

Data type: Stdlib::Filemode

The file permissions applied to the config file.

Default value: '0444'

manage_config_dir

Data type: Boolean

Manage the parent directory of the config file.

Default value: false

config_dir_mode

Data type: Optional[Stdlib::Filemode]

The file permissions applied to the config directory.

Default value: undef

http_proxy

Data type: Optional[Stdlib::HTTPUrl]

An HTTP proxy to use whilst registering runners. This setting is only used when registering or unregistering runners and will be used for all runners in the runners parameter. If you have some runners that need to use a proxy and others that don't, leave runners and http_proxy unset and declare gitlab_ci_runnner::runner resources separately. If you do need to use an http proxy, you'll probably also want to configure other aspects of your runners to use it, (eg. setting http_proxy environment variables, pre-clone-script, pre-build-script etc.) Exactly how you might need to configure your runners varies between runner executors and specific use-cases. This module makes no attempt to automatically alter your runner configurations based on the value of this parameter. More information on what you might need to configure can be found here

Default value: undef

ca_file

Data type: Optional[Stdlib::Unixpath]

A file containing public keys of trusted certificate authorities in PEM format. This setting is only used when registering or unregistering runners and will be used for all runners in the runners parameter. It can be used when the certificate of the gitlab server is signed using a CA and when upon registering a runner the following error is shown: certificate verify failed (self signed certificate in certificate chain) Using the CA file solves voxpupuli#124. The ca_file must exist. If it doesn't, Gitlab runner token generation will be skipped. Gitlab runner will not register until either the file exists or the ca_file parameter is not specified.

Default value: undef

repo_keysource

Data type: Stdlib::HTTPSUrl

URL to the gpg file used to sign the apt packages

Default value: "${repo_base_url}/gpg.key"

Defined types

gitlab_ci_runner::runner

This configures a Gitlab CI runner.

Examples

Add a simple runner
gitlab_ci_runner::runner { 'testrunner':
  config               => {
    'url'              => 'https://gitlab.com',
    'token'            => '123456789abcdefgh', # Note this is different from the registration token used by `gitlab-runner register`
    'executor'         => 'shell',
  },
}
Add a autoscaling runner with DigitalOcean as IaaS
gitlab_ci_runner::runner { 'autoscale-runner':
  config => {
    url      => 'https://gitlab.com',
    token    => 'RUNNER_TOKEN', # Note this is different from the registration token used by `gitlab-runner register`
    name     => 'autoscale-runner',
    executor => 'docker+machine',
    limit    => 10,
    docker   => {
      image => 'ruby:2.6',
    },
    machine  => {
      OffPeakPeriods   => [
        '* * 0-9,18-23 * * mon-fri *',
        '* * * * * sat,sun *',
      ],
      OffPeakIdleCount => 1,
      OffPeakIdleTime  => 1200,
      IdleCount        => 5,
      IdleTime         => 600,
      MaxBuilds        => 100,
      MachineName      => 'auto-scale-%s',
      MachineDriver    => 'digitalocean',
      MachineOptions   => [
        'digitalocean-image=coreos-stable',
        'digitalocean-ssh-user=core',
        'digitalocean-access-token=DO_ACCESS_TOKEN',
        'digitalocean-region=nyc2',
        'digitalocean-size=4gb',
        'digitalocean-private-networking',
        'engine-registry-mirror=http://10.11.12.13:12345',
      ],
    },
    cache    => {
      'Type' => 's3',
      s3     => {
        ServerAddress => 's3-eu-west-1.amazonaws.com',
        AccessKey     => 'AMAZON_S3_ACCESS_KEY',
        SecretKey     => 'AMAZON_S3_SECRET_KEY',
        BucketName    => 'runner',
        Insecure      => false,
      },
    },
  },
}

Parameters

The following parameters are available in the gitlab_ci_runner::runner defined type:

config

Data type: Hash

Hash with configuration options. See https://docs.gitlab.com/runner/configuration/advanced-configuration.html for all possible options. If you omit the 'name' configuration, we will automatically use the $title of this define class.

ensure

Data type: Enum['present', 'absent']

If the runner should be 'present' or 'absent'. Will add/remove the configuration from config.toml Will also register/unregister the runner.

Default value: 'present'

ca_file

Data type: Optional[Stdlib::Unixpath]

A path to a file containing public keys of trusted certificate authorities in PEM format. Used during runner registration/unregistration only.

Default value: undef

http_proxy

Data type: Optional[Stdlib::HTTPUrl]

Default value: undef

Functions

gitlab_ci_runner::register

Type: Ruby 4.x API

A function that registers a Gitlab runner on a Gitlab instance. Be careful, this will be triggered on noop runs as well!

Examples

Using it as a replacement for the Bolt 'register_runner' task
puppet apply -e "notice(gitlab_ci_runner::register('https://gitlab.com', 'registration-token'))"

gitlab_ci_runner::register(Stdlib::HTTPUrl $url, String[1] $token, Optional[Gitlab_ci_runner::Register] $additional_options, Optional[Optional[Stdlib::Unixpath]] $ca_file)

A function that registers a Gitlab runner on a Gitlab instance. Be careful, this will be triggered on noop runs as well!

Returns: Struct[{ id => Integer[1], token => String[1], }] Returns a hash with the runner id and authentcation token

Examples
Using it as a replacement for the Bolt 'register_runner' task
puppet apply -e "notice(gitlab_ci_runner::register('https://gitlab.com', 'registration-token'))"
url

Data type: Stdlib::HTTPUrl

The url to your Gitlab instance. Please only provide the host part (e.g https://gitlab.com)

token

Data type: String[1]

Registration token.

additional_options

Data type: Optional[Gitlab_ci_runner::Register]

A hash with all additional configuration options for that runner

ca_file

Data type: Optional[Optional[Stdlib::Unixpath]]

An absolute path to a trusted certificate authority file.

gitlab_ci_runner::register_to_file

Type: Ruby 4.x API

A function that registers a Gitlab runner on a Gitlab instance, if it doesn't already exist, and saves the retrieved authentication token to a file. This is helpful for Deferred functions.

Examples

Using it as a Deferred function
gitlab_ci_runner::runner { 'testrunner':
  config               => {
    'url'              => 'https://gitlab.com',
    'token'            => Deferred('gitlab_ci_runner::register_runner_to_file', [$config['url'], $config['registration-token'], 'testrunner'])
    'executor'         => 'shell',
  },
}

gitlab_ci_runner::register_to_file(String[1] $url, String[1] $regtoken, String[1] $runner_name, Optional[Hash] $additional_options, Optional[Optional[String[1]]] $proxy, Optional[Optional[String[1]]] $ca_file)

A function that registers a Gitlab runner on a Gitlab instance, if it doesn't already exist, and saves the retrieved authentication token to a file. This is helpful for Deferred functions.

Returns: String[1] Returns the authentication token

Examples
Using it as a Deferred function
gitlab_ci_runner::runner { 'testrunner':
  config               => {
    'url'              => 'https://gitlab.com',
    'token'            => Deferred('gitlab_ci_runner::register_runner_to_file', [$config['url'], $config['registration-token'], 'testrunner'])
    'executor'         => 'shell',
  },
}
url

Data type: String[1]

The url to your Gitlab instance. Please only provide the host part (e.g https://gitlab.com)

regtoken

Data type: String[1]

Registration token.

runner_name

Data type: String[1]

The name of the runner. Use as identifier for the retrieved auth token.

additional_options

Data type: Optional[Hash]

A hash with all additional configuration options for that runner

proxy

Data type: Optional[Optional[String[1]]]

The HTTP proxy to use when registering

ca_file

Data type: Optional[Optional[String[1]]]

An absolute path to a trusted certificate authority file.

gitlab_ci_runner::to_toml

Type: Ruby 4.x API

Convert a data structure and output to TOML.

Examples

How to output TOML to a file
file { '/tmp/config.toml':
  ensure  => file,
  content => to_toml($myhash),
}

gitlab_ci_runner::to_toml(Hash $data)

The gitlab_ci_runner::to_toml function.

Returns: String Converted data as TOML string

Examples
How to output TOML to a file
file { '/tmp/config.toml':
  ensure  => file,
  content => to_toml($myhash),
}
data

Data type: Hash

Data structure which needs to be converted into TOML

gitlab_ci_runner::unregister

Type: Ruby 4.x API

A function that unregisters a Gitlab runner from a Gitlab instance. Be careful, this will be triggered on noop runs as well!

Examples

Using it as a replacement for the Bolt 'unregister_runner' task
puppet apply -e "notice(gitlab_ci_runner::unregister('https://gitlab.com', 'runner-auth-token'))"

gitlab_ci_runner::unregister(Stdlib::HTTPUrl $url, String[1] $token, Optional[Optional[Stdlib::Unixpath]] $ca_file)

A function that unregisters a Gitlab runner from a Gitlab instance. Be careful, this will be triggered on noop runs as well!

Returns: Struct[{ status => Enum['success'], }] Returns a hash with the runner id and authentcation token

Examples
Using it as a replacement for the Bolt 'unregister_runner' task
puppet apply -e "notice(gitlab_ci_runner::unregister('https://gitlab.com', 'runner-auth-token'))"
url

Data type: Stdlib::HTTPUrl

The url to your Gitlab instance. Please only provide the host part (e.g https://gitlab.com)

token

Data type: String[1]

Runners authentication token.

ca_file

Data type: Optional[Optional[Stdlib::Unixpath]]

An absolute path to a trusted certificate authority file.

gitlab_ci_runner::unregister_from_file

Type: Ruby 4.x API

A function that unregisters a Gitlab runner from a Gitlab instance, if the local token is there. This is meant to be used in conjunction with the gitlab_ci_runner::register_to_file function.

Examples

Using it as a Deferred function with a file resource
file { '/etc/gitlab-runner/auth-token-testrunner':
  file    => absent,
  content => Deferred('gitlab_ci_runner::unregister_from_file', ['http://gitlab.example.org'])
}

gitlab_ci_runner::unregister_from_file(String[1] $url, String[1] $runner_name, Optional[Optional[String[1]]] $proxy, Optional[Optional[String[1]]] $ca_file)

A function that unregisters a Gitlab runner from a Gitlab instance, if the local token is there. This is meant to be used in conjunction with the gitlab_ci_runner::register_to_file function.

Returns: Any

Examples
Using it as a Deferred function with a file resource
file { '/etc/gitlab-runner/auth-token-testrunner':
  file    => absent,
  content => Deferred('gitlab_ci_runner::unregister_from_file', ['http://gitlab.example.org'])
}
url

Data type: String[1]

The url to your Gitlab instance. Please only provide the host part (e.g https://gitlab.com)

runner_name

Data type: String[1]

The name of the runner. Use as identifier for the retrived auth token.

proxy

Data type: Optional[Optional[String[1]]]

HTTP proxy to use when unregistering

ca_file

Data type: Optional[Optional[String[1]]]

An absolute path to a trusted certificate authority file.

Data types

Gitlab_ci_runner::Keyserver

Type to match repo_keyserver Regex from: https://github.com/puppetlabs/puppetlabs-apt/blob/main/manifests/key.pp

Alias of Pattern[/\A((hkp|hkps|http|https):\/\/)?([a-z\d])([a-z\d-]{0,61}\.)+[a-z\d]+(:\d{2,5})?(\/[a-zA-Z\d\-_.]+)*\/?$/]

Gitlab_ci_runner::Log_format

Gitlab Runner log format configuration

Alias of Enum['runner', 'text', 'json']

Gitlab_ci_runner::Log_level

Gitlab Runner log level configuration

Alias of Enum['debug', 'info', 'warn', 'error', 'fatal', 'panic']

Gitlab_ci_runner::Register

A struct of all possible additionl options for gitlab_ci_runner::register

Alias of

Struct[{
  Optional[description]     => String[1],
  Optional[info]            => Hash[String[1],String[1]],
  Optional[active]          => Boolean,
  Optional[locked]          => Boolean,
  Optional[run_untagged]    => Boolean,
  Optional[tag_list]        => Array[String[1]],
  Optional[access_level]    => Enum['not_protected', 'ref_protected'],
  Optional[maximum_timeout] => Integer,
}]

Gitlab_ci_runner::Register_parameters

A enum containing a possible keys used for Gitlab runner registrations

Alias of Enum['description', 'info', 'active', 'locked', 'run_untagged', 'run-untagged', 'tag_list', 'tag-list', 'access_level', 'access-level', 'maximum_timeout', 'maximum-timeout']

Gitlab_ci_runner::Session_server

Gitlab Runner session_server configuration

Alias of

Struct[{
    listen_address    => String[1],
    advertise_address => String[1],
    session_timeout   => Optional[Integer],
  }]

Tasks

register_runner

Registers a runner on a Gitlab instance.

Supports noop? false

Parameters

url

Data type: String[1]

The url to your Gitlab instance. Please only provide the host part (e.g https://gitlab.com)

token

Data type: String[1]

Registration token.

description

Data type: Optional[String[1]]

Runners description.

info

Data type: Optional[Hash]

Runners metadata.

active

Data type: Optional[Boolean]

Whether the Runner is active.

locked

Data type: Optional[Boolean]

Whether the Runner should be locked for current project.

run_untagged

Data type: Optional[Boolean]

Whether the Runner should handle untagged jobs.

tag_list

Data type: Optional[Array[String[1]]]

List of Runners tags.

access_level

Data type: Optional[Enum['not_protected', 'ref_protected']]

The access_level of the runner.

maximum_timeout

Data type: Optional[Integer[1]]

Maximum timeout set when this Runner will handle the job.

unregister_runner

Unregisters a runner from a Gitlab instance.

Supports noop? false

Parameters

url

Data type: String[1]

The url to your Gitlab instance. Please provide the host part only! (e.g https://gitlab.com)

token

Data type: String[1]

Runners authentication token.