Skip to main content

GitLab Runner Claim

General

The GitLabRunnerClaim is a way of requesting a GitLab runner. GitLabRunnerClaim resources can be created only in the Claim Namespace, which is isolated for each GitLabPipelinesIntegration.

Administrator (owner of Puzl account) always has full permissions on all GitLabRunnerClaim resources within the account. Integration Service Account always has full permissions on GitLabRunnerClaim resources only within its Claim Namespace.

Orchestrate Your GitLab Runners

GitLabRunnerClaim allows you to orchestrate the runners in 2 ways.

Unmanaged Runners

This is a standard way and fits the needs of the most users. We call such runners unmanaged, because Puzl does not interact with the API of your GitLab instance to create or delete the runners. To claim the unmanaged runner, follow these steps:

  1. Create a new runner in your GitLab instance (or take the token of the existing runner, for GitLab older than v16).
  2. Create file named my-unmanaged-runner.yaml and define spec of the GitLabRunnerClaim resource:
    • Take the received runner token and pass it to the spec.gitlab.token.
    • If you use GitLab instance older than v16, set the desired tags to the spec.gitlab.tags or set spec.gitlab.runUntaggedJobs: true.
    • Define other settings, available in the spec.pipelines section.
  3. Define other required resource settings. Here is the minimal possible configuration of the GitLabRunnerClaim to run unmanaged runner:
apiVersion: gitlab-pipelines.svcs.puzl.cloud/v1
kind: GitLabRunnerClaim
metadata:
  # Replace <Your_Integration_claimNamespaceRef> with the value retrieved from your GitLabIntegration resource.
  namespace: <Your_Integration_claimNamespaceRef>
  name: my-unmanaged-runner
spec:
  gitlab:
    token: <Your-GitLab-Token>

    # Tags are deprecated. Set up tags here only if you have GitLab v15 or earlier.
    tags:
      # Replace <Tag-1> and <Tag-2> with the required tags. Add more tags as needed.
      - <Tag-1>
      - <Tag-2>
  1. Apply your GitLabRunnerClaim resource to Puzl:
kubectl apply -f my-unmanaged-runner.yaml
  1. Once your GitLabRunnerClaim is in Ready phase, your runner is ready for processing the pipeline jobs.

Managed Runners

This flow provides you with a powerful tool to orchestrate dozens of teams and hundreds of runners. These runners are called managed, because Puzl takes control over the runner tokens issuing and management of runners via the API of your GitLab instance. This way, you can avoid using GitLab dashboard for your operations. Instead, you can manage all your GitLab runners via CI/CD, following the typical GitOps approach.

At the moment, this flow is not supported in the Puzl dashboard, you can use it only via Puzl API. Follow these steps to create a managed runner:

  1. Provide GitLab access token to the Claim Namespace as described here.

  2. Create file named my-managed-runner.yaml and define spec of the GitLabRunnerClaim resource:

    • Set spec.gitlab.runnerType to project_type, group_type, or instance_type.
    • Define either spec.gitlab.groupId or spec.gitlab.projectId depends on the scope you would like to create a runner for.
    • Define other settings, available in the spec.pipelines section.
    • Pass the desired tags to the spec.gitlab.tags field for GitLab instances older than v16.

  3. Define other required resource settings. Here is the minimal possible configuration of the GitLabRunnerClaim to create managed runner:

apiVersion: gitlab-pipelines.svcs.puzl.cloud/v1
kind: GitLabRunnerClaim
metadata:
  # Replace <Your_Integration_claimNamespaceRef> with the value retrieved from your GitLabIntegration resource.
  namespace: <Your_Integration_claimNamespaceRef>
  name: my-managed-runner
spec:
  gitlab:
    # You must pass either `projectId` or `groupId`, not both.
    projectId: <Integer_ID_Of_GitLab_Project_To_Register_Runner_For>
    groupId: <Integer_ID_Of_GitLab_Group_To_Register_Runner_For>

    # Tags are deprecated. Set up tags here only if you have GitLab v15 or earlier.
    tags:
      # Replace <Tag-1> and <Tag-2> with the required tags. Add more tags as needed.
      - <Tag-1>
      - <Tag-2>
  1. Apply your GitLabRunnerClaim resource to Puzl:
kubectl apply -f my-managed-runner.yaml
  1. Once your GitLabRunnerClaim is in Ready phase, your runner is created within your GitLab instance and is ready for processing the pipeline jobs.

metadata section

The metadata section is used to uniquely identify objects and to provide other information that is not directly tied to a resource's configuration.

namespace: string

Namespace defines the space within which each GitLabRunnerClaim name must be unique.

name: string

Each GitLabRunnerClaim name must be unique, within a namespace. The name must contain only lower-case letters, digits and dashes.

More Details

In this section, we've described only two fields that are necessary and sufficient for users on Puzl. For a more in-depth explanation of metadata and its various fields, refer to the official Kubernetes documentation.

