AWS CDK GitLab Runner autoscaling on EC2 instances using docker+machine executor.
Project description
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
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"],
- Add
-
Update project files and install dependencies
npx projen
-
Register a new runner
- 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
-
Retrieve a new runner authentication token
curl --request POST "https://gitlab.com/api/v4/runners" --form "token=<your register token>" --form "description=gitlab-runner" --form "tag_list=pepperize,docker,production"
-
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>", }); new GitlabRunnerAutoscaling(stack, "GitlabRunner", { gitlabToken: "<your gitlab runner auth token>", network: { vpc, }, });
-
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 is created as GitLab Runner's distributed cache. It's encrypted with a KMS managed key and public access is blocked. A custom S3 Bucket can be configured.
const cache = new Bucket(this, "Cache", {
// Your custom bucket
});
new GitlabRunnerAutoscaling(this, "Runner", {
gitlabToken: "<auth token>",
cache: { bucket: cache },
});
See example
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";
new GitlabRunnerAutoscaling(this, "Runner", {
gitlabToken: "<auth token>",
runners: {
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
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.
new GitlabRunnerAutoscaling(this, "Runner", {
gitlabToken: "<auth token>",
manager: {
instanceType: InstanceType.of(InstanceClass.T3, InstanceSize.NANO),
},
runners: {
instanceType: InstanceType.of(InstanceClass.T3, InstanceSize.LARGE),
},
});
See example
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.
new GitlabRunnerAutoscaling(this, "Runner", {
gitlabToken: "<auth token>",
manager: {
machineImage: MachineImage.genericLinux(managerAmiMap),
},
runners: {
machineImage: MachineImage.genericLinux(runnerAmiMap),
},
});
See example
Spot instances
By default, EC2 Spot Instances are requested.
new GitlabRunnerAutoscaling(this, "Runner", {
gitlabToken: "<auth token>",
runners: {
machine: {
machineOptions: {
requestSpotInstance: false,
spotPrice: 0.5,
},
},
},
});
See example
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: {},
});
new GitlabRunnerAutoscaling(this, "Runner", {
gitlabToken: "<auth token>",
runners: {
role: role,
},
});
See example
Vpc
If no existing Vpc is passed, a VPC that spans a whole region on will be created. This can become costly, because AWS CDK configured also the routing for the private subnets and creates NAT Gateways (one per AZ).
const vpc = new Vpc(this, "Vpc", {
// Your custom vpc
});
new GitlabRunnerAutoscaling(this, "Runner", {
gitlabToken: "<auth token>",
network: { vpc: vpc },
});
See example
Zero config
Deploys the Autoscaling GitLab Runner on AWS EC2 with the default settings mentioned above.
Happy with the presets?
new GitlabRunnerAutoscaling(this, "Runner", {
gitlabToken: "<auth token>",
});
See example
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.
See also Create and Publish CDK Constructs Using projen and jsii.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pepperize.cdk-autoscaling-gitlab-runner-0.0.163.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | fea6368d384324fa1681b99c6916507baa1fa1342a4f8792f7e6d7fb5bdaa602 |
|
MD5 | c01ac4052ba2fc9728a6a6171dae5579 |
|
BLAKE2b-256 | 602d92da602085eb4e97446adb991e2d46a2db34f2c33fb9b8819d465cd1e68a |
Hashes for pepperize.cdk_autoscaling_gitlab_runner-0.0.163-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d6878d9c5373abeb6dd93b38f9ff4067e2a82e047f21ee0b22adb7f67b284d20 |
|
MD5 | d541f03daf995ea45d75cfd65228d5e3 |
|
BLAKE2b-256 | ca398644cd777844cf511ff7cfbc6e1dac843d5d9db591041bcdd0556a2fbf88 |