com.cloudsnorkel.cdk.github.runners.GitHubRunners Maven / Gradle / Ivy
Show all versions of cdk.github.runners Show documentation
package com.cloudsnorkel.cdk.github.runners;
/**
* (experimental) Create all the required infrastructure to provide self-hosted GitHub runners.
*
* It creates a webhook, secrets, and a step function to orchestrate all runs. Secrets are not automatically filled. See README.md for instructions on how to setup GitHub integration.
*
* By default, this will create a runner provider of each available type with the defaults. This is good enough for the initial setup stage when you just want to get GitHub integration working.
*
*
* new GitHubRunners(this, 'runners');
*
*
* Usually you'd want to configure the runner providers so the runners can run in a certain VPC or have certain permissions.
*
*
* const vpc = ec2.Vpc.fromLookup(this, 'vpc', { vpcId: 'vpc-1234567' });
* const runnerSg = new ec2.SecurityGroup(this, 'runner security group', { vpc: vpc });
* const dbSg = ec2.SecurityGroup.fromSecurityGroupId(this, 'database security group', 'sg-1234567');
* const bucket = new s3.Bucket(this, 'runner bucket');
* // create a custom CodeBuild provider
* const myProvider = new CodeBuildRunnerProvider(
* this, 'codebuild runner',
* {
* labels: ['my-codebuild'],
* vpc: vpc,
* securityGroups: [runnerSg],
* },
* );
* // grant some permissions to the provider
* bucket.grantReadWrite(myProvider);
* dbSg.connections.allowFrom(runnerSg, ec2.Port.tcp(3306), 'allow runners to connect to MySQL database');
* // create the runner infrastructure
* new GitHubRunners(
* this,
* 'runners',
* {
* providers: [myProvider],
* }
* );
*
*/
@javax.annotation.Generated(value = "jsii-pacmak/1.103.1 (build bef2dea)", date = "2024-09-14T02:42:19.442Z")
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
@software.amazon.jsii.Jsii(module = com.cloudsnorkel.cdk.github.runners.$Module.class, fqn = "@cloudsnorkel/cdk-github-runners.GitHubRunners")
public class GitHubRunners extends software.constructs.Construct implements software.amazon.awscdk.services.ec2.IConnectable {
protected GitHubRunners(final software.amazon.jsii.JsiiObjectRef objRef) {
super(objRef);
}
protected GitHubRunners(final software.amazon.jsii.JsiiObject.InitializationMode initializationMode) {
super(initializationMode);
}
/**
* @param scope This parameter is required.
* @param id This parameter is required.
* @param props
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public GitHubRunners(final @org.jetbrains.annotations.NotNull software.constructs.Construct scope, final @org.jetbrains.annotations.NotNull java.lang.String id, final @org.jetbrains.annotations.Nullable com.cloudsnorkel.cdk.github.runners.GitHubRunnersProps props) {
super(software.amazon.jsii.JsiiObject.InitializationMode.JSII);
software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(scope, "scope is required"), java.util.Objects.requireNonNull(id, "id is required"), props });
}
/**
* @param scope This parameter is required.
* @param id This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public GitHubRunners(final @org.jetbrains.annotations.NotNull software.constructs.Construct scope, final @org.jetbrains.annotations.NotNull java.lang.String id) {
super(software.amazon.jsii.JsiiObject.InitializationMode.JSII);
software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(scope, "scope is required"), java.util.Objects.requireNonNull(id, "id is required") });
}
/**
* (experimental) Creates CloudWatch Logs Insights saved queries that can be used to debug issues with the runners.
*
*
* - "Webhook errors" helps diagnose configuration issues with GitHub integration
* - "Ignored webhook" helps understand why runners aren't started
* - "Ignored jobs based on labels" helps debug label matching issues
* - "Webhook started runners" helps understand which runners were started
*
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public void createLogsInsightsQueries() {
software.amazon.jsii.Kernel.call(this, "createLogsInsightsQueries", software.amazon.jsii.NativeType.VOID);
}
/**
* (experimental) Creates a topic for notifications when a runner image build fails.
*
* Runner images are rebuilt every week by default. This provides the latest GitHub Runner version and software updates.
*
* If you want to be sure you are using the latest runner version, you can use this topic to be notified when a build fails.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.sns.Topic failedImageBuildsTopic() {
return software.amazon.jsii.Kernel.call(this, "failedImageBuildsTopic", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.sns.Topic.class));
}
/**
* (experimental) Metric for failed runner executions.
*
* A failed runner usually means the runner failed to start and so a job was never executed. It doesn't necessarily mean the job was executed and failed. For that, see {@link metricJobCompleted}.
*
* @param props
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.cloudwatch.Metric metricFailed(final @org.jetbrains.annotations.Nullable software.amazon.awscdk.services.cloudwatch.MetricProps props) {
return software.amazon.jsii.Kernel.call(this, "metricFailed", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.cloudwatch.Metric.class), new Object[] { props });
}
/**
* (experimental) Metric for failed runner executions.
*
* A failed runner usually means the runner failed to start and so a job was never executed. It doesn't necessarily mean the job was executed and failed. For that, see {@link metricJobCompleted}.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.cloudwatch.Metric metricFailed() {
return software.amazon.jsii.Kernel.call(this, "metricFailed", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.cloudwatch.Metric.class));
}
/**
* (experimental) Metric for the number of GitHub Actions jobs completed.
*
* It has ProviderLabels and Status dimensions. The status can be one of "Succeeded", "SucceededWithIssues", "Failed", "Canceled", "Skipped", or "Abandoned".
*
* WARNING: this method creates a metric filter for each provider. Each metric has a status dimension with six possible values. These resources may incur cost.
*
* @param props
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.cloudwatch.Metric metricJobCompleted(final @org.jetbrains.annotations.Nullable software.amazon.awscdk.services.cloudwatch.MetricProps props) {
return software.amazon.jsii.Kernel.call(this, "metricJobCompleted", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.cloudwatch.Metric.class), new Object[] { props });
}
/**
* (experimental) Metric for the number of GitHub Actions jobs completed.
*
* It has ProviderLabels and Status dimensions. The status can be one of "Succeeded", "SucceededWithIssues", "Failed", "Canceled", "Skipped", or "Abandoned".
*
* WARNING: this method creates a metric filter for each provider. Each metric has a status dimension with six possible values. These resources may incur cost.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.cloudwatch.Metric metricJobCompleted() {
return software.amazon.jsii.Kernel.call(this, "metricJobCompleted", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.cloudwatch.Metric.class));
}
/**
* (experimental) Metric for successful executions.
*
* A successful execution doesn't always mean a runner was started. It can be successful even without any label matches.
* A successful runner doesn't mean the job it executed was successful. For that, see {@link metricJobCompleted}.
*
* @param props
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.cloudwatch.Metric metricSucceeded(final @org.jetbrains.annotations.Nullable software.amazon.awscdk.services.cloudwatch.MetricProps props) {
return software.amazon.jsii.Kernel.call(this, "metricSucceeded", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.cloudwatch.Metric.class), new Object[] { props });
}
/**
* (experimental) Metric for successful executions.
*
* A successful execution doesn't always mean a runner was started. It can be successful even without any label matches.
* A successful runner doesn't mean the job it executed was successful. For that, see {@link metricJobCompleted}.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.cloudwatch.Metric metricSucceeded() {
return software.amazon.jsii.Kernel.call(this, "metricSucceeded", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.cloudwatch.Metric.class));
}
/**
* (experimental) Metric for the interval, in milliseconds, between the time the execution starts and the time it closes.
*
* This time may be longer than the time the runner took.
*
* @param props
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.cloudwatch.Metric metricTime(final @org.jetbrains.annotations.Nullable software.amazon.awscdk.services.cloudwatch.MetricProps props) {
return software.amazon.jsii.Kernel.call(this, "metricTime", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.cloudwatch.Metric.class), new Object[] { props });
}
/**
* (experimental) Metric for the interval, in milliseconds, between the time the execution starts and the time it closes.
*
* This time may be longer than the time the runner took.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.cloudwatch.Metric metricTime() {
return software.amazon.jsii.Kernel.call(this, "metricTime", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.cloudwatch.Metric.class));
}
/**
* (experimental) Manage the connections of all management functions.
*
* Use this to enable connections to your GitHub Enterprise Server in a VPC.
*
* This cannot be used to manage connections of the runners. Use the connections property of each runner provider to manage runner connections.
*/
@Override
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.ec2.Connections getConnections() {
return software.amazon.jsii.Kernel.get(this, "connections", software.amazon.jsii.NativeType.forClass(software.amazon.awscdk.services.ec2.Connections.class));
}
/**
* (experimental) Configured runner providers.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull java.util.List getProviders() {
return java.util.Collections.unmodifiableList(software.amazon.jsii.Kernel.get(this, "providers", software.amazon.jsii.NativeType.listOf(software.amazon.jsii.NativeType.forClass(com.cloudsnorkel.cdk.github.runners.IRunnerProvider.class))));
}
/**
* (experimental) Secrets for GitHub communication including webhook secret and runner authentication.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.NotNull com.cloudsnorkel.cdk.github.runners.Secrets getSecrets() {
return software.amazon.jsii.Kernel.get(this, "secrets", software.amazon.jsii.NativeType.forClass(com.cloudsnorkel.cdk.github.runners.Secrets.class));
}
/**
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public @org.jetbrains.annotations.Nullable com.cloudsnorkel.cdk.github.runners.GitHubRunnersProps getProps() {
return software.amazon.jsii.Kernel.get(this, "props", software.amazon.jsii.NativeType.forClass(com.cloudsnorkel.cdk.github.runners.GitHubRunnersProps.class));
}
/**
* (experimental) A fluent builder for {@link com.cloudsnorkel.cdk.github.runners.GitHubRunners}.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public static final class Builder implements software.amazon.jsii.Builder {
/**
* @return a new instance of {@link Builder}.
* @param scope This parameter is required.
* @param id This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public static Builder create(final software.constructs.Construct scope, final java.lang.String id) {
return new Builder(scope, id);
}
private final software.constructs.Construct scope;
private final java.lang.String id;
private com.cloudsnorkel.cdk.github.runners.GitHubRunnersProps.Builder props;
private Builder(final software.constructs.Construct scope, final java.lang.String id) {
this.scope = scope;
this.id = id;
}
/**
* (experimental) Allow management functions to run in public subnets.
*
* Lambda Functions in a public subnet can NOT access the internet.
*
* Default: false
*
* @return {@code this}
* @param allowPublicSubnet Allow management functions to run in public subnets. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder allowPublicSubnet(final java.lang.Boolean allowPublicSubnet) {
this.props().allowPublicSubnet(allowPublicSubnet);
return this;
}
/**
* (experimental) Path to a directory containing a file named certs.pem containing any additional certificates required to trust GitHub Enterprise Server. Use this when GitHub Enterprise Server certificates are self-signed.
*
* You may also want to use custom images for your runner providers that contain the same certificates. See {@link CodeBuildImageBuilder.addCertificates }.
* ```java
* const imageBuilder = CodeBuildRunnerProvider.imageBuilder(this, 'Image Builder with Certs');
* imageBuilder.addComponent(RunnerImageComponent.extraCertificates('path-to-my-extra-certs-folder/certs.pem', 'private-ca');
* const provider = new CodeBuildRunnerProvider(this, 'CodeBuild', {
* imageBuilder: imageBuilder,
* });
* new GitHubRunners(
* this,
* 'runners',
* {
* providers: [provider],
* extraCertificates: 'path-to-my-extra-certs-folder',
* }
* );
* ```
*
* @return {@code this}
* @param extraCertificates Path to a directory containing a file named certs.pem containing any additional certificates required to trust GitHub Enterprise Server. Use this when GitHub Enterprise Server certificates are self-signed. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder extraCertificates(final java.lang.String extraCertificates) {
this.props().extraCertificates(extraCertificates);
return this;
}
/**
* (experimental) Time to wait before stopping a runner that remains idle.
*
* If the user cancelled the job, or if another runner stole it, this stops the runner to avoid wasting resources.
*
* Default: 5 minutes
*
* @return {@code this}
* @param idleTimeout Time to wait before stopping a runner that remains idle. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder idleTimeout(final software.amazon.awscdk.Duration idleTimeout) {
this.props().idleTimeout(idleTimeout);
return this;
}
/**
* (experimental) Logging options for the state machine that manages the runners.
*
* Default: no logs
*
* @return {@code this}
* @param logOptions Logging options for the state machine that manages the runners. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder logOptions(final com.cloudsnorkel.cdk.github.runners.LogOptions logOptions) {
this.props().logOptions(logOptions);
return this;
}
/**
* (experimental) List of runner providers to use.
*
* At least one provider is required. Provider will be selected when its label matches the labels requested by the workflow job.
*
* Default: CodeBuild, Lambda and Fargate runners with all the defaults (no VPC or default account VPC)
*
* @return {@code this}
* @param providers List of runner providers to use. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder providers(final java.util.List providers) {
this.props().providers(providers);
return this;
}
/**
* (experimental) Whether to require the self-hosted label.
*
* If true, the runner will only start if the workflow job explicitly requests the self-hosted label.
*
* Be careful when setting this to false. Avoid setting up providers with generic label requirements like linux as they may match workflows that are not meant to run on self-hosted runners.
*
* Default: true
*
* @return {@code this}
* @param requireSelfHostedLabel Whether to require the self-hosted label. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder requireSelfHostedLabel(final java.lang.Boolean requireSelfHostedLabel) {
this.props().requireSelfHostedLabel(requireSelfHostedLabel);
return this;
}
/**
* (experimental) Options to retry operation in case of failure like missing capacity, or API quota issues.
*
* GitHub jobs time out after not being able to get a runner for 24 hours. You should not retry for more than 24 hours.
*
* Total time spent waiting can be calculated with interval * (backoffRate ^ maxAttempts) / (backoffRate - 1).
*
* Default: retry 23 times up to about 24 hours
*
* @return {@code this}
* @param retryOptions Options to retry operation in case of failure like missing capacity, or API quota issues. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder retryOptions(final com.cloudsnorkel.cdk.github.runners.ProviderRetryOptions retryOptions) {
this.props().retryOptions(retryOptions);
return this;
}
/**
* (deprecated) Security group attached to all management functions.
*
* Use this with to provide access to GitHub Enterprise Server hosted inside a VPC.
*
* @return {@code this}
* @deprecated use {@link securityGroups } instead
* @param securityGroup Security group attached to all management functions. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@Deprecated
public Builder securityGroup(final software.amazon.awscdk.services.ec2.ISecurityGroup securityGroup) {
this.props().securityGroup(securityGroup);
return this;
}
/**
* (experimental) Security groups attached to all management functions.
*
* Use this with to provide access to GitHub Enterprise Server hosted inside a VPC.
*
* @return {@code this}
* @param securityGroups Security groups attached to all management functions. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder securityGroups(final java.util.List securityGroups) {
this.props().securityGroups(securityGroups);
return this;
}
/**
* (experimental) Access configuration for the setup function.
*
* Once you finish the setup process, you can set this to LambdaAccess.noAccess() to remove access to the setup function. You can also use LambdaAccess.apiGateway({ allowedIps: ['my-ip/0']}) to limit access to your IP only.
*
* Default: LambdaAccess.lambdaUrl()
*
* @return {@code this}
* @param setupAccess Access configuration for the setup function. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder setupAccess(final com.cloudsnorkel.cdk.github.runners.LambdaAccess setupAccess) {
this.props().setupAccess(setupAccess);
return this;
}
/**
* (experimental) Access configuration for the status function.
*
* This function returns a lot of sensitive information about the runner, so you should only allow access to it from trusted IPs, if at all.
*
* Default: LambdaAccess.noAccess()
*
* @return {@code this}
* @param statusAccess Access configuration for the status function. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder statusAccess(final com.cloudsnorkel.cdk.github.runners.LambdaAccess statusAccess) {
this.props().statusAccess(statusAccess);
return this;
}
/**
* (experimental) VPC used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC.
*
* Make sure the selected VPC and subnets have access to the following with either NAT Gateway or VPC Endpoints:
*
*
* - GitHub Enterprise Server
* - Secrets Manager
* - SQS
* - Step Functions
* - CloudFormation (status function only)
* - EC2 (status function only)
* - ECR (status function only)
*
*
* @return {@code this}
* @param vpc VPC used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder vpc(final software.amazon.awscdk.services.ec2.IVpc vpc) {
this.props().vpc(vpc);
return this;
}
/**
* (experimental) VPC subnets used for all management functions.
*
* Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC.
*
* @return {@code this}
* @param vpcSubnets VPC subnets used for all management functions. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder vpcSubnets(final software.amazon.awscdk.services.ec2.SubnetSelection vpcSubnets) {
this.props().vpcSubnets(vpcSubnets);
return this;
}
/**
* (experimental) Access configuration for the webhook function.
*
* This function is called by GitHub when a new workflow job is scheduled. For an extra layer of security, you can set this to LambdaAccess.apiGateway({ allowedIps: LambdaAccess.githubWebhookIps() }).
*
* You can also set this to LambdaAccess.apiGateway({allowedVpc: vpc, allowedIps: ['GHES.IP.ADDRESS/32']}) if your GitHub Enterprise Server is hosted in a VPC. This will create an API Gateway endpoint that's only accessible from within the VPC.
*
* WARNING: changing access type may change the URL. When the URL changes, you must update GitHub as well.
*
* Default: LambdaAccess.lambdaUrl()
*
* @return {@code this}
* @param webhookAccess Access configuration for the webhook function. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
public Builder webhookAccess(final com.cloudsnorkel.cdk.github.runners.LambdaAccess webhookAccess) {
this.props().webhookAccess(webhookAccess);
return this;
}
/**
* @return a newly built instance of {@link com.cloudsnorkel.cdk.github.runners.GitHubRunners}.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
@Override
public com.cloudsnorkel.cdk.github.runners.GitHubRunners build() {
return new com.cloudsnorkel.cdk.github.runners.GitHubRunners(
this.scope,
this.id,
this.props != null ? this.props.build() : null
);
}
private com.cloudsnorkel.cdk.github.runners.GitHubRunnersProps.Builder props() {
if (this.props == null) {
this.props = new com.cloudsnorkel.cdk.github.runners.GitHubRunnersProps.Builder();
}
return this.props;
}
}
}