aws-delivlib
Version:
A fabulous library for defining continuous pipelines for building, testing and releasing code libraries.
320 lines (319 loc) • 11.1 kB
TypeScript
import { Duration, aws_cloudwatch as cloudwatch, aws_codebuild as cbuild, aws_codepipeline as cpipeline, aws_codepipeline_actions as cpipeline_actions, aws_iam as iam } from 'aws-cdk-lib';
import { IRole } from 'aws-cdk-lib/aws-iam';
import { Construct } from 'constructs';
import { BuildSpec } from './build-spec';
export interface ShellableOptions {
/**
* Description for the CodeBuild Project
*/
readonly description?: string;
/**
* Source for the CodeBuild project
*
* @default no source
*/
source?: cbuild.ISource;
/**
* What platform to us to run the scripts on
*
* @default ShellPlatform.LinuxUbuntu
*/
platform?: ShellPlatform;
/**
* Additional environment variables to set.
*
* @default No additional environment variables
*/
environment?: {
[key: string]: string | undefined;
};
/**
* Environment variables with secrets manager values. The values must be complete Secret Manager ARNs.
*
* @default no additional environment variables
*/
environmentSecrets?: {
[key: string]: string;
};
/**
* Environment variables with SSM parameter values.
*
* @default no additional environment variables
*/
environmentParameters?: {
[key: string]: string;
};
/**
* The compute type to use for the build container.
*
* Note that not all combinations are available. For example,
* Windows images cannot be run on ComputeType.Small.
*
* @default ComputeType.Medium
*/
computeType?: cbuild.ComputeType;
/**
* Indicates how the project builds Docker images. Specify true to enable
* running the Docker daemon inside a Docker container. This value must be
* set to true only if this build project will be used to build Docker
* images, and the specified build environment image is not one provided by
* AWS CodeBuild with Docker support. Otherwise, all associated builds that
* attempt to interact with the Docker daemon will fail.
*
* @default false
*/
privileged?: boolean;
/**
* The name for the build project.
*
* @default a name is generated by CloudFormation.
*/
buildProjectName?: string;
/**
* Indicates if Regional AWS STS endpoints should be used instead
* of the global endpoint. Specify true to use Regional AWS STS endpoints.
*
* @default false
*/
useRegionalStsEndpoints?: boolean;
/**
* Can be used to run this build using a specific IAM role. This can be used,
* for example, to execute in the context of another account (e.g. to run
* tests in isolation).
*/
assumeRole?: AssumeRole;
/**
* Additional buildspec (for artifacts etc.)
*
* @default No additional buildspec
*/
buildSpec?: BuildSpec;
/**
* The timeout of the build.
*
* @default the CodeBuild default (1 hour)
*/
timeout?: Duration;
/**
* Alarm period.
*
* @default 300 seconds (5 minutes)
*/
alarmPeriod?: Duration;
/**
* Alarm threshold.
* @default 1
*/
alarmThreshold?: number;
/**
* Alarm evaluation periods.
* @default 1
*/
alarmEvaluationPeriods?: number;
secondaryArtifactNames?: string[];
/**
* Clarify whether this Shellable produces any artifacts
*
* @default true
*/
readonly producesArtifacts?: boolean;
/**
* Namespace to use when adding as an action to the pipeline
*
* @default No namespace
*/
readonly actionNamespace?: string;
/**
* Additional environment variables to set from the pipeline action
*
* @default No environment variables
*/
readonly pipelineEnvironmentVars?: Record<string, string>;
/**
* The service role to assume while running the build
*
* @default A role will be created
*/
readonly serviceRole?: IRole;
}
/**
* Properties used to create a Shellable
*/
export interface ShellableProps extends ShellableOptions {
/**
* Directory with the scripts.
*
* By default the whole directory will be uploaded. Use `excludeFilePatterns` to ignore files.
*/
scriptDirectory: string;
/**
* File paths matching the glob patterns will be excluded from the script dir.
*/
excludeFilePatterns?: string[];
/**
* Filename of the initial script to start, relative to scriptDirectory.
*/
entrypoint: string;
/**
* Additional arguments to pass to the entrypoint script.
*
* (NOTE: not named 'arguments' because that's a reserved identifier in JavaScript)
*
* @default No arguments
*/
readonly args?: string[];
}
export interface AssumeRole {
/**
* The Amazon Resource Name (ARN) of the role to assume.
*/
roleArn: string;
/**
* An identifier for the assumed role session.
*
* Use the role session name to uniquely identify a session when the same
* role is assumed by different principals or for different reasons. In
* cross-account scenarios, the role session name is visible to, and can be
* logged by the account that owns the role. The role session name is also
* used in the ARN of the assumed role principal. This means that subsequent
* cross-account API requests using the tem- porary security credentials will
* expose the role session name to the external account in their CloudTrail
* logs.
*
* The regex used to validate this parameter is a string of characters
* consisting of upper- and lower-case alphanumeric characters with no
* spaces. You can also include underscores or any of the following
* characters: =,.@-
*/
sessionName: string;
/**
* A unique identifier that is used by third parties when assuming roles
* in their customers' accounts. For each role that the third party can
* assume, they should instruct their customers to ensure the role's trust
* policy checks for the external ID that the third party generated. Each
* time the third party assumes the role, they should pass the customer's
* external ID. The external ID is useful in order to help third parties
* bind a role to the customer who created it. For more information about the
* external ID, see How to Use an Exter- nal ID When Granting Access to Your
* AWS Resources to a Third Party in the IAM User Guide .
*
* This parameter must be a string of characters consisting of upper- and
* lower-case alphanumeric characters with no spaces. You can also include
* underscores or any of the following characters: =,.@:/-
*/
externalId?: string;
/**
* When a profie name is configured, an assumed role configuration will be created
* in the shared aws configuration file (~/.aws/config). This is in contrary of simply invoking
* an `sts assume-role` command that creates a session with a fixed expiry date.
*
* Using a profile will delegate credential refreshing to the SDK/CLI.
* This is needed to support long running sessions that needs sessions that are longer than
* the session duration that can be configured with a `sts assume-role`.
*
* The application code will access to this profile in the `AWS_PROFILE` env variable.
*
* Only relevant if `refresh` is specified.
*
* @see https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html
*
* @default 'long-running-profile'
*/
profileName?: string;
/**
* Specify this if you have a long running execution that needs long running sessions.
* This will create a profile and use it to delegate credential refreshing to the SDK/CLI
*
* @default false
*/
refresh?: boolean;
}
/**
* A CodeBuild project that runs arbitrary scripts.
*
* The scripts to be run are specified by supplying a directory.
* All files in the directory are uploaded, then the script designated
* as the entry point is started.
*
* The script is executed in the directory where the build project's
* input is stored. The directory where the script files are stored
* is in the $SCRIPT_DIR environment variable.
*
* Supports both Windows and Linux computes.
*/
export declare class Shellable extends Construct {
private readonly props;
readonly project: cbuild.Project;
readonly role: iam.IRole;
/**
* CloudWatch alarm that will be triggered if this action fails.
*/
readonly alarm: cloudwatch.Alarm;
private readonly platform;
private readonly buildSpec;
private readonly outputArtifactName?;
constructor(parent: Construct, id: string, props: ShellableProps);
addToPipeline(stage: cpipeline.IStage, name: string, inputArtifact: cpipeline.Artifact, runOrder?: number): cpipeline_actions.CodeBuildAction;
/**
* The contract of `environmentSecrets` is that the values are complete Secret ARNs;
* however, the CodeBuild construct expects secret names as the inputs for environment variables.
* This method converts the environment secrets from ARNs to names.
*/
private convertEnvironmentSecretArnsToSecretNames;
}
/**
* Platform archetype
*/
export declare enum PlatformType {
Linux = "Linux",
Windows = "Windows"
}
/**
* The platform type to run the scripts on
*/
export declare abstract class ShellPlatform {
readonly buildImage: cbuild.IBuildImage;
/**
* Return a default Ubuntu Linux platform
*/
static get LinuxUbuntu(): ShellPlatform;
/**
* Return a default Windows platform
*/
static get Windows(): ShellPlatform;
constructor(buildImage: cbuild.IBuildImage);
/**
* Retrn commands to prepare the host for the shellable.
*/
abstract installCommands(): string[] | undefined;
/**
* Return commands to download the script bundle
*/
abstract prebuildCommands(assumeRole?: AssumeRole, useRegionalStsEndpoints?: boolean): string[];
/**
* Return commands to start the entrypoint script
*/
abstract buildCommands(entrypoint: string, args?: string[]): string[];
/**
* Type of platform
*/
abstract get platformType(): PlatformType;
}
/**
* A Linux Platform
*/
export declare class LinuxPlatform extends ShellPlatform {
readonly platformType = PlatformType.Linux;
installCommands(): string[] | undefined;
prebuildCommands(assumeRole?: AssumeRole, useRegionalStsEndpoints?: boolean): string[];
buildCommands(entrypoint: string, args?: string[]): string[];
}
/**
* A Windows Platform
*/
export declare class WindowsPlatform extends ShellPlatform {
readonly platformType = PlatformType.Windows;
installCommands(): string[] | undefined;
prebuildCommands(assumeRole?: AssumeRole, _useRegionalStsEndpoints?: boolean): string[];
buildCommands(entrypoint: string, args?: string[]): string[];
}