Skip to content

Latest commit

 

History

History
1260 lines (787 loc) · 38.8 KB

API.md

File metadata and controls

1260 lines (787 loc) · 38.8 KB

API Reference

Constructs

GitlabContainerRunner

GitlabContainerRunner Construct for create a Gitlab Runner.

Initializers

import { GitlabContainerRunner } from 'cdk-gitlab-runner'

new GitlabContainerRunner(scope: Construct, id: string, props: GitlabContainerRunnerProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props GitlabContainerRunnerProps No description.

scopeRequired
  • Type: constructs.Construct

idRequired
  • Type: string

propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
createUserData No description.
expireAfter Add expire time function for spotfleet runner !!! .

toString
public toString(): string

Returns a string representation of this construct.

createUserData
public createUserData(props: GitlabContainerRunnerProps, tokenParameterStoreName: string): string[]
propsRequired

tokenParameterStoreNameRequired
  • Type: string

the tokenParameterStoreName to put gitlab runner token.


expireAfter
public expireAfter(duration: Duration): void

Add expire time function for spotfleet runner !!! .

durationRequired
  • Type: aws-cdk-lib.Duration

Block duration.


Static Functions

Name Description
isConstruct Checks if x is a construct.

isConstruct
import { GitlabContainerRunner } from 'cdk-gitlab-runner'

GitlabContainerRunner.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.


Properties

Name Type Description
node constructs.Node The tree node.
defaultRunnerSG aws-cdk-lib.aws_ec2.ISecurityGroup The EC2 runner's default SecurityGroup.
runnerEc2 aws-cdk-lib.aws_ec2.IInstance This represents a Runner EC2 instance , !!! only support On-demand runner instance !!!
runnerRole aws-cdk-lib.aws_iam.IRole The IAM role assumed by the Runner instance .
spotFleetInstanceId string the first instance id in this fleet , !!! only support spotfleet runner !!!
spotFleetRequestId string SpotFleetRequestId for this spot fleet , !!! only support spotfleet runner !!!
vpc aws-cdk-lib.aws_ec2.IVpc The EC2 runner's vpc.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


defaultRunnerSGRequired
public readonly defaultRunnerSG: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup

The EC2 runner's default SecurityGroup.


runnerEc2Required
public readonly runnerEc2: IInstance;
  • Type: aws-cdk-lib.aws_ec2.IInstance

This represents a Runner EC2 instance , !!! only support On-demand runner instance !!!


runnerRoleRequired
public readonly runnerRole: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole

The IAM role assumed by the Runner instance .


spotFleetInstanceIdRequired
public readonly spotFleetInstanceId: string;
  • Type: string

the first instance id in this fleet , !!! only support spotfleet runner !!!


spotFleetRequestIdRequired
public readonly spotFleetRequestId: string;
  • Type: string

SpotFleetRequestId for this spot fleet , !!! only support spotfleet runner !!!


vpcRequired
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

The EC2 runner's vpc.


GitlabRunnerAutoscaling

GitlabRunnerAutoscaling Construct for create Autoscaling Gitlab Runner.

Initializers

import { GitlabRunnerAutoscaling } from 'cdk-gitlab-runner'

new GitlabRunnerAutoscaling(scope: Construct, id: string, props: GitlabRunnerAutoscalingProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props GitlabRunnerAutoscalingProps No description.

scopeRequired
  • Type: constructs.Construct

idRequired
  • Type: string

propsRequired

Methods

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

toString
public toString(): string

Returns a string representation of this construct.

createUserData
public createUserData(props: GitlabRunnerAutoscalingProps): string[]
propsRequired

Static Functions

Name Description
isConstruct Checks if x is a construct.

isConstruct
import { GitlabRunnerAutoscaling } from 'cdk-gitlab-runner'

GitlabRunnerAutoscaling.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.


Properties

Name Type Description
node constructs.Node The tree node.
autoscalingGroup aws-cdk-lib.aws_autoscaling.AutoScalingGroup This represents a Runner Auto Scaling Group.
instanceRole aws-cdk-lib.aws_iam.IRole The IAM role assumed by the Runner instance.
securityGroup aws-cdk-lib.aws_ec2.ISecurityGroup The EC2 runner's default SecurityGroup.
topicAlarm aws-cdk-lib.aws_sns.ITopic The SNS topic to suscribe alarms for EC2 runner's metrics.
vpc aws-cdk-lib.aws_ec2.IVpc The EC2 runner's VPC.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


autoscalingGroupRequired
public readonly autoscalingGroup: AutoScalingGroup;
  • Type: aws-cdk-lib.aws_autoscaling.AutoScalingGroup

This represents a Runner Auto Scaling Group.


instanceRoleRequired
public readonly instanceRole: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole

The IAM role assumed by the Runner instance.


securityGroupRequired
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup

The EC2 runner's default SecurityGroup.


topicAlarmRequired
public readonly topicAlarm: ITopic;
  • Type: aws-cdk-lib.aws_sns.ITopic

The SNS topic to suscribe alarms for EC2 runner's metrics.


vpcRequired
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

The EC2 runner's VPC.


Structs

DockerVolumes

Docker Volumes interface.

Initializer

import { DockerVolumes } from 'cdk-gitlab-runner'

const dockerVolumes: DockerVolumes = { ... }

Properties

Name Type Description
containerPath string Job Runtime Container Path Host Path.
hostPath string EC2 Runner Host Path.

containerPathRequired
public readonly containerPath: string;
  • Type: string

Job Runtime Container Path Host Path.


Example

- /tmp/cahce
more detail see https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersdocker-section
hostPathRequired
public readonly hostPath: string;
  • Type: string

EC2 Runner Host Path.


Example

- /tmp/cahce
more detail see https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersdocker-section

GitlabContainerRunnerProps

GitlabContainerRunner Props.

Initializer

import { GitlabContainerRunnerProps } from 'cdk-gitlab-runner'

const gitlabContainerRunnerProps: GitlabContainerRunnerProps = { ... }

Properties

Name Type Description
gitlabRunnerVersion string Gitlab Runner version Please give me gitlab runner version.
gitlabtoken string Gitlab token for the Register Runner .
concurrentJobs number Gitlab Runner concurrent job configuration.
dockerVolumes DockerVolumes[] add another Gitlab Container Runner Docker Volumes Path at job runner runtime.
ebsSize number Gitlab Runner instance EBS size .
ec2iamrole aws-cdk-lib.aws_iam.IRole IAM role for the Gitlab Runner Instance .
ec2type string Runner default EC2 instance type.
enabledIMDSv2 boolean Enabled IMDSv2.
gitlabRunnerImage string Image URL of Gitlab Runner.
gitlaburl string Gitlab Runner register url .
instanceInterruptionBehavior InstanceInterruptionBehavior The behavior when a Spot Runner Instance is interrupted.
keyName string SSH key name.
runnerDescription string Gitlab Runner description.
selfvpc aws-cdk-lib.aws_ec2.IVpc VPC for the Gitlab Runner .
spotFleet boolean Gitlab Runner instance Use Spot Fleet or not ?!.
tags string[] tags for the runner Unsupported Gitlab Runner 15.10 and later.
validUntil string the time when the spot fleet allocation expires.
vpcSubnet aws-cdk-lib.aws_ec2.SubnetSelection VPC subnet for the spot fleet.

gitlabRunnerVersionRequired
public readonly gitlabRunnerVersion: string;
  • Type: string

Gitlab Runner version Please give me gitlab runner version.


gitlabtokenRequired
public readonly gitlabtoken: string;
  • Type: string
  • Default: You must to give the token !!!

Gitlab token for the Register Runner .


Example

new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN' });
concurrentJobsOptional
public readonly concurrentJobs: number;
  • Type: number
  • Default: concurrentJobs=1

Gitlab Runner concurrent job configuration.


Example

const runner = new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN',concurrentJobs: 3});
dockerVolumesOptional
public readonly dockerVolumes: DockerVolumes[];
  • Type: DockerVolumes[]
  • Default: already mount "/var/run/docker.sock:/var/run/docker.sock"

add another Gitlab Container Runner Docker Volumes Path at job runner runtime.

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


Example

dockerVolumes: [
  {
    hostPath: '/tmp/cache',
    containerPath: '/tmp/cache',
  },
],
ebsSizeOptional
public readonly ebsSize: number;
  • Type: number
  • Default: ebsSize=60

Gitlab Runner instance EBS size .


Example

const runner = new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN',ebsSize: 100});
ec2iamroleOptional
public readonly ec2iamrole: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole
  • Default: new Role for Gitlab Runner Instance , attach AmazonSSMManagedInstanceCore Policy .

IAM role for the Gitlab Runner Instance .


Example

const role = new Role(stack, 'runner-role', {
  assumedBy: new ServicePrincipal('ec2.amazonaws.com'),
  description: 'For Gitlab EC2 Runner Test Role',
  roleName: 'Myself-Runner-Role',
});

new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN', ec2iamrole: role });
ec2typeOptional
public readonly ec2type: string;
  • Type: string
  • Default: t3.micro

Runner default EC2 instance type.


Example

new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN', ec2type: 't3.small' });
enabledIMDSv2Optional
public readonly enabledIMDSv2: boolean;
  • Type: boolean
  • Default: false

Enabled IMDSv2.

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


gitlabRunnerImageOptional
public readonly gitlabRunnerImage: string;
  • Type: string
  • Default: public.ecr.aws/gitlab/gitlab-runner:latest !!! <--- latest now > 16.0 Gitlab Runner version

Image URL of Gitlab Runner.


Example

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', gitlabRunnerImage: 'gitlab/gitlab-runner:alpine' });
gitlaburlOptional
public readonly gitlaburl: string;

Gitlab Runner register url .


Example

const runner = new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN',gitlaburl: 'https://gitlab.com/'});
instanceInterruptionBehaviorOptional
public readonly instanceInterruptionBehavior: InstanceInterruptionBehavior;

The behavior when a Spot Runner Instance is interrupted.


keyNameOptional
public readonly keyName: string;
  • Type: string
  • Default: no ssh key will be assigned , !!! only support spotfleet runner !!! .

SSH key name.


runnerDescriptionOptional
public readonly runnerDescription: string;
  • Type: string
  • Default: runnerDescription='Docker Runner'

Gitlab Runner description.


Example

const runner = new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN',runnerDescription: 'Simple GitLab Runner'});
selfvpcOptional
public readonly selfvpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc
  • Default: new VPC will be created , 1 Vpc , 2 Public Subnet .

VPC for the Gitlab Runner .


Example

const newvpc = new Vpc(stack, 'NEWVPC', {
  ipAddresses: IpAddresses.cidr('10.0.0.0/16'),
  maxAzs: 2,
  subnetConfiguration: [{
    cidrMask: 26,
    name: 'RunnerVPC',
    subnetType: SubnetType.PUBLIC,
  }],
  natGateways: 0,
});

new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN', selfvpc: newvpc });
spotFleetOptional
public readonly spotFleet: boolean;
  • Type: boolean
  • Default: spotFleet=false

Gitlab Runner instance Use Spot Fleet or not ?!.


Example

const runner = new GitlabContainerRunner(stack, 'runner', { gitlabtoken: 'GITLAB_TOKEN',spotFleet: true});
tagsOptional
public readonly tags: string[];
  • Type: string[]
  • Default: ['runner', 'gitlab', 'awscdk']

tags for the runner Unsupported Gitlab Runner 15.10 and later.

[ - https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html]( - https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html)


validUntilOptional
public readonly validUntil: string;
  • Type: string
  • Default: no expiration , !!! only support spotfleet runner !!! .

the time when the spot fleet allocation expires.


vpcSubnetOptional
public readonly vpcSubnet: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
  • Default: public subnet

VPC subnet for the spot fleet.


Example

const vpc = new Vpc(stack, 'nat', {
natGateways: 1,
maxAzs: 2,
});
const runner = new GitlabContainerRunner(stack, 'testing', {
  gitlabtoken: 'GITLAB_TOKEN',
  ec2type: 't3.large',
  ec2iamrole: role,
  ebsSize: 100,
  selfvpc: vpc,
  vpcSubnet: {
    subnetType: SubnetType.PUBLIC,
  },
});

GitlabRunnerAutoscalingProps

GitlabRunnerAutoscaling Props.

Initializer

import { GitlabRunnerAutoscalingProps } from 'cdk-gitlab-runner'

const gitlabRunnerAutoscalingProps: GitlabRunnerAutoscalingProps = { ... }

Properties

Name Type Description
gitlabRunnerVersion string Gitlab Runner version Please give me gitlab runner version.
gitlabToken string Gitlab token.
alarms object[] Parameters of put_metric_alarm function.
desiredCapacity number Desired capacity limit for autoscaling group.
dockerVolumes DockerVolumes[] add another Gitlab Container Runner Docker Volumes Path at job runner runtime.
ebsSize number Gitlab Runner instance EBS size .
gitlabRunnerImage string Image URL of Gitlab Runner.
gitlabUrl string Gitlab Runner register url .
instanceRole aws-cdk-lib.aws_iam.IRole IAM role for the Gitlab Runner Instance .
instanceType string Runner default EC2 instance type.
maxCapacity number Maximum capacity limit for autoscaling group.
minCapacity number Minimum capacity limit for autoscaling group.
spotInstance boolean Run worker nodes as EC2 Spot.
tags string[] tags for the runner.
vpc aws-cdk-lib.aws_ec2.IVpc VPC for the Gitlab Runner .
vpcSubnet aws-cdk-lib.aws_ec2.SubnetSelection VPC subnet.

gitlabRunnerVersionRequired
public readonly gitlabRunnerVersion: string;
  • Type: string

Gitlab Runner version Please give me gitlab runner version.


gitlabTokenRequired
public readonly gitlabToken: string;
  • Type: string

Gitlab token.


Example

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN' });
alarmsOptional
public readonly alarms: object[];
  • Type: object[]
  • Default: [{ AlarmName: 'GitlabRunnerDiskUsage', MetricName: 'disk_used_percent', }]

Parameters of put_metric_alarm function.

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudwatch.html#CloudWatch.Client.put_metric_alarm


desiredCapacityOptional
public readonly desiredCapacity: number;
  • Type: number
  • Default: minCapacity, and leave unchanged during deployment

Desired capacity limit for autoscaling group.


Example

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', desiredCapacity: 2 });
dockerVolumesOptional
public readonly dockerVolumes: DockerVolumes[];
  • Type: DockerVolumes[]
  • Default: already mount "/var/run/docker.sock:/var/run/docker.sock"

add another Gitlab Container Runner Docker Volumes Path at job runner runtime.

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


Example

dockerVolumes: [
  {
    hostPath: '/tmp/cache',
    containerPath: '/tmp/cache',
  },
],
ebsSizeOptional
public readonly ebsSize: number;
  • Type: number
  • Default: ebsSize=60

Gitlab Runner instance EBS size .


Example

const runner = new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', ebsSize: 100});
gitlabRunnerImageOptional
public readonly gitlabRunnerImage: string;
  • Type: string
  • Default: public.ecr.aws/gitlab/gitlab-runner:latest

Image URL of Gitlab Runner.


Example

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', gitlabRunnerImage: 'gitlab/gitlab-runner:alpine' });
gitlabUrlOptional
public readonly gitlabUrl: string;

Gitlab Runner register url .


Example

const runner = new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN',gitlabUrl: 'https://gitlab.com/'});
instanceRoleOptional
public readonly instanceRole: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole
  • Default: new Role for Gitlab Runner Instance , attach AmazonSSMManagedInstanceCore Policy .

IAM role for the Gitlab Runner Instance .


Example

const role = new Role(stack, 'runner-role', {
  assumedBy: new ServicePrincipal('ec2.amazonaws.com'),
  description: 'For Gitlab Runner Test Role',
  roleName: 'Runner-Role',
});

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', instanceRole: role });
instanceTypeOptional
public readonly instanceType: string;
  • Type: string
  • Default: t3.micro

Runner default EC2 instance type.


Example

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', instanceType: 't3.small' });
maxCapacityOptional
public readonly maxCapacity: number;
  • Type: number
  • Default: desiredCapacity

Maximum capacity limit for autoscaling group.


Example

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', maxCapacity: 4 });
minCapacityOptional
public readonly minCapacity: number;
  • Type: number
  • Default: minCapacity: 1

Minimum capacity limit for autoscaling group.


Example

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', minCapacity: 2 });
spotInstanceOptional
public readonly spotInstance: boolean;
  • Type: boolean
  • Default: false

Run worker nodes as EC2 Spot.


tagsOptional
public readonly tags: string[];
  • Type: string[]
  • Default: ['runner', 'gitlab', 'awscdk']

tags for the runner.


vpcOptional
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc
  • Default: A new VPC will be created.

VPC for the Gitlab Runner .


Example

const newVpc = new Vpc(stack, 'NewVPC', {
  ipAddresses: IpAddresses.cidr('10.0.0.0/16'),
  maxAzs: 2,
  subnetConfiguration: [{
    cidrMask: 26,
    name: 'RunnerVPC',
    subnetType: SubnetType.PUBLIC,
  }],
  natGateways: 0,
});

new GitlabRunnerAutoscaling(stack, 'runner', { gitlabToken: 'GITLAB_TOKEN', vpc: newVpc });
vpcSubnetOptional
public readonly vpcSubnet: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
  • Default: SubnetType.PRIVATE subnet

VPC subnet.


Example

const vpc = new Vpc(stack, 'nat', {
natGateways: 1,
maxAzs: 2,
});
const runner = new GitlabRunnerAutoscaling(stack, 'testing', {
  gitlabToken: 'GITLAB_TOKEN',
  instanceType: 't3.large',
  instanceRole: role,
  ebsSize: 100,
  vpc: vpc,
  vpcSubnet: {
    subnetType: SubnetType.PUBLIC,
  },
});

Enums

InstanceInterruptionBehavior

InstanceInterruptionBehavior enum.

Members

Name Description
HIBERNATE hibernate.
STOP stop.
TERMINATE terminate.

HIBERNATE

hibernate.


STOP

stop.


TERMINATE

terminate.