Dedicated runners¶

Dedicated runners are single servers that run the gitlab-runner daemon, and execute jobs in Docker installed on the local host. This is done using the upstream Docker Executor.

This type of runner is best suited for small projects and/or teams that require a small amount of runners with predictable pricing, or if a special configuration of machine is required for a specific project and/or group.

Required settings¶

The examples below are concise and get you started with the basic default values.

Terraform settings¶

To get started with dedicated GitLab Runners, the following configuration is an example for two dedicated runners:

dedicated_runner_node_list = [
  {
    name          = "small"
    instance_type = "t3a.small"
  },
  {
    name          = "medium"
    instance_type = "t3a.medium"
  }
]

When not set manually, Terraform picks a subnet based on the name variable of the runner. This ensures the machine is not re-created every time the node list changes.

Because of this, it is recommended to not change the name of the runner node after deployment.

Ansible settings¶

There is no special configuration, and you can follow the example in Shared Ansible settings.

Optional settings are also available, please refer to the following sections:

Terraform optional node settings¶

In addition to the basic settings above, there are multiple values available to override on a per-runner basis. If you need these settings on all your runners, please refer to the Terraform optional default settings below.

# The object type definition of a dedicated runner node
dedicated_runner_node_list = list(object({
  name          = string  # Name of the instance, for example: 'dedicated-small'
  instance_type = string  # Instance type, for example: 't3a.small'

  ami_id        = optional(string)  # If you need a custom AWS AMI instead of the cluster default
  subnet_id     = optional(string)  # If you manually want to assign the subnet the runner lives in

  additional_tags        = optional(map(any), {})      # Any additional tags in AWS set on the EC2 and EBS objects
  additional_policy_arns = optional(list(string), [])  # These ARNs are added to the IAM role the EC2 machine has

  disk_type                  = optional(string)  # If you need a different EBS root volume type
  disk_size                  = optional(string)  # If you need a different EBS root volume size
  disk_iops                  = optional(number)  # If you need more (or less) IOPS on the EBS root volume
  disk_delete_on_termination = optional(bool)    # If you need to keep the EBS volume after the instance is terminated
  disk_encrypt               = optional(bool)    # Can be used to deviate from cluster-wide encryption configuration
  disk_kms_key_arn           = optional(string)  # Can be used to deviate from cluster-wide encryption configuration
}))

Terraform optional default settings¶

On the Terraform side of the configuration, there is support for a set of default values for each runner. When set, these values are used when the matching parameter is not defined in the dedicated_runner_node_list mapping.

Configuring this is entirely optional, and it's possible to create runners without setting any of the following values:

Name	Default	Description
`dedicated_runner_default_disk_type`	`gp3`	Change the default EBS volume type
`dedicated_runner_default_disk_size`	`25`	Change the default EBS volume size
`dedicated_runner_default_disk_iops`	`null`	Change the default EBS volume IOPS count
`dedicated_runner_default_disk_delete_on_termination`	`true`	Turn this off to keep the EBS volume
`dedicated_runner_default_disk_encrypt`	`null`	Used to deviate from cluster-wide defaults
`dedicated_runner_default_disk_kms_key_arn`	`null`	Used to deviate from cluster-wide defaults
`dedicated_runner_default_iam_instance_policy_arns`	`[]`	Will be added to the EC2 instance role