spec section

The section defines the desired state of the object. It describes the characteristics you want the resource to have: its configuration, settings, and data.

spec.gitlab

The section contains all the settings for the GitLab runner creation and registration.

token: string
Path:spec.gitlab.token

Runner's authentication token. See more details in the official GitLab documentation.

For security reasons, token is immediately encrypted on a flight and can't be accessed by the user later once processed.

tags: [string]
Path:spec.gitlab.tags

Use tags to match the runner with the pipeline jobs, which this runner should run. Find more information about tags in the official GitLab documentation.

runnerType: string
Path:spec.gitlab.runnerType

The type of runner to create. This field is required when using the auto-creation flow. Must be one of project_type, group_type, or instance_type as per GitLab documentation.

Although GitLab versions earlier than 16.0 do not support the runner_type setting, we have generalized this setting to apply to all GitLab versions to make the configuration more intuitive.

groupId: integer
Path:spec.gitlab.groupId

Designates the target group for the runner when using the auto-creation flow. If specified, a new group runner will be created. For more details, please refer to the official GitLab documentation on group runners.

This field is required if runnerType is set to group_type.

projectId: integer
Path:spec.gitlab.projectId

Designates the target project for the runner when using the auto-creation flow. If specified, a new project runner will be created. For more details, please refer to the official GitLab documentation on project runners.

This field is required if runnerType is set to project_type.

protected: boolean
Path:spec.gitlab.protected

If true, the runner will only run jobs on protected branches, or jobs that have protected tags. For more details, please refer to the official GitLab documentation.

runUntaggedJobs: boolean
Path:spec.gitlab.runUntaggedJobs

If true, the runner will be allowed to run jobs which have no tags. For more details, please refer to the official GitLab documentation on untagged jobs.

spec.pipelines

The section contains all the settings for the GitLab runner's runtime.

ultimateJobTimeout: integer
Path:spec.pipelines.ultimateJobTimeout

Specifies the timeout duration in seconds for terminating the pipeline job, regardless of the pipeline configuration.

delayOnStartForJobsWithServices: integer
Default:30
Path:spec.pipelines.delayOnStartForJobsWithServices

Sets an initial delay in seconds for jobs that include services in their GitLab CI configuration. The delay helps to avoid job failures due to services not being fully ready at the start of the CI script. This is particularly useful when the CI script does not include checks for service readiness.

enableInteractiveWebTerminal: boolean
Path:spec.pipelines.enableInteractiveWebTerminal

Enables an external port for real-time debugging of the pipeline using the GitLab dashboard. More details can be found here.

spec.pipelines.resources

dropContainerResourceLimits: boolean
Default:True
Path:spec.pipelines.resources.dropContainerResourceLimits

Removes the cpu and memory limits from all pipeline job containers, allowing each container to utilize the full resources allocated to the job.

sharedPersistentMountPoints: [string]
Path:spec.pipelines.sharedPersistentMountPoints

Defines directories on the persistent Flexible Cloud Storage that will be created and made accessible across all containers within all pipeline jobs of this runner. These directories and their data persist beyond job executions.

You can share the same persistent directories among multiple runners within the same Integration. To achieve this, specify the same mount paths for each runner.

sharedMountPoints: [string]
Default:['/certs', '/var/run']
Path:spec.pipelines.sharedMountPoints

Defines directories that will be created and made accessible to all containers within one pipeline job. These directories and the data in them are ephemeral and will be erased after the job execution.

spec.runner

The section stores references to the runner's state and fully managed by the platform.

spec.runner.releaseRef

Internal platform reference to the current GitLab runner release.

name
: string
Path:spec.runner.releaseRef.name
namespace
: string
Path:spec.runner.releaseRef.namespace
pipelineNamespaceRef
: string
Path:spec.runner.pipelineNamespaceRef

Specifies the namespace where the pipeline jobs are executed by this runner.

status section

The section provides information about the current state of the object. It is populated by the platform and is used to inform users about the state of the resource, whether it's currently operational, and additional metadata like timestamps.

phase
: string
Default:Pending
Path:status.phase

Represents the high-level summary of the current status of the resource.

status.conditions[]

Conditions are designed based on Kubernetes API conventions. Conditions represent the logical states that the resource has passed through.

lastTransitionTime
: string
Path:status.conditions[].lastTransitionTime

The last time the condition transitioned from one status to another.

observedGeneration
: integer
Path:status.conditions[].observedGeneration

The value of metadata.generation when the condition has been transited last time.

message
: string
Path:status.conditions[].message

A human-readable message indicating details about the transition.

reason
: string
Path:status.conditions[].reason

A one-word, CamelCase reason caused the transition of the resource to this condition.

status
: string
Path:status.conditions[].status

The current status of the condition. Can be one of: True, False, or Unknown.

type
: string
Path:status.conditions[].type

Unique type of the resource condition.