cdk-gitlab-runner

2.4.18 · active · verified Thu Apr 16

cdk-gitlab-runner is a Python library that leverages AWS CDK to provision and manage GitLab CI/CD runners within your AWS environment. It supports various configurations, including Fargate and EC2 instances, enabling users to quickly deploy self-hosted runners to execute GitLab pipeline jobs. The library is actively maintained, with frequent updates to support new AWS CDK and GitLab Runner features, and the current version is 2.4.18.

Common errors

```
Error: spawnSync docker ENOENT
```
cause The `docker` command is not found in the execution environment of the CDK deployment or synth process, usually when the CDK app attempts to build a Docker image.

fix Install Docker on the machine or CI/CD runner executing the CDK commands. For CI environments, ensure the Docker service is running and accessible to the user running the pipeline.
```
Deployment Failure Due to Missing Permissions
```
cause The IAM role used by the AWS CDK deployment (or the CloudFormation execution role) lacks the necessary permissions to create, update, or delete AWS resources defined in your stack.

fix Review the IAM permissions attached to the role used for CDK deployments. Ensure it has permissions for all AWS services and actions required by your `cdk-gitlab-runner` stack (e.g., EC2, VPC, IAM, S3, Secrets Manager).
```
context value not found for key 'vpc-provider:account=...'
```
cause CDK's context (e.g., for VPC lookups) is outdated or missing, preventing it from resolving environment-specific information.

fix Run `cdk context --reset` to clear cached context values, then re-run `cdk synth` or `cdk deploy` to refresh the context. Alternatively, provide explicit VPC IDs and other resources instead of relying on lookups.
```
Job stalls and doesn't want to start even though your runner is available
```
cause The GitLab CI job's `tags` do not match any of the `runner_tags` configured for your `cdk-gitlab-runner` instance.

fix Verify that the `tags` array in your `.gitlab-ci.yml` for the failing job includes at least one tag present in the `runner_tags` array passed to `GitlabContainerRunner`.
```
No URL provided, cache will not be download / uploaded
```
cause This error in GitLab Runner logs indicates an issue with cache configuration, where the runner helper cannot get valid pre-signed URLs to access the remote cache (e.g., S3).

fix Review your GitLab Runner's `config.toml` (managed by `cdk-gitlab-runner`) and ensure the cache section is correctly configured, including S3 bucket details and IAM permissions for the runner to access the cache bucket. Ensure the helper image is up-to-date.

Warnings

gotcha Hardcoding GitLab Runner Tokens is a security risk. Always use AWS Secrets Manager or SSM Parameter Store to manage and retrieve sensitive tokens.
Fix: Store your GitLab token in AWS Secrets Manager or SSM Parameter Store and retrieve it at runtime, e.g., `ssm.StringParameter.value_from_lookup(self, '/gitlab/runner/token')`.
breaking GitLab Runner versions have compatibility requirements with GitLab server versions and features. Using an incompatible runner version can lead to unexpected behavior or features not working.
Fix: Refer to the official GitLab Runner documentation for compatibility matrices. Ensure the `gitlab_runner_version` parameter in `GitlabContainerRunner` is compatible with your GitLab instance and desired features.
gotcha If your CDK application involves building Docker images locally or within the CI/CD pipeline, the Docker daemon must be accessible in the environment where `cdk deploy` or `cdk synth` is executed.
Fix: Ensure Docker is installed and running on the machine or CI runner performing CDK operations. For Docker-in-Docker (DinD) scenarios, consider the security implications of privileged containers.
gotcha For features like Docker-in-Docker (DinD), the GitLab Runner container often requires 'privileged' mode. This grants extensive capabilities to the container and poses a significant security risk if untrusted code is executed.
Fix: Only use privileged mode if absolutely necessary and fully understand the security implications. Limit the scope of jobs running in privileged containers and implement strict access controls.
gotcha Jobs may stall or not be picked up by runners if the `runner_tags` defined in your `cdk-gitlab-runner` stack do not match the tags specified in your `.gitlab-ci.yml` jobs.
Fix: Carefully define and verify that the `runner_tags` in your `GitlabContainerRunner` configuration precisely match the `tags` specified in your GitLab CI/CD job definitions.

Install

pip install cdk-gitlab-runner Install latest version

Imports

GitlabContainerRunner

from cdk_gitlab_runner import GitlabContainerRunner

BlockDuration

from cdk_gitlab_runner import BlockDuration

Quickstart

This quickstart deploys a GitLab Container Runner on an EC2 instance within your default VPC using AWS CDK. It retrieves the GitLab Runner token from an environment variable (recommended for security) and configures the runner with a specific GitLab Runner version, EC2 instance type, and Docker image. Remember to set the `GITLAB_RUNNER_TOKEN` environment variable or replace the placeholder.

import os
from aws_cdk import App, Stack
from cdk_gitlab_runner import GitlabContainerRunner
from aws_cdk.aws_ec2 import Vpc


class MyGitlabRunnerStack(Stack):
    def __init__(self, scope: App, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Retrieve an existing VPC by ID or create a new one
        # For simplicity, a default VPC lookup is used. In production, provide a specific vpc_id.
        # Ensure your AWS account is bootstrapped and CDK context is up-to-date for VPC lookup.
        vpc = Vpc.from_lookup(self, "VPC", is_default=True)

        # Get GitLab Token from environment variable (secure practice)
        gitlab_token = os.environ.get('GITLAB_RUNNER_TOKEN', 'glrt-YOUR_GITLAB_TOKEN_HERE')

        if gitlab_token == 'glrt-YOUR_GITLAB_TOKEN_HERE':
            print("WARNING: Replace 'glrt-YOUR_GITLAB_TOKEN_HERE' with a real GitLab Runner Token or set GITLAB_RUNNER_TOKEN env var.")

        # Create a GitLab Container Runner
        runner = GitlabContainerRunner(
            self, 
            'MyGitlabRunner',
            vpc=vpc,
            gitlab_token=gitlab_token,
            gitlab_runner_version='16.9.1', # Specify a compatible GitLab Runner version
            ec2_type='t3.micro', # Instance type for the runner
            docker_image_name='python:3.9-slim-buster', # Docker image for jobs
            runner_tags=['aws', 'cdk', 'python'], # Tags for matching jobs
        )

app = App()
MyGitlabRunnerStack(app, "MyGitlabRunnerStack")
app.synth()

view raw JSON →