AWS CDK GitLab Runner autoscaling on EC2

This project provides a CDK construct to execute jobs on auto-scaled EC2 instances using the Docker Machine executor.

Running out of Runner minutes, using Docker-in-Docker (dind), speed up jobs with shared S3 Cache, cross compiling/building environment multiarch, cost effective autoscaling on EC2, deploy directly from AWS accounts (without AWS Access Key), running on Spot instances, having a bigger build log size

Install

TypeScript

npm install @pepperize/cdk-autoscaling-gitlab-runner

or

yarn add @pepperize/cdk-autoscaling-gitlab-runner

Python

pip install pepperize.cdk-autoscaling-gitlab-runner

C# / .Net

dotnet add package Pepperize.CDK.AutoscalingGitlabRunner

Java

<dependency>
  <groupId>com.pepperize</groupId>
  <artifactId>cdk-autoscaling-gitlab-runner</artifactId>
  <version>${cdkAutoscalingGitlabRunner.version}</version>
</dependency>

Quickstart

Create a new AWS CDK App in TypeScript with projen

mkdir gitlab-runner
cd gitlab-runner
git init
npx projen new awscdk-app-ts

Configure your project in .projenrc.js
- Add deps: ["@pepperize/cdk-autoscaling-gitlab-runner"],
Update project files and install dependencies
```
npx projen
```
Register a new runner

Registering runners:
- For a shared runner, go to the GitLab Admin Area and click Overview > Runners
- For a group runner, go to Settings > CI/CD and expand the Runners section
- For a project runner, go to Settings > CI/CD and expand the Runners section
Optionally enable: Run untagged jobs [x] Indicates whether this runner can pick jobs without tags

See also Registration token vs. Authentication token

Retrieve a new runner authentication token

Register a new runner

curl --request POST "https://gitlab.com/api/v4/runners" --form "token=<your register token>" --form "description=gitlab-runner" --form "tag_list=pepperize,docker,production"

Store runner authentication token in SSM ParameterStore

Create a String parameter

aws ssm put-parameter --name "/gitlab-runner/token" --value "<your runner authentication token>" --type "String"

Add to your main.ts

import { Vpc } from "@aws-cdk/aws-ec2";
import { App, Stack } from "@aws-cdk/core";
import { GitlabRunnerAutoscaling } from "@pepperize/cdk-autoscaling-gitlab-runner";

const app = new App();
const stack = new Stack(app, "GitLabRunnerStack");
const vpc = Vpc.fromLookup(app, "ExistingVpc", {
  vpcId: "<your vpc id>",
});
const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});
new GitlabRunnerAutoscaling(stack, "GitlabRunner", {
  network: {
    vpc: vpc,
  },
  runners: [
    {
      token: token,
      configuration: {
        // optionally configure your runner
      },
    },
  ],
});

Create service linked role

(If requesting spot instances, default: true)

aws iam create-service-linked-role --aws-service-name spot.amazonaws.com

Configure the AWS CLI
Deploy the GitLab Runner
```
npm run deploy
```

Example

Custom cache bucket

By default, an AWS S3 Bucket is created as GitLab Runner's distributed cache. It's encrypted and public access is blocked. A custom S3 Bucket can be configured:

const cache = new Bucket(this, "Cache", {
  // Your custom bucket
});
const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      token: token,
    },
  ],
  cache: { bucket: cache },
});

See example, GitlabRunnerAutoscalingCacheProps

Custom EC2 key pair

By default, the amazonec2 driver will create an EC2 key pair for each runner. To use custom ssh credentials provide a SecretsManager Secret with the private and public key file:

Create a key pair, download the private key file and remember the created key pair name

Generate the public key file

ssh-keygen -f <the downloaded private key file> -y

Create an AWS SecretsManager Secret from the key pair

aws secretsmanager create-secret --name <the secret name> --secret-string "{\"<the key pair name>\":\"<the private key>\",\"<the key pair name>.pub\":\"<the public key>\"}"

Configure the job runner

const keyPair = Secret.fromSecretNameV2(stack, "Secret", "CustomEC2KeyPair");

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      keyPair: keyPair,
      configuration: {
        machine: {
          machineOptions: {
            keypairName: "<the key pair name>",
          },
        },
      },
    },
  ],
  cache: { bucket: cache },
});

Configure Docker Machine

By default, docker machine is configured to run privileged with CAP_SYS_ADMIN to support Docker-in-Docker using the OverlayFS driver and cross compiling/building with multiarch.

See runners.docker section in Advanced configuration

import { GitlabRunnerAutoscaling } from "@pepperize/cdk-autoscaling-gitlab-runner";
import { StringParameter } from "aws-cdk-lib/aws-ssm";

const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      token: token,
      configuration: {
        environment: [], // Reset the OverlayFS driver for every project
        docker: {
          capAdd: [], // Remove the CAP_SYS_ADMIN
          privileged: false, // Run unprivileged
        },
        machine: {
          idleCount: 2, // Number of idle machine
          idleTime: 3000, // Waiting time in idle state
          maxBuilds: 1, // Max builds before instance is removed
        },
      },
    },
  ],
});

See example, DockerConfiguration

Bigger instance type

By default, t3.nano is used for the manager/coordinator and t3.micro instances will be spawned. For bigger projects, for example with webpack, this won't be enough memory.

const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  manager: {
    instanceType: InstanceType.of(InstanceClass.T3, InstanceSize.SMALL),
  },
  runners: [
    {
      instanceType: InstanceType.of(InstanceClass.T3, InstanceSize.LARGE),
      token: token,
      configuration: {
        // optionally configure your runner
      },
    },
  ],
});

You may have to disable or configure Spot instances

See example, GitlabRunnerAutoscalingManagerProps, GitlabRunnerAutoscalingJobRunnerProps

Different machine image

By default, the latest Amazon 2 Linux will be used for the manager/coordinator. The manager/coordinator instance's cloud init scripts requires yum is installed, any RHEL flavor should work. The requested runner instances by default using Ubuntu 20.04, any OS implemented by the Docker Machine provisioner should work.

const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  manager: {
    machineImage: MachineImage.genericLinux(managerAmiMap),
  },
  runners: [
    {
      machineImage: MachineImage.genericLinux(runnerAmiMap),
      token: token,
      configuration: {
        // optionally configure your runner
      },
    },
  ],
});

See example, GitlabRunnerAutoscalingManagerProps, GitlabRunnerAutoscalingJobRunnerProps

Multiple runners configuration

Each runner defines one [[runners]] section in the configuration file. Use Specific runners when you want to use runners for specific projects.

const privilegedRole = new Role(this, "PrivilegedRunnersRole", {
  // role 1
});

const restrictedRole = new Role(this, "RestrictedRunnersRole", {
  // role 2
});

const token1 = StringParameter.fromStringParameterAttributes(stack, "Token1", {
  parameterName: "/gitlab-runner/token1",
});

const token2 = StringParameter.fromStringParameterAttributes(stack, "Token2", {
  parameterName: "/gitlab-runner/token2",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      token: token1,
      configuration: {
        name: "privileged-runner",
      },
      role: privilegedRole,
    },
    {
      token: token2,
      configuration: {
        name: "restricted-runner",
        docker: {
          privileged: false, // Run unprivileged
        },
      },
      role: restrictedRole,
    },
  ],
});

See example, GitlabRunnerAutoscalingProps

Spot instances

By default, EC2 Spot Instances are requested.

const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      token: token,
      configuration: {
        machine: {
          machineOptions: {
            requestSpotInstance: false,
            spotPrice: 0.5,
          },
        },
      },
    },
  ],
});

See example, EC2 spot price, MachineConfiguration, MachineOptions, Advanced configuration - runners.machine.autoscaling

Cross-Compile with Multiarch

To build binaries of different architectures can also use Multiarch

const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      token: token,
      configuration: {
        docker: {
          privileged: true,
        },
      },
    },
  ],
});

Configure your .gitlab-ci.yml file

build:
  image: multiarch/debian-debootstrap:armhf-buster
  services:
    - docker:stable-dind
    - name: multiarch/qemu-user-static:register
      command:
        - "--reset"
  script:
    - make build

See multiarch/qemu-user-static

Running on AWS Graviton

To run your jobs on AWS Graviton you have to provide an AMI for arm64 architecture.

const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      token: token,
      configuration: {
        instanceType: InstanceType.of(InstanceClass.M6G, InstanceSize.LARGE),
        machineImage: MachineImage.genericLinux({
          [this.region]: new LookupMachineImage({
            name: "ubuntu/images/hvm-ssd/ubuntu-focal-20.04-*-server-*",
            owners: ["099720109477"],
            filters: {
              architecture: [InstanceArchitecture.ARM_64],
              "image-type": ["machine"],
              state: ["available"],
              "root-device-type": ["ebs"],
              "virtualization-type": ["hvm"],
            },
          }).getImage(this).imageId,
        }),
      },
    },
  ],
});

See Ubuntu Amazon EC2 AMI Locator

Custom runner's role

To deploy from within your GitLab Runner Instances, you may pass a Role with the IAM Policies attached.

const role = new Role(this, "RunnersRole", {
  assumedBy: new ServicePrincipal("ec2.amazonaws.com", {}),
  inlinePolicies: {},
});
const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      role: role,
      token: token,
      configuration: {
        // optionally configure your runner
      },
    },
  ],
});

See example, GitlabRunnerAutoscalingProps

Vpc

If no existing Vpc is passed, a cheap VPC with a NatInstance (t3.nano) and a single AZ will be created.

const natInstanceProvider = aws_ec2.NatProvider.instance({
  instanceType: aws_ec2.InstanceType.of(InstanceClass.T3, InstanceSize.NANO), // using a cheaper gateway (not scalable)
});
const vpc = new Vpc(this, "Vpc", {
  // Your custom vpc, i.e.:
  natGatewayProvider: natInstanceProvider,
  maxAzs: 1,
});

const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      token: token,
      configuration: {
        // optionally configure your runner
      },
    },
  ],
  network: { vpc: vpc },
});

See example, GitlabRunnerAutoscalingProps

Zero config

Deploys the Autoscaling GitLab Runner on AWS EC2 with the default settings mentioned above.

Happy with the presets?

const token = StringParameter.fromStringParameterAttributes(stack, "Token", {
  parameterName: "/gitlab-runner/token",
});

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      token: token,
      configuration: {
        // optionally configure your runner
      },
    },
  ],
});

See example, GitlabRunnerAutoscalingProps

ECR Credentials Helper

By default, the GitLab amzonec2 driver will be configured to install the amazon-ecr-credential-helper on the runner's instances.

To configure, override the default job runners environment:

new GitlabRunnerAutoscaling(this, "Runner", {
  runners: [
    {
      // ...
      environment: [
        "DOCKER_DRIVER=overlay2",
        "DOCKER_TLS_CERTDIR=/certs",
        'DOCKER_AUTH_CONFIG={"credHelpers": { "public.ecr.aws": "ecr-login", "<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login" } }',
      ],
    },
  ],
});

Projen

This project uses projen to maintain project configuration through code. Thus, the synthesized files with projen should never be manually edited (in fact, projen enforces that).

To modify the project setup, you should interact with rich strongly-typed class AwsCdkTypeScriptApp and execute npx projen to update project configuration files.

In simple words, developers can only modify .projenrc.js file for configuration/maintenance and files under /src directory for development.

API Reference

Constructs

Cache

A GitLab Runner cache consisting of an Amazon S3 bucket.

The bucket is encrypted with a KMS managed master key, it has public access blocked and will be cleared and deleted on CFN stack deletion.

Initializers

import { Cache } from '@pepperize/cdk-autoscaling-gitlab-runner'

new Cache(scope: Construct, id: string, props?: CacheProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`CacheProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Optional

Type: CacheProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { Cache } from '@pepperize/cdk-autoscaling-gitlab-runner'

Cache.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`bucket`	`aws-cdk-lib.aws_s3.IBucket`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`bucket`^Required

public readonly bucket: IBucket;

Type: aws-cdk-lib.aws_s3.IBucket

GitlabRunnerAutoscaling

The Gitlab Runner autoscaling on EC2 by Docker Machine.

Example

<caption>Provisioning a basic Runner</caption>
const app = new cdk.App();
const stack = new cdk.Stack(app, "RunnerStack", {
env: {
account: "000000000000",
region: "us-east-1",
}
});

const token = new StringParameter(stack, "imported-token", {
parameterName: "/gitlab-runner/token1",
stringValue: gitlabToken,
type: ParameterType.SECURE_STRING,
tier: ParameterTier.STANDARD,
});

new GitlabRunnerAutoscaling(stack, "GitlabRunner", {
runners: [{
token: "xxxxxxxxxxxxxxxxxxxx"
}],
});

Initializers

import { GitlabRunnerAutoscaling } from '@pepperize/cdk-autoscaling-gitlab-runner'

new GitlabRunnerAutoscaling(scope: Stack, id: string, props: GitlabRunnerAutoscalingProps)

Name	Type	Description
`scope`	`aws-cdk-lib.Stack`	No description.
`id`	`string`	No description.
`props`	`GitlabRunnerAutoscalingProps`	No description.

`scope`^Required

Type: aws-cdk-lib.Stack

`id`^Required

Type: string

`props`^Required

Type: GitlabRunnerAutoscalingProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { GitlabRunnerAutoscaling } from '@pepperize/cdk-autoscaling-gitlab-runner'

GitlabRunnerAutoscaling.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`cacheBucket`	`aws-cdk-lib.aws_s3.IBucket`	No description.
`manager`	`GitlabRunnerAutoscalingManager`	No description.
`network`	`Network`	No description.
`runners`	`GitlabRunnerAutoscalingJobRunner[]`	No description.
`checkInterval`	`number`	No description.
`concurrent`	`number`	No description.
`logFormat`	`string`	No description.
`logLevel`	`string`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`cacheBucket`^Required

public readonly cacheBucket: IBucket;

Type: aws-cdk-lib.aws_s3.IBucket

`manager`^Required

public readonly manager: GitlabRunnerAutoscalingManager;

Type: GitlabRunnerAutoscalingManager

`network`^Required

public readonly network: Network;

Type: Network

`runners`^Required

public readonly runners: GitlabRunnerAutoscalingJobRunner[];

Type: GitlabRunnerAutoscalingJobRunner[]

`checkInterval`^Optional

public readonly checkInterval: number;

Type: number

`concurrent`^Optional

public readonly concurrent: number;

Type: number

`logFormat`^Optional

public readonly logFormat: string;

Type: string

`logLevel`^Optional

public readonly logLevel: string;

Type: string

GitlabRunnerAutoscalingJobRunner

Initializers

import { GitlabRunnerAutoscalingJobRunner } from '@pepperize/cdk-autoscaling-gitlab-runner'

new GitlabRunnerAutoscalingJobRunner(scope: Construct, id: string, props: GitlabRunnerAutoscalingJobRunnerProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`GitlabRunnerAutoscalingJobRunnerProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: GitlabRunnerAutoscalingJobRunnerProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { GitlabRunnerAutoscalingJobRunner } from '@pepperize/cdk-autoscaling-gitlab-runner'

GitlabRunnerAutoscalingJobRunner.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`configuration`	`RunnerConfiguration`	No description.
`instanceProfile`	`aws-cdk-lib.aws_iam.CfnInstanceProfile`	No description.
`instanceType`	`aws-cdk-lib.aws_ec2.InstanceType`	No description.
`machineImage`	`aws-cdk-lib.aws_ec2.IMachineImage`	No description.
`role`	`aws-cdk-lib.aws_iam.IRole`	No description.
`keyPair`	`aws-cdk-lib.aws_secretsmanager.ISecret`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`configuration`^Required

public readonly configuration: RunnerConfiguration;

Type: RunnerConfiguration

`instanceProfile`^Required

public readonly instanceProfile: CfnInstanceProfile;

Type: aws-cdk-lib.aws_iam.CfnInstanceProfile

`instanceType`^Required

public readonly instanceType: InstanceType;

Type: aws-cdk-lib.aws_ec2.InstanceType

`machineImage`^Required

public readonly machineImage: IMachineImage;

Type: aws-cdk-lib.aws_ec2.IMachineImage

`role`^Required

public readonly role: IRole;

Type: aws-cdk-lib.aws_iam.IRole

`keyPair`^Optional

public readonly keyPair: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

GitlabRunnerAutoscalingManager

Settings for the manager (coordinator).

Manager coordinates the placement of runner (job executor) instances

Initializers

import { GitlabRunnerAutoscalingManager } from '@pepperize/cdk-autoscaling-gitlab-runner'

new GitlabRunnerAutoscalingManager(scope: Construct, id: string, props: GitlabRunnerAutoscalingManagerProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`GitlabRunnerAutoscalingManagerProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: GitlabRunnerAutoscalingManagerProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { GitlabRunnerAutoscalingManager } from '@pepperize/cdk-autoscaling-gitlab-runner'

GitlabRunnerAutoscalingManager.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`cacheBucket`	`aws-cdk-lib.aws_s3.IBucket`	No description.
`globalConfiguration`	`GlobalConfiguration`	No description.
`initConfig`	`aws-cdk-lib.aws_ec2.CloudFormationInit`	No description.
`instanceType`	`aws-cdk-lib.aws_ec2.InstanceType`	No description.
`machineImage`	`aws-cdk-lib.aws_ec2.IMachineImage`	No description.
`network`	`Network`	No description.
`role`	`aws-cdk-lib.aws_iam.IRole`	No description.
`runners`	`GitlabRunnerAutoscalingJobRunner[]`	No description.
`runnersSecurityGroupName`	`string`	No description.
`userData`	`aws-cdk-lib.aws_ec2.UserData`	No description.
`keyPairName`	`string`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`cacheBucket`^Required

public readonly cacheBucket: IBucket;

Type: aws-cdk-lib.aws_s3.IBucket

`globalConfiguration`^Required

public readonly globalConfiguration: GlobalConfiguration;

Type: GlobalConfiguration

`initConfig`^Required

public readonly initConfig: CloudFormationInit;

Type: aws-cdk-lib.aws_ec2.CloudFormationInit

`instanceType`^Required

public readonly instanceType: InstanceType;

Type: aws-cdk-lib.aws_ec2.InstanceType

`machineImage`^Required

public readonly machineImage: IMachineImage;

Type: aws-cdk-lib.aws_ec2.IMachineImage

`network`^Required

public readonly network: Network;

Type: Network

`role`^Required

public readonly role: IRole;

Type: aws-cdk-lib.aws_iam.IRole

`runners`^Required

public readonly runners: GitlabRunnerAutoscalingJobRunner[];

Type: GitlabRunnerAutoscalingJobRunner[]

`runnersSecurityGroupName`^Required

public readonly runnersSecurityGroupName: string;

Type: string

`userData`^Required

public readonly userData: UserData;

Type: aws-cdk-lib.aws_ec2.UserData

`keyPairName`^Optional

public readonly keyPairName: string;

Type: string

Network

Network settings for the manager and runners.

All EC2 instances should belong to the same subnet, availability zone and vpc.

Initializers

import { Network } from '@pepperize/cdk-autoscaling-gitlab-runner'

new Network(scope: Construct, id: string, props?: NetworkProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`NetworkProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Optional

Type: NetworkProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`hasPrivateSubnets`	No description.

`toString`

public toString(): string

Returns a string representation of this construct.

`hasPrivateSubnets`

public hasPrivateSubnets(): boolean

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { Network } from '@pepperize/cdk-autoscaling-gitlab-runner'

Network.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`availabilityZone`	`string`	No description.
`subnet`	`aws-cdk-lib.aws_ec2.ISubnet`	No description.
`vpc`	`aws-cdk-lib.aws_ec2.IVpc`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`availabilityZone`^Required

public readonly availabilityZone: string;

Type: string

`subnet`^Required

public readonly subnet: ISubnet;

Type: aws-cdk-lib.aws_ec2.ISubnet

`vpc`^Required

public readonly vpc: IVpc;

Type: aws-cdk-lib.aws_ec2.IVpc

Structs

AutoscalingConfiguration

https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersmachineautoscaling-sections

Initializer

import { AutoscalingConfiguration } from '@pepperize/cdk-autoscaling-gitlab-runner'

const autoscalingConfiguration: AutoscalingConfiguration = { ... }

Properties

Name	Type	Description
`idleCount`	`number`	No description.
`idleTime`	`number`	No description.
`periods`	`string[]`	The Periods setting contains an array of string patterns of time periods represented in a cron-style format. https://github.com/gorhill/cronexpr#implementation.
`timezone`	`string`	No description.

`idleCount`^Optional

public readonly idleCount: number;

Type: number

`idleTime`^Optional

public readonly idleTime: number;

Type: number

`periods`^Optional

public readonly periods: string[];

Type: string[]

The Periods setting contains an array of string patterns of time periods represented in a cron-style format. https://github.com/gorhill/cronexpr#implementation.

[second] [minute] [hour] [day of month] [month] [day of week] [year]

Example

// "* * 7-22 * * mon-fri *"

`timezone`^Optional

public readonly timezone: string;

Type: string

CacheConfiguration

Initializer

import { CacheConfiguration } from '@pepperize/cdk-autoscaling-gitlab-runner'

const cacheConfiguration: CacheConfiguration = { ... }

Properties

Name	Type	Description
`s3`	`CacheS3Configuration`	No description.
`shared`	`boolean`	No description.
`type`	`string`	No description.

`s3`^Optional

public readonly s3: CacheS3Configuration;

Type: CacheS3Configuration

`shared`^Optional

public readonly shared: boolean;

Type: boolean

`type`^Optional

public readonly type: string;

Type: string

CacheProps

Initializer

import { CacheProps } from '@pepperize/cdk-autoscaling-gitlab-runner'

const cacheProps: CacheProps = { ... }

Properties

Name	Type	Description
`bucketName`	`string`	The infix of the physical cache bucket name.
`expiration`	`aws-cdk-lib.Duration`	The number of days after which the created cache objects are deleted from S3.

`bucketName`^Optional

public readonly bucketName: string;

Type: string
Default: "runner-cache"

The infix of the physical cache bucket name.

`expiration`^Optional

public readonly expiration: Duration;

Type: aws-cdk-lib.Duration
Default: 30 days

The number of days after which the created cache objects are deleted from S3.

CacheS3Configuration

Define cache configuration for S3 storage.

https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section

Initializer

import { CacheS3Configuration } from '@pepperize/cdk-autoscaling-gitlab-runner'

const cacheS3Configuration: CacheS3Configuration = { ... }

Properties

Name	Type	Description
`accessKey`	`string`	No description.
`authenticationType`	`string`	In GitLab 15.0 and later, explicitly set AuthenticationType to iam or access-key.
`bucketLocation`	`string`	The name of the S3 region.
`bucketName`	`string`	The name of the storage bucket where cache is stored.
`insecure`	`boolean`	Set to true if the S3 service is available by HTTP.
`secretKey`	`string`	No description.
`serverAddress`	`string`	The AWS S3 host.

`accessKey`^Optional

public readonly accessKey: string;

Type: string

`authenticationType`^Optional

public readonly authenticationType: string;

Type: string
Default: "iam"

In GitLab 15.0 and later, explicitly set AuthenticationType to iam or access-key.

https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28171

`bucketLocation`^Optional

public readonly bucketLocation: string;

Type: string

The name of the S3 region.

`bucketName`^Optional

public readonly bucketName: string;

Type: string
Default: "runners-cache"

The name of the storage bucket where cache is stored.

`insecure`^Optional

public readonly insecure: boolean;

Type: boolean
Default: false

Set to true if the S3 service is available by HTTP.

`secretKey`^Optional

public readonly secretKey: string;

Type: string

`serverAddress`^Optional

public readonly serverAddress: string;

Type: string
Default: "s3.amazonaws.com"

The AWS S3 host.

ConfigurationMapperProps

Initializer

import { ConfigurationMapperProps } from '@pepperize/cdk-autoscaling-gitlab-runner'

const configurationMapperProps: ConfigurationMapperProps = { ... }

Properties

Name	Type	Description
`globalConfiguration`	`GlobalConfiguration`	No description.
`runnersConfiguration`	`RunnerConfiguration[]`	No description.

`globalConfiguration`^Required

public readonly globalConfiguration: GlobalConfiguration;

Type: GlobalConfiguration

`runnersConfiguration`^Required

public readonly runnersConfiguration: RunnerConfiguration[];

Type: RunnerConfiguration[]

DockerConfiguration

Configure docker on the runners.

https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersdocker-section

Initializer

import { DockerConfiguration } from '@pepperize/cdk-autoscaling-gitlab-runner'

const dockerConfiguration: DockerConfiguration = { ... }

Properties

Name	Type	Description
`allowedImages`	`string[]`	Wildcard list of images that can be specified in the .gitlab-ci.yml file. If not present, all images are allowed (equivalent to ["/:*"]). See Restrict Docker images and services.
`allowedServices`	`string[]`	Wildcard list of services that can be specified in the .gitlab-ci.yml file. If not present, all images are allowed (equivalent to [/:*]). See Restrict Docker images and services.
`cacheDir`	`string`	Directory where Docker caches should be stored.
`capAdd`	`string[]`	Add additional Linux capabilities to the container.
`capDrop`	`string[]`	Drop additional Linux capabilities from the container.
`cpus`	`string`	Number of CPUs (available in Docker 1.13 or later. A string.
`cpusetCpus`	`string`	The control group’s CpusetCpus.
`cpuShares`	`number`	Number of CPU shares used to set relative CPU usage.
`devices`	`string[]`	Share additional host devices with the container.
`disableCache`	`boolean`	The Docker executor has two levels of caching: a global one (like any other executor) and a local cache based on Docker volumes.
`disableEntrypointOverwrite`	`boolean`	Disable the image entrypoint overwriting.
`dns`	`string[]`	A list of DNS servers for the container to use.
`dnsSearch`	`string[]`	A list of DNS search domains.
`extraHosts`	`string[]`	Hosts that should be defined in container environment.
`gpus`	`string[]`	GPU devices for Docker container.
`helperImage`	`string`	(Advanced) The default helper image used to clone repositories and upload artifacts.
`helperImageFlavor`	`string`	Sets the helper image flavor (alpine, alpine3.12, alpine3.13, alpine3.14 or ubuntu). Defaults to alpine. The alpine flavor uses the same version as alpine3.12.
`host`	`string`	Custom Docker endpoint.
`hostname`	`string`	Custom hostname for the Docker container.
`image`	`string`	The image to run jobs with.
`links`	`string[]`	Containers that should be linked with container that runs the job.
`memory`	`string`	The memory limit.
`memoryReservation`	`string`	The memory soft limit.
`memorySwap`	`string`	The total memory limit.
`networkMode`	`string`	Add container to a custom network.
`oomKillDisable`	`boolean`	If an out-of-memory (OOM) error occurs, do not kill processes in a container.
`oomScoreAdjust`	`string`	OOM score adjustment.
`privileged`	`boolean`	Make the container run in privileged mode.
`pullPolicy`	`string`	The image pull policy: never, if-not-present or always (default).
`runtime`	`string`	The runtime for the Docker container.
`securityOpt`	`string`	Security options (–security-opt in docker run).
`shmSize`	`number`	Shared memory size for images (in bytes).
`sysctls`	`string`	The sysctl options.
`tlsCertPath`	`string`	A directory where ca.pem, cert.pem or key.pem are stored and used to make a secure TLS connection to Docker. Useful in boot2docker.
`tlsVerify`	`boolean`	Enable or disable TLS verification of connections to Docker daemon.
`usernsMode`	`string`	The user namespace mode for the container and Docker services when user namespace remapping option is enabled.
`volumeDriver`	`string`	The volume driver to use for the container.
`volumes`	`string[]`	Additional volumes that should be mounted.
`volumesFrom`	`string[]`	A list of volumes to inherit from another container in the form [:<ro\|rw>].
`waitForServicesTimeout`	`number`	How long to wait for Docker services.

`allowedImages`^Optional

public readonly allowedImages: string[];

Type: string[]

Wildcard list of images that can be specified in the .gitlab-ci.yml file. If not present, all images are allowed (equivalent to ["/:*"]). See Restrict Docker images and services.

`allowedServices`^Optional

public readonly allowedServices: string[];

Type: string[]

Wildcard list of services that can be specified in the .gitlab-ci.yml file. If not present, all images are allowed (equivalent to [/:*]). See Restrict Docker images and services.

`cacheDir`^Optional

public readonly cacheDir: string;

Type: string

Directory where Docker caches should be stored.

This path can be absolute or relative to current working directory. See disable_cache for more information.

`capAdd`^Optional

public readonly capAdd: string[];

Type: string[]
Default: ["CAP_SYS_ADMIN"]

Add additional Linux capabilities to the container.

`capDrop`^Optional

public readonly capDrop: string[];

Type: string[]

Drop additional Linux capabilities from the container.

`cpus`^Optional

public readonly cpus: string;

Type: string

Number of CPUs (available in Docker 1.13 or later. A string.

`cpusetCpus`^Optional

public readonly cpusetCpus: string;

Type: string

The control group’s CpusetCpus.

A string.

`cpuShares`^Optional

public readonly cpuShares: number;

Type: number

Number of CPU shares used to set relative CPU usage.

Default is 1024.

`devices`^Optional

public readonly devices: string[];

Type: string[]

Share additional host devices with the container.

`disableCache`^Optional

public readonly disableCache: boolean;

Type: boolean
Default: false

The Docker executor has two levels of caching: a global one (like any other executor) and a local cache based on Docker volumes.

This configuration flag acts only on the local one which disables the use of automatically created (not mapped to a host directory) cache volumes. In other words, it only prevents creating a container that holds temporary files of builds, it does not disable the cache if the runner is configured in distributed cache mode.

`disableEntrypointOverwrite`^Optional

public readonly disableEntrypointOverwrite: boolean;

Type: boolean

Disable the image entrypoint overwriting.

`dns`^Optional

public readonly dns: string[];

Type: string[]

A list of DNS servers for the container to use.

`dnsSearch`^Optional

public readonly dnsSearch: string[];

Type: string[]

A list of DNS search domains.

`extraHosts`^Optional

public readonly extraHosts: string[];

Type: string[]

Hosts that should be defined in container environment.

`gpus`^Optional

public readonly gpus: string[];

Type: string[]

GPU devices for Docker container.

Uses the same format as the docker cli. View details in the Docker documentation.

`helperImage`^Optional

public readonly helperImage: string;

Type: string

(Advanced) The default helper image used to clone repositories and upload artifacts.

`helperImageFlavor`^Optional

public readonly helperImageFlavor: string;

Type: string

Sets the helper image flavor (alpine, alpine3.12, alpine3.13, alpine3.14 or ubuntu). Defaults to alpine. The alpine flavor uses the same version as alpine3.12.

`host`^Optional

public readonly host: string;

Type: string

Custom Docker endpoint.

Default is DOCKER_HOST environment or unix:///var/run/docker.sock.

`hostname`^Optional

public readonly hostname: string;

Type: string

Custom hostname for the Docker container.

`image`^Optional

public readonly image: string;

Type: string

The image to run jobs with.

`links`^Optional

public readonly links: string[];

Type: string[]

Containers that should be linked with container that runs the job.

`memory`^Optional

public readonly memory: string;

Type: string

The memory limit.

A string.

`memoryReservation`^Optional

public readonly memoryReservation: string;

Type: string

The memory soft limit.

A string.

`memorySwap`^Optional

public readonly memorySwap: string;

Type: string

The total memory limit.

A string.

`networkMode`^Optional

public readonly networkMode: string;

Type: string

Add container to a custom network.

`oomKillDisable`^Optional

public readonly oomKillDisable: boolean;

Type: boolean

If an out-of-memory (OOM) error occurs, do not kill processes in a container.

`oomScoreAdjust`^Optional

public readonly oomScoreAdjust: string;

Type: string

OOM score adjustment.

Positive means kill earlier.

`privileged`^Optional

public readonly privileged: boolean;

Type: boolean
Default: true

Make the container run in privileged mode.

Insecure.

`pullPolicy`^Optional

public readonly pullPolicy: string;

Type: string

The image pull policy: never, if-not-present or always (default).

View details in the pull policies documentation. You can also add multiple pull policies.

`runtime`^Optional

public readonly runtime: string;

Type: string

The runtime for the Docker container.

`securityOpt`^Optional

public readonly securityOpt: string;

Type: string

Security options (–security-opt in docker run).

Takes a list of : separated key/values.

`shmSize`^Optional

public readonly shmSize: number;

Type: number
Default: 0

Shared memory size for images (in bytes).

`sysctls`^Optional

public readonly sysctls: string;

Type: string

The sysctl options.

`tlsCertPath`^Optional

public readonly tlsCertPath: string;

Type: string

A directory where ca.pem, cert.pem or key.pem are stored and used to make a secure TLS connection to Docker. Useful in boot2docker.

`tlsVerify`^Optional

public readonly tlsVerify: boolean;

Type: boolean
Default: false

Enable or disable TLS verification of connections to Docker daemon.

Disabled by default.

`usernsMode`^Optional

public readonly usernsMode: string;

Type: string

The user namespace mode for the container and Docker services when user namespace remapping option is enabled.

Available in Docker 1.10 or later.

`volumeDriver`^Optional

public readonly volumeDriver: string;

Type: string

The volume driver to use for the container.

`volumes`^Optional

public readonly volumes: string[];

Type: string[]

Additional volumes that should be mounted.

Same syntax as the Docker -v flag.

`volumesFrom`^Optional

public readonly volumesFrom: string[];

Type: string[]

A list of volumes to inherit from another container in the form [:<ro|rw>].

Access level defaults to read-write, but can be manually set to ro (read-only) or rw (read-write).

`waitForServicesTimeout`^Optional

public readonly waitForServicesTimeout: number;

Type: number
Default: 300

How long to wait for Docker services.

Set to 0 to disable. Default is 30.

GitlabRunnerAutoscalingCacheProps

The distributed GitLab runner S3 cache.

Either pass an existing bucket or override default options.

https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section

Initializer

import { GitlabRunnerAutoscalingCacheProps } from '@pepperize/cdk-autoscaling-gitlab-runner'

const gitlabRunnerAutoscalingCacheProps: GitlabRunnerAutoscalingCacheProps = { ... }

Properties

Name	Type	Description
`bucket`	`aws-cdk-lib.aws_s3.IBucket`	An existing S3 bucket used as runner's cache.
`options`	`CacheProps`	If no existing S3 bucket is provided, a S3 bucket will be created.

`bucket`^Optional

public readonly bucket: IBucket;

Type: aws-cdk-lib.aws_s3.IBucket

An existing S3 bucket used as runner's cache.

`options`^Optional

public readonly options: CacheProps;

Type: CacheProps

If no existing S3 bucket is provided, a S3 bucket will be created.

GitlabRunnerAutoscalingJobRunnerProps

The runner EC2 instances configuration.

If not set, the defaults will be used.

Initializer

import { GitlabRunnerAutoscalingJobRunnerProps } from '@pepperize/cdk-autoscaling-gitlab-runner'

const gitlabRunnerAutoscalingJobRunnerProps: GitlabRunnerAutoscalingJobRunnerProps = { ... }

Properties

Name	Type	Description
`configuration`	`RunnerConfiguration`	The runner EC2 instances configuration.
`token`	`aws-cdk-lib.aws_ssm.IStringParameter`	The runner’s authentication token, which is obtained during runner registration.
`instanceType`	`aws-cdk-lib.aws_ec2.InstanceType`	Instance type for runner EC2 instances.
`keyPair`	`aws-cdk-lib.aws_secretsmanager.ISecret`	Optionally pass a custom EC2 KeyPair, that will be used by the manager to connect to the job runner instances.
`machineImage`	`aws-cdk-lib.aws_ec2.IMachineImage`	An Amazon Machine Image ID for the Runners EC2 instances.
`role`	`aws-cdk-lib.aws_iam.IRole`	Optionally pass an IAM role, that get's assigned to the EC2 runner instances via Instance Profile.

`configuration`^Required

public readonly configuration: RunnerConfiguration;

Type: RunnerConfiguration

The runner EC2 instances configuration.

If not set, the defaults will be used.

RunnerConfiguration

`token`^Required

public readonly token: IStringParameter;

Type: aws-cdk-lib.aws_ssm.IStringParameter

The runner’s authentication token, which is obtained during runner registration.

Not the same as the registration token.

https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner

`instanceType`^Optional

public readonly instanceType: InstanceType;

Type: aws-cdk-lib.aws_ec2.InstanceType
Default: InstanceType.of(InstanceClass.T3, InstanceSize.MICRO)

Instance type for runner EC2 instances.

It's a combination of a class and size.

`keyPair`^Optional

public readonly keyPair: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

Optionally pass a custom EC2 KeyPair, that will be used by the manager to connect to the job runner instances.

Example: aws secretsmanager create-secret --name AnyKeyPairSecret --secret-string "{\"theKeyPairName\":\"\",\"theKeyPairName.pub\":\"\"}"
Additionally configure an unique key pair configuration.machine.machineOptions.keypairName

`machineImage`^Optional

public readonly machineImage: IMachineImage;

Type: aws-cdk-lib.aws_ec2.IMachineImage

An Amazon Machine Image ID for the Runners EC2 instances.

If empty the latest Ubuntu 20.04 focal will be looked up.

Any operating system supported by Docker Machine's provisioner.

https://gitlab.com/gitlab-org/ci-cd/docker-machine/-/tree/main/libmachine/provision

`role`^Optional

public readonly role: IRole;

Type: aws-cdk-lib.aws_iam.IRole

Optionally pass an IAM role, that get's assigned to the EC2 runner instances via Instance Profile.

GitlabRunnerAutoscalingManagerBaseProps

Initializer

import { GitlabRunnerAutoscalingManagerBaseProps } from '@pepperize/cdk-autoscaling-gitlab-runner'

const gitlabRunnerAutoscalingManagerBaseProps: GitlabRunnerAutoscalingManagerBaseProps = { ... }

Properties

Name	Type	Description
`dockerMachineVersion`	`DockerMachineVersion`	No description.
`instanceType`	`aws-cdk-lib.aws_ec2.InstanceType`	Instance type for manager EC2 instance.
`keyPairName`	`string`	A set of security credentials that you use to prove your identity when connecting to an Amazon EC2 instance.
`machineImage`	`aws-cdk-lib.aws_ec2.IMachineImage`	An Amazon Machine Image ID for the Manager EC2 instance.

`dockerMachineVersion`^Optional

public readonly dockerMachineVersion: DockerMachineVersion;

Type: DockerMachineVersion

`instanceType`^Optional

public readonly instanceType: InstanceType;

Type: aws-cdk-lib.aws_ec2.InstanceType
Default: InstanceType.of(InstanceClass.T3, InstanceSize.NANO)

Instance type for manager EC2 instance.

It's a combination of a class and size.

`keyPairName`^Optional

public readonly keyPairName: string;

Type: string

A set of security credentials that you use to prove your identity when connecting to an Amazon EC2 instance.

You won't be able to ssh into an instance without the Key Pair.

`machineImage`^Optional

public readonly machineImage: IMachineImage;

Type: aws-cdk-lib.aws_ec2.IMachineImage

An Amazon Machine Image ID for the Manager EC2 instance.

If empty the latest Amazon 2 Image will be looked up.

Should be RHEL flavor like Amazon Linux 2 with yum available for instance initialization.

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-init.html

GitlabRunnerAutoscalingManagerProps

Initializer

import { GitlabRunnerAutoscalingManagerProps } from '@pepperize/cdk-autoscaling-gitlab-runner'

const gitlabRunnerAutoscalingManagerProps: GitlabRunnerAutoscalingManagerProps = { ... }

Properties

Name	Type	Description
`dockerMachineVersion`	`DockerMachineVersion`	No description.
`instanceType`	`aws-cdk-lib.aws_ec2.InstanceType`	Instance type for manager EC2 instance.
`keyPairName`	`string`	A set of security credentials that you use to prove your identity when connecting to an Amazon EC2 instance.
`machineImage`	`aws-cdk-lib.aws_ec2.IMachineImage`	An Amazon Machine Image ID for the Manager EC2 instance.
`cacheBucket`	`aws-cdk-lib.aws_s3.IBucket`	No description.
`network`	`Network`	No description.
`runners`	`GitlabRunnerAutoscalingJobRunner[]`	No description.
`runnersSecurityGroup`	`@pepperize/cdk-security-group.SecurityGroup`	No description.
`globalConfiguration`	`GlobalConfiguration`	No description.
`role`	`aws-cdk-lib.aws_iam.IRole`	No description.

`dockerMachineVersion`^Optional

public readonly dockerMachineVersion: DockerMachineVersion;

Type: DockerMachineVersion

`instanceType`^Optional

public readonly instanceType: InstanceType;

Type: aws-cdk-lib.aws_ec2.InstanceType
Default: InstanceType.of(InstanceClass.T3, InstanceSize.NANO)

Instance type for manager EC2 instance.

It's a combination of a class and size.

`keyPairName`^Optional

public readonly keyPairName: string;

Type: string

A set of security credentials that you use to prove your identity when connecting to an Amazon EC2 instance.

You won't be able to ssh into an instance without the Key Pair.

`machineImage`^Optional

public readonly machineImage: IMachineImage;

Type: aws-cdk-lib.aws_ec2.IMachineImage

An Amazon Machine Image ID for the Manager EC2 instance.

If empty the latest Amazon 2 Image will be looked up.

Should be RHEL flavor like Amazon Linux 2 with yum available for instance initialization.

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-init.html

`cacheBucket`^Required

public readonly cacheBucket: IBucket;

Type: aws-cdk-lib.aws_s3.IBucket

`network`^Required

public readonly network: Network;

Type: Network

`runners`^Required

public readonly runners: GitlabRunnerAutoscalingJobRunner[];

Type: GitlabRunnerAutoscalingJobRunner[]

`runnersSecurityGroup`^Required

public readonly runnersSecurityGroup: SecurityGroup;

Type: @pepperize/cdk-security-group.SecurityGroup

`globalConfiguration`^Optional

public readonly globalConfiguration: GlobalConfiguration;

Type: GlobalConfiguration

`role`^Optional

public readonly role: IRole;

Type: aws-cdk-lib.aws_iam.IRole

GitlabRunnerAutoscalingProps

Properties of the Gitlab Runner.

You have to provide at least the GitLab's Runner's authentication token.

Initializer

import { GitlabRunnerAutoscalingProps } from '@pepperize/cdk-autoscaling-gitlab-runner'

const gitlabRunnerAutoscalingProps: GitlabRunnerAutoscalingProps = { ... }

Properties

Name	Type	Description
`checkInterval`	`number`	The check_interval option defines how often the runner should check GitLab for new jobs\| in seconds.
`concurrent`	`number`	The limit of the jobs that can be run concurrently across all runners (concurrent).
`logFormat`	`string`	The log format.
`logLevel`	`string`	The log_level.
`runners`	`GitlabRunnerAutoscalingJobRunnerProps[]`	The runner EC2 instances settings.
`cache`	`GitlabRunnerAutoscalingCacheProps`	No description.
`manager`	`GitlabRunnerAutoscalingManagerBaseProps`	The manager EC2 instance configuration.
`network`	`NetworkProps`	The network configuration for the Runner.

`checkInterval`^Optional

public readonly checkInterval: number;

Type: number
Default: 0

The check_interval option defines how often the runner should check GitLab for new jobs| in seconds.

`concurrent`^Optional

public readonly concurrent: number;

Type: number
Default: 10

The limit of the jobs that can be run concurrently across all runners (concurrent).

`logFormat`^Optional

public readonly logFormat: string;

Type: string
Default: "runner"

The log format.

`logLevel`^Optional

public readonly logLevel: string;

Type: string
Default: "info"

The log_level.

`runners`^Required

public readonly runners: GitlabRunnerAutoscalingJobRunnerProps[];

Type: GitlabRunnerAutoscalingJobRunnerProps[]

The runner EC2 instances settings.

At least one runner should be set up.

GitlabRunnerAutoscalingJobRunnerProps

`cache`^Optional

public readonly cache: GitlabRunnerAutoscalingCacheProps;

Type: GitlabRunnerAutoscalingCacheProps

`manager`^Optional

public readonly manager: GitlabRunnerAutoscalingManagerBaseProps;

Type: GitlabRunnerAutoscalingManagerBaseProps

The manager EC2 instance configuration.

If not set, the defaults will be used.

GitlabRunnerAutoscalingManagerBaseProps

`network`^Optional

public readonly network: NetworkProps;

Type: NetworkProps

The network configuration for the Runner.

If not set, the defaults will be used.

NetworkProps

GlobalConfiguration

You can change the behavior of GitLab Runner and of individual registered runners.

This imitates the structure of Gitlab Runner advanced configuration that originally is set with config.toml file.

https://docs.gitlab.com/runner/configuration/advanced-configuration.html

Initializer

import { GlobalConfiguration } from '@pepperize/cdk-autoscaling-gitlab-runner'

const globalConfiguration: GlobalConfiguration = { ... }

Properties

Name	Type	Description
`checkInterval`	`number`	The check_interval option defines how often the runner should check GitLab for new jobs\| in seconds.
`concurrent`	`number`	The limit of the jobs that can be run concurrently across all runners (concurrent).
`logFormat`	`string`	The log format.
`logLevel`	`string`	The log_level.

`checkInterval`^Optional

public readonly checkInterval: number;

Type: number
Default: 0

The check_interval option defines how often the runner should check GitLab for new jobs| in seconds.

`concurrent`^Optional

public readonly concurrent: number;

Type: number
Default: 10

The limit of the jobs that can be run concurrently across all runners (concurrent).

`logFormat`^Optional

public readonly logFormat: string;

Type: string
Default: "runner"

The log format.

`logLevel`^Optional

public readonly logLevel: string;

Type: string
Default: "info"

The log_level.

MachineConfiguration

Initializer

import { MachineConfiguration } from '@pepperize/cdk-autoscaling-gitlab-runner'

const machineConfiguration: MachineConfiguration = { ... }

Properties

Name	Type	Description
`autoscaling`	`AutoscalingConfiguration[]`	No description.
`idleCount`	`number`	Number of machines that need to be created and waiting in Idle state.
`idleTime`	`number`	Time (in seconds) for machine to be in Idle state before it is removed.
`machineDriver`	`string`	Docker Machine driver.
`machineName`	`string`	No description.
`machineOptions`	`MachineOptions`	Docker Machine options passed to the Docker Machine driver.
`maxBuilds`	`number`	Maximum job (build) count before machine is removed.

`autoscaling`^Optional

public readonly autoscaling: AutoscalingConfiguration[];

Type: AutoscalingConfiguration[]

`idleCount`^Optional

public readonly idleCount: number;

Type: number
Default: 0

Number of machines that need to be created and waiting in Idle state.

`idleTime`^Optional

public readonly idleTime: number;

Type: number
Default: 300

Time (in seconds) for machine to be in Idle state before it is removed.

`machineDriver`^Optional

public readonly machineDriver: string;

Type: string
Default: "amazonec2"

Docker Machine driver.

`machineName`^Optional

public readonly machineName: string;

Type: string
Default: "gitlab-runner"

`machineOptions`^Optional

public readonly machineOptions: MachineOptions;

Type: MachineOptions

Docker Machine options passed to the Docker Machine driver.

`maxBuilds`^Optional

public readonly maxBuilds: number;

Type: number
Default: 20

Maximum job (build) count before machine is removed.

MachineOptions

https://gitlab.com/gitlab-org/ci-cd/docker-machine/-/blob/main/drivers/amazonec2/amazonec2.go

Initializer

import { MachineOptions } from '@pepperize/cdk-autoscaling-gitlab-runner'

const machineOptions: MachineOptions = { ... }

Properties

Name	Type	Description
`engineInstallUrl`	`string`	Custom URL to use for engine installation.
`ami`	`string`	No description.
`blockDurationMinutes`	`number`	The amazonec2-block-duration-minutes parameter.
`iamInstanceProfile`	`string`	No description.
`instanceType`	`string`	No description.
`keypairName`	`string`	The amazonec2-keypair-name parameter.
`metadataToken`	`string`	Whether the metadata token is required or optional.
`metadataTokenResponseHopLimit`	`number`	The number of network hops that the metadata token can travel.
`privateAddressOnly`	`boolean`	The amazonec2-private-address-only parameter.
`region`	`string`	No description.
`requestSpotInstance`	`boolean`	The amazonec2-request-spot-instance parameter.
`rootSize`	`number`	The root disk size of the instance (in GB).
`securityGroup`	`string`	The SecurityGroup's GroupName, not the GroupId.
`spotPrice`	`number`	The amazonec2-spot-price parameter.
`sshKeypath`	`string`	The amazonec2-ssh-keypath parameter.
`subnetId`	`string`	No description.
`useEbsOptimizedInstance`	`boolean`	Create an EBS Optimized Instance, instance type must support it.
`usePrivateAddress`	`boolean`	Use the private IP address of Docker Machines, but still create a public IP address.
`userdata`	`string`	The path of the runner machine's userdata file on the manager instance used by the amazonec2 driver to create a new instance.
`volumeType`	`string`	The Amazon EBS volume type to be attached to the instance.
`vpcId`	`string`	No description.
`zone`	`string`	Extract the availabilityZone last character for the needs of gitlab configuration.

`engineInstallUrl`^Optional

public readonly engineInstallUrl: string;

Type: string
Default: https://releases.rancher.com/install-docker/20.10.21.sh

Custom URL to use for engine installation.

`ami`^Optional

public readonly ami: string;

Type: string

`blockDurationMinutes`^Optional

public readonly blockDurationMinutes: number;

Type: number

The amazonec2-block-duration-minutes parameter.

AWS spot instance duration in minutes (60, 120, 180, 240, 300, or 360).

https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/#cutting-down-costs-with-amazon-ec2-spot-instances

`iamInstanceProfile`^Optional

public readonly iamInstanceProfile: string;

Type: string

`instanceType`^Optional

public readonly instanceType: string;

Type: string

`keypairName`^Optional

public readonly keypairName: string;

Type: string

The amazonec2-keypair-name parameter.

A set of security credentials that you use to prove your identity when connecting to an Amazon EC2 instance.

using --amazonec2-keypair-name also requires --amazonec2-ssh-keypath

https://gitlab.com/gitlab-org/ci-cd/docker-machine/-/blob/main/drivers/amazonec2/amazonec2.go#L398

`metadataToken`^Optional

public readonly metadataToken: string;

Type: string
Default: required

Whether the metadata token is required or optional.

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html

`metadataTokenResponseHopLimit`^Optional

public readonly metadataTokenResponseHopLimit: number;

Type: number
Default: 2

The number of network hops that the metadata token can travel.

`privateAddressOnly`^Optional

public readonly privateAddressOnly: boolean;

Type: boolean

The amazonec2-private-address-only parameter.

If true, your EC2 instance won’t get assigned a public IP. This is ok if your VPC is configured correctly with an Internet Gateway (IGW), NatGateway (NGW) and routing is fine, but it’s something to consider if you’ve got a more complex configuration.

https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/#the-runnersmachine-section

`region`^Optional

public readonly region: string;

Type: string

`requestSpotInstance`^Optional

public readonly requestSpotInstance: boolean;

Type: boolean
Default: true

The amazonec2-request-spot-instance parameter.

Whether or not to request spot instances.

https://aws.amazon.com/ec2/spot/

`rootSize`^Optional

public readonly rootSize: number;

Type: number
Default: 16

The root disk size of the instance (in GB).

https://gitlab.com/gitlab-org/ci-cd/docker-machine/-/blob/main/docs/drivers/aws.md#options

`securityGroup`^Optional

public readonly securityGroup: string;

Type: string

The SecurityGroup's GroupName, not the GroupId.

`spotPrice`^Optional

public readonly spotPrice: number;

Type: number
Default: 0.03

The amazonec2-spot-price parameter.

The bidding price for spot instances.

https://aws.amazon.com/ec2/spot/pricing/

`sshKeypath`^Optional

public readonly sshKeypath: string;

Type: string
Default: /etc/gitlab-runner/ssh

The amazonec2-ssh-keypath parameter.

`subnetId`^Optional

public readonly subnetId: string;

Type: string

`useEbsOptimizedInstance`^Optional

public readonly useEbsOptimizedInstance: boolean;

Type: boolean

Create an EBS Optimized Instance, instance type must support it.

`usePrivateAddress`^Optional

public readonly usePrivateAddress: boolean;

Type: boolean

Use the private IP address of Docker Machines, but still create a public IP address.

Useful to keep the traffic internal and avoid extra costs.

https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/#the-runnersmachine-section

`userdata`^Optional

public readonly userdata: string;

Type: string
Default: /etc/gitlab-runner/user_data_runners

The path of the runner machine's userdata file on the manager instance used by the amazonec2 driver to create a new instance.

https://gitlab.com/gitlab-org/ci-cd/docker-machine/-/blob/main/drivers/amazonec2/amazonec2.go

`volumeType`^Optional

public readonly volumeType: string;

Type: string
Default: gp2

The Amazon EBS volume type to be attached to the instance.

`vpcId`^Optional

public readonly vpcId: string;

Type: string

`zone`^Optional

public readonly zone: string;

Type: string

Extract the availabilityZone last character for the needs of gitlab configuration.

https://docs.gitlab.com/runners/configuration/runners_autoscale_aws/#the-runnerssmachine-section

NetworkProps

Initializer

import { NetworkProps } from '@pepperize/cdk-autoscaling-gitlab-runner'

const networkProps: NetworkProps = { ... }

Properties

Name	Type	Description
`subnetSelection`	`aws-cdk-lib.aws_ec2.SubnetSelection`	The GitLab Runner's subnets.
`vpc`	`aws-cdk-lib.aws_ec2.IVpc`	If no existing VPC is provided, a default Vpc will be created.

`subnetSelection`^Optional

public readonly subnetSelection: SubnetSelection;

Type: aws-cdk-lib.aws_ec2.SubnetSelection

The GitLab Runner's subnets.

It should be either public or private. If more then subnet is selected, then the first found (private) subnet will be used.

https://docs.aws.amazon.com/cdk/api/latest/docs/

`vpc`^Optional

public readonly vpc: IVpc;

Type: aws-cdk-lib.aws_ec2.IVpc

If no existing VPC is provided, a default Vpc will be created.

RunnerConfiguration

Initializer

import { RunnerConfiguration } from '@pepperize/cdk-autoscaling-gitlab-runner'

const runnerConfiguration: RunnerConfiguration = { ... }

Properties

Name	Type	Description
`buildsDir`	`string`	Absolute path to a directory where builds are stored in the context of the selected executor.
`cache`	`CacheConfiguration`	The runner's AWS S3 cache configuration.
`cacheDir`	`string`	Absolute path to a directory where build caches are stored in context of selected executor.
`cloneUrl`	`string`	Overwrite the URL for the GitLab instance.
`debugTraceDisabled`	`boolean`	Disables the CI_DEBUG_TRACE feature.
`docker`	`DockerConfiguration`	The runner's docker configuration.
`environment`	`string[]`	Append or overwrite environment variables.
`executor`	`string`	Select how a project should be built.
`limit`	`number`	Limit how many jobs can be handled concurrently by this registered runner.
`machine`	`MachineConfiguration`	The runner's Docker Machine configuration.
`name`	`string`	The runner’s description.
`outputLimit`	`number`	Maximum build log size in kilobytes.
`postBuildScript`	`string`	Commands to be executed on the runner just after executing the build, but before executing after_script.
`preBuildScript`	`string`	Commands to be executed on the runner after cloning the Git repository, but before executing the build.
`preCloneScript`	`string`	Commands to be executed on the runner before cloning the Git repository.
`referees`	`string`	Extra job monitoring workers that pass their results as job artifacts to GitLab.
`requestConcurrency`	`number`	Limit number of concurrent requests for new jobs from GitLab.
`shell`	`string`	Name of shell to generate the script.
`tlsCaFile`	`string`	When using HTTPS, file that contains the certificates to verify the peer.
`tlsCertFile`	`string`	When using HTTPS, file that contains the certificate to authenticate with the peer.
`tlsKeyFile`	`string`	When using HTTPS, file that contains the private key to authenticate with the peer.
`token`	`string`	The runner’s authentication token, which is obtained during runner registration. Not the same as the registration token.
`url`	`string`	GitLab instance URL.

`buildsDir`^Optional

public readonly buildsDir: string;

Type: string

Absolute path to a directory where builds are stored in the context of the selected executor.

For example, locally, Docker, or SSH.

`cache`^Optional

public readonly cache: CacheConfiguration;

Type: CacheConfiguration

The runner's AWS S3 cache configuration.

https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section

`cacheDir`^Optional

public readonly cacheDir: string;

Type: string

Absolute path to a directory where build caches are stored in context of selected executor.

For example, locally, Docker, or SSH. If the docker executor is used, this directory needs to be included in its volumes parameter.

`cloneUrl`^Optional

public readonly cloneUrl: string;

Type: string

Overwrite the URL for the GitLab instance.

Used only if the runner can’t connect to the GitLab URL.

`debugTraceDisabled`^Optional

public readonly debugTraceDisabled: boolean;

Type: boolean

Disables the CI_DEBUG_TRACE feature.

When set to true, then debug log (trace) remains disabled, even if CI_DEBUG_TRACE is set to true by the user.

`docker`^Optional

public readonly docker: DockerConfiguration;

Type: DockerConfiguration

The runner's docker configuration.

https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersdocker-section

`environment`^Optional

public readonly environment: string[];

Type: string[]
Default: ["DOCKER_DRIVER=overlay2", "DOCKER_TLS_CERTDIR=/certs"]

Append or overwrite environment variables.

`executor`^Optional

public readonly executor: string;

Type: string
Default: "docker+machine"

Select how a project should be built.

`limit`^Optional

public readonly limit: number;

Type: number
Default: 10

Limit how many jobs can be handled concurrently by this registered runner.

0 (default) means do not limit.

`machine`^Optional

public readonly machine: MachineConfiguration;

Type: MachineConfiguration

The runner's Docker Machine configuration.

https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/#the-runnersmachine-section

`name`^Optional

public readonly name: string;

Type: string
Default: "gitlab-runner"

The runner’s description.

Informational only.

`outputLimit`^Optional

public readonly outputLimit: number;

Type: number
Default: 52428800 (50GB)

Maximum build log size in kilobytes.

Default is 4096 (4MB).

`postBuildScript`^Optional

public readonly postBuildScript: string;

Type: string

Commands to be executed on the runner just after executing the build, but before executing after_script.

To insert multiple commands, use a (triple-quoted) multi-line string or \n character.

`preBuildScript`^Optional

public readonly preBuildScript: string;

Type: string

Commands to be executed on the runner after cloning the Git repository, but before executing the build.

To insert multiple commands, use a (triple-quoted) multi-line string or \n character.

`preCloneScript`^Optional

public readonly preCloneScript: string;

Type: string

Commands to be executed on the runner before cloning the Git repository.

Use it to adjust the Git client configuration first, for example. To insert multiple commands, use a (triple-quoted) multi-line string or \n character.

`referees`^Optional

public readonly referees: string;

Type: string

Extra job monitoring workers that pass their results as job artifacts to GitLab.

`requestConcurrency`^Optional

public readonly requestConcurrency: number;

Type: number

Limit number of concurrent requests for new jobs from GitLab.

Default is 1.

`shell`^Optional

public readonly shell: string;

Type: string

Name of shell to generate the script.

Default value is platform dependent.

`tlsCaFile`^Optional

public readonly tlsCaFile: string;

Type: string

When using HTTPS, file that contains the certificates to verify the peer.

See Self-signed certificates or custom Certification Authorities documentation.

`tlsCertFile`^Optional

public readonly tlsCertFile: string;

Type: string

When using HTTPS, file that contains the certificate to authenticate with the peer.

`tlsKeyFile`^Optional

public readonly tlsKeyFile: string;

Type: string

When using HTTPS, file that contains the private key to authenticate with the peer.

`token`^Optional

public readonly token: string;

Type: string

The runner’s authentication token, which is obtained during runner registration. Not the same as the registration token.

Will be replaced by the runner's props token SSM Parameter

https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner

`url`^Optional

public readonly url: string;

Type: string
Default: "https://gitlab.com"

GitLab instance URL.

SharedCreateOptions

https://gitlab.com/gitlab-org/ci-cd/docker-machine/-/blob/main/commands/create.go

Initializer

import { SharedCreateOptions } from '@pepperize/cdk-autoscaling-gitlab-runner'

const sharedCreateOptions: SharedCreateOptions = { ... }

Properties

Name	Type	Description
`engineInstallUrl`	`string`	Custom URL to use for engine installation.

`engineInstallUrl`^Optional

public readonly engineInstallUrl: string;

Type: string
Default: https://releases.rancher.com/install-docker/20.10.21.sh

Custom URL to use for engine installation.

Classes

ConfigurationMapper

Methods

Name	Description
`toToml`	No description.

`toToml`

public toToml(): string

Static Functions

Name	Description
`fromProps`	No description.
`withDefaults`	No description.

`fromProps`

import { ConfigurationMapper } from '@pepperize/cdk-autoscaling-gitlab-runner'

ConfigurationMapper.fromProps(props: ConfigurationMapperProps)

`props`^Required

Type: ConfigurationMapperProps

`withDefaults`

import { ConfigurationMapper } from '@pepperize/cdk-autoscaling-gitlab-runner'

ConfigurationMapper.withDefaults(props: ConfigurationMapperProps)

`props`^Required

Type: ConfigurationMapperProps

Properties

Name	Type	Description
`props`	`ConfigurationMapperProps`	No description.

`props`^Required

public readonly props: ConfigurationMapperProps;

Type: ConfigurationMapperProps

DockerMachineVersion

Docker+machine version.

https://gitlab.com/gitlab-org/ci-cd/docker-machine

Static Functions

Name	Description
`of`	Custom docker+machine version.

`of`

import { DockerMachineVersion } from '@pepperize/cdk-autoscaling-gitlab-runner'

DockerMachineVersion.of(version: string)

Custom docker+machine version.

`version`^Required

Type: string

docker+machine version number.

Properties

Name	Type	Description
`version`	`string`	No description.

`version`^Required

public readonly version: string;

Type: string

Constants

Name	Type	Description
`V0_16_2_GITLAB_15`	`DockerMachineVersion`	Docker+machine version 0.16.2-gitlab.15.

`V0_16_2_GITLAB_15`^Required

public readonly V0_16_2_GITLAB_15: DockerMachineVersion;

Type: DockerMachineVersion

Docker+machine version 0.16.2-gitlab.15.

Files

API.md

Latest commit

History

API.md

File metadata and controls

AWS CDK GitLab Runner autoscaling on EC2

Install

TypeScript

Python

C# / .Net

Java

Quickstart

Example

Custom cache bucket

Custom EC2 key pair

Configure Docker Machine

Bigger instance type

Different machine image

Multiple runners configuration

Spot instances

Cross-Compile with Multiarch

Running on AWS Graviton

Custom runner's role

Vpc

Zero config

ECR Credentials Helper

Projen

API Reference

Constructs

Cache

Initializers

scopeRequired

idRequired

propsOptional

Methods

toString

Static Functions

isConstruct

xRequired

Properties

nodeRequired

bucketRequired

GitlabRunnerAutoscaling

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

Static Functions

isConstruct

xRequired

Properties

nodeRequired

cacheBucketRequired

managerRequired

networkRequired

runnersRequired

checkIntervalOptional

concurrentOptional

logFormatOptional

logLevelOptional

GitlabRunnerAutoscalingJobRunner

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

Static Functions

isConstruct

xRequired

Properties

nodeRequired

configurationRequired

instanceProfileRequired

instanceTypeRequired

machineImageRequired

roleRequired

`scope`^Required

`id`^Required

`props`^Optional

`toString`

`isConstruct`

`x`^Required

`node`^Required

`bucket`^Required

`scope`^Required

`id`^Required

`props`^Required

`toString`

`isConstruct`

`x`^Required

`node`^Required

`cacheBucket`^Required

`manager`^Required

`network`^Required

`runners`^Required

`checkInterval`^Optional

`concurrent`^Optional

`logFormat`^Optional

`logLevel`^Optional

`scope`^Required

`id`^Required

`props`^Required

`toString`

`isConstruct`

`x`^Required

`node`^Required

`configuration`^Required

`instanceProfile`^Required

`instanceType`^Required

`machineImage`^Required

`role`^Required

`keyPair`^Optional

`scope`^Required

`id`^Required

`props`^Required

`toString`

`isConstruct`

`x`^Required

`node`^Required

`cacheBucket`^Required

`globalConfiguration`^Required

`initConfig`^Required

`instanceType`^Required

`machineImage`^Required

`network`^Required

`role`^Required

`runners`^Required

`runnersSecurityGroupName`^Required

`userData`^Required

`keyPairName`^Optional

`scope`^Required

`id`^Required

`props`^Optional

`toString`

`hasPrivateSubnets`

`isConstruct`

`x`^Required

`node`^Required

`availabilityZone`^Required

`subnet`^Required

`vpc`^Required

`idleCount`^Optional

`idleTime`^Optional

`periods`^Optional

`timezone`^Optional

`s3`^Optional

`shared`^Optional

`type`^Optional

`bucketName`^Optional

`expiration`^Optional

`accessKey`^Optional