aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.d.ts

Version 2 of the AWS Cloud Development Kit library

import { Construct } from 'constructs';
import * as cb from '../../../aws-codebuild';
import * as cp from '../../../aws-codepipeline';
import * as ec2 from '../../../aws-ec2';
import * as iam from '../../../aws-iam';
import * as s3 from '../../../aws-s3';
import { Duration } from '../../../core';
import { IFileSetProducer } from '../blueprint';
import { DockerCredential } from '../docker-credentials';
import { PipelineBase } from '../main';
/**
 * Properties for a `CodePipeline`
 */
export interface CodePipelineProps {
    /**
     * The build step that produces the CDK Cloud Assembly
     *
     * The primary output of this step needs to be the `cdk.out` directory
     * generated by the `cdk synth` command.
     *
     * If you use a `ShellStep` here and you don't configure an output directory,
     * the output directory will automatically be assumed to be `cdk.out`.
     */
    readonly synth: IFileSetProducer;
    /**
     * The name of the CodePipeline pipeline
     *
     * @default - Automatically generated
     */
    readonly pipelineName?: string;
    /**
     * Create KMS keys for the artifact buckets, allowing cross-account deployments
     *
     * The artifact buckets have to be encrypted to support deploying CDK apps to
     * another account, so if you want to do that or want to have your artifact
     * buckets encrypted, be sure to set this value to `true`.
     *
     * Be aware there is a cost associated with maintaining the KMS keys.
     *
     * @default false
     */
    readonly crossAccountKeys?: boolean;
    /**
     * CDK CLI version to use in self-mutation and asset publishing steps
     *
     * If you want to lock the CDK CLI version used in the pipeline, by steps
     * that are automatically generated for you, specify the version here.
     *
     * We recommend you do not specify this value, as not specifying it always
     * uses the latest CLI version which is backwards compatible with old versions.
     *
     * If you do specify it, be aware that this version should always be equal to or higher than the
     * version of the CDK framework used by the CDK app, when the CDK commands are
     * run during your pipeline execution. When you change this version, the *next
     * time* the `SelfMutate` step runs it will still be using the CLI of the the
     * *previous* version that was in this property: it will only start using the
     * new version after `SelfMutate` completes successfully. That means that if
     * you want to update both framework and CLI version, you should update the
     * CLI version first, commit, push and deploy, and only then update the
     * framework version.
     *
     * @default - Latest version
     */
    readonly cliVersion?: string;
    /**
     * Whether the pipeline will update itself
     *
     * This needs to be set to `true` to allow the pipeline to reconfigure
     * itself when assets or stages are being added to it, and `true` is the
     * recommended setting.
     *
     * You can temporarily set this to `false` while you are iterating
     * on the pipeline itself and prefer to deploy changes using `cdk deploy`.
     *
     * @default true
     */
    readonly selfMutation?: boolean;
    /**
     * Enable Docker for the self-mutate step
     *
     * Set this to true if the pipeline itself uses Docker container assets
     * (for example, if you use `LinuxBuildImage.fromAsset()` as the build
     * image of a CodeBuild step in the pipeline).
     *
     * You do not need to set it if you build Docker image assets in the
     * application Stages and Stacks that are *deployed* by this pipeline.
     *
     * Configures privileged mode for the self-mutation CodeBuild action.
     *
     * If you are about to turn this on in an already-deployed Pipeline,
     * set the value to `true` first, commit and allow the pipeline to
     * self-update, and only then use the Docker asset in the pipeline.
     *
     * @default false
     */
    readonly dockerEnabledForSelfMutation?: boolean;
    /**
     * Enable Docker for the 'synth' step
     *
     * Set this to true if you are using file assets that require
     * "bundling" anywhere in your application (meaning an asset
     * compilation step will be run with the tools provided by
     * a Docker image), both for the Pipeline stack as well as the
     * application stacks.
     *
     * A common way to use bundling assets in your application is by
     * using the `aws-cdk-lib/aws-lambda-nodejs` library.
     *
     * Configures privileged mode for the synth CodeBuild action.
     *
     * If you are about to turn this on in an already-deployed Pipeline,
     * set the value to `true` first, commit and allow the pipeline to
     * self-update, and only then use the bundled asset.
     *
     * @default false
     */
    readonly dockerEnabledForSynth?: boolean;
    /**
     * Customize the CodeBuild projects created for this pipeline
     *
     * @default - All projects run non-privileged build, SMALL instance, LinuxBuildImage.STANDARD_7_0
     */
    readonly codeBuildDefaults?: CodeBuildOptions;
    /**
     * Additional customizations to apply to the synthesize CodeBuild projects
     *
     * @default - Only `codeBuildDefaults` are applied
     */
    readonly synthCodeBuildDefaults?: CodeBuildOptions;
    /**
     * Additional customizations to apply to the asset publishing CodeBuild projects
     *
     * @default - Only `codeBuildDefaults` are applied
     */
    readonly assetPublishingCodeBuildDefaults?: CodeBuildOptions;
    /**
     * Additional customizations to apply to the self mutation CodeBuild projects
     *
     * @default - Only `codeBuildDefaults` are applied
     */
    readonly selfMutationCodeBuildDefaults?: CodeBuildOptions;
    /**
     * Publish assets in multiple CodeBuild projects
     *
     * If set to false, use one Project per type to publish all assets.
     *
     * Publishing in parallel improves concurrency and may reduce publishing
     * latency, but may also increase overall provisioning time of the CodeBuild
     * projects.
     *
     * Experiment and see what value works best for you.
     *
     * @default true
     */
    readonly publishAssetsInParallel?: boolean;
    /**
     * A list of credentials used to authenticate to Docker registries.
     *
     * Specify any credentials necessary within the pipeline to build, synth, update, or publish assets.
     *
     * @default []
     */
    readonly dockerCredentials?: DockerCredential[];
    /**
     * An existing Pipeline to be reused and built upon.
     *
     * [disable-awslint:ref-via-interface]
     *
     * @default - a new underlying pipeline is created.
     */
    readonly codePipeline?: cp.Pipeline;
    /**
     * Reuse the same cross region support stack for all pipelines in the App.
     *
     * @default - true (Use the same support stack for all pipelines in App)
     */
    readonly reuseCrossRegionSupportStacks?: boolean;
    /**
     * The IAM role to be assumed by this Pipeline
     *
     * @default - A new role is created
     */
    readonly role?: iam.IRole;
    /**
     * Deploy every stack by creating a change set and executing it
     *
     * When enabled, creates a "Prepare" and "Execute" action for each stack. Disable
     * to deploy the stack in one pipeline action.
     *
     * @default true
     */
    readonly useChangeSets?: boolean;
    /**
     * Enable KMS key rotation for the generated KMS keys.
     *
     * By default KMS key rotation is disabled, but will add
     * additional costs when enabled.
     *
     * @default - false (key rotation is disabled)
     */
    readonly enableKeyRotation?: boolean;
    /**
     * An existing S3 Bucket to use for storing the pipeline's artifact.
     *
     * @default - A new S3 bucket will be created.
     */
    readonly artifactBucket?: s3.IBucket;
    /**
     * A map of region to S3 bucket name used for cross-region CodePipeline.
     * For every Action that you specify targeting a different region than the Pipeline itself,
     * if you don't provide an explicit Bucket for that region using this property,
     * the construct will automatically create a Stack containing an S3 Bucket in that region.
     * Passed directly through to the {@link cp.Pipeline}.
     *
     * @default - no cross region replication buckets.
     */
    readonly crossRegionReplicationBuckets?: {
        [region: string]: s3.IBucket;
    };
}
/**
 * Options for customizing a single CodeBuild project
 */
export interface CodeBuildOptions {
    /**
     * Partial build environment, will be combined with other build environments that apply
     *
     * @default - Non-privileged build, SMALL instance, LinuxBuildImage.STANDARD_7_0
     */
    readonly buildEnvironment?: cb.BuildEnvironment;
    /**
     * Policy statements to add to role
     *
     * @default - No policy statements added to CodeBuild Project Role
     */
    readonly rolePolicy?: iam.PolicyStatement[];
    /**
     * Partial buildspec, will be combined with other buildspecs that apply
     *
     * The BuildSpec must be available inline--it cannot reference a file
     * on disk.
     *
     * @default - No initial BuildSpec
     */
    readonly partialBuildSpec?: cb.BuildSpec;
    /**
     * Which security group(s) to associate with the project network interfaces.
     *
     * Only used if 'vpc' is supplied.
     *
     * @default - Security group will be automatically created.
     */
    readonly securityGroups?: ec2.ISecurityGroup[];
    /**
     * The VPC where to create the CodeBuild network interfaces in.
     *
     * @default - No VPC
     */
    readonly vpc?: ec2.IVpc;
    /**
     * Which subnets to use.
     *
     * Only used if 'vpc' is supplied.
     *
     * @default - All private subnets.
     */
    readonly subnetSelection?: ec2.SubnetSelection;
    /**
     * Caching strategy to use.
     *
     * @default - No cache
     */
    readonly cache?: cb.Cache;
    /**
     * The number of minutes after which AWS CodeBuild stops the build if it's
     * not complete. For valid values, see the timeoutInMinutes field in the AWS
     * CodeBuild User Guide.
     *
     * @default Duration.hours(1)
     */
    readonly timeout?: Duration;
    /**
     * ProjectFileSystemLocation objects for CodeBuild build projects.
     *
     * A ProjectFileSystemLocation object specifies the identifier, location, mountOptions, mountPoint,
     * and type of a file system created using Amazon Elastic File System.
     * Requires a vpc to be set and privileged to be set to true.
     *
     * @default - no file system locations
     */
    readonly fileSystemLocations?: cb.IFileSystemLocation[];
    /**
     * Information about logs for CodeBuild projects. A CodeBuild project can create logs in Amazon CloudWatch Logs, an S3 bucket, or both.
     *
     * @default - no log configuration is set
     */
    readonly logging?: cb.LoggingOptions;
}
/**
 * A CDK Pipeline that uses CodePipeline to deploy CDK apps
 *
 * This is a `Pipeline` with its `engine` property set to
 * `CodePipelineEngine`, and exists for nicer ergonomics for
 * users that don't need to switch out engines.
 */
export declare class CodePipeline extends PipelineBase {
    private readonly props;
    /**
     * Whether SelfMutation is enabled for this CDK Pipeline
     */
    readonly selfMutationEnabled: boolean;
    private _pipeline?;
    private artifacts;
    private _synthProject?;
    private _selfMutationProject?;
    private readonly useChangeSets;
    private _myCxAsmRoot?;
    private readonly dockerCredentials;
    private readonly cachedFnSub;
    private stackOutputs;
    /**
     * Asset roles shared for publishing
     */
    private readonly assetCodeBuildRoles;
    /**
     * This is set to the very first artifact produced in the pipeline
     */
    private _fallbackArtifact?;
    private _cloudAssemblyFileSet?;
    private readonly singlePublisherPerAssetType;
    private readonly cliVersion?;
    constructor(scope: Construct, id: string, props: CodePipelineProps);
    /**
     * The CodeBuild project that performs the Synth
     *
     * Only available after the pipeline has been built.
     */
    get synthProject(): cb.IProject;
    /**
     * The CodeBuild project that performs the SelfMutation
     *
     * Will throw an error if this is accessed before `buildPipeline()`
     * is called, or if selfMutation has been disabled.
     */
    get selfMutationProject(): cb.IProject;
    /**
     * The CodePipeline pipeline that deploys the CDK app
     *
     * Only available after the pipeline has been built.
     */
    get pipeline(): cp.Pipeline;
    protected doBuildPipeline(): void;
    private get myCxAsmRoot();
    /**
     * Scope for Assets-related resources.
     *
     * Purely exists for construct tree backwards compatibility with legacy pipelines
     */
    private get assetsScope();
    private pipelineStagesAndActionsFromGraph;
    /**
     * Do additional things after the action got added to the pipeline
     *
     * Some minor state manipulation of CodeBuild projects and pipeline
     * artifacts.
     */
    private postProcessNode;
    /**
     * Make an action from the given node and/or step
     */
    private actionFromNode;
    /**
     * Take a Step and turn it into a CodePipeline Action
     *
     * There are only 3 types of Steps we need to support:
     *
     * - Shell (generic)
     * - ManualApproval (generic)
     * - CodePipelineActionFactory (CodePipeline-specific)
     *
     * The rest is expressed in terms of these 3, or in terms of graph nodes
     * which are handled elsewhere.
     */
    private actionFromStep;
    private createChangeSetAction;
    private executeChangeSetAction;
    private executeDeploymentAction;
    private selfMutateAction;
    private publishAssetsAction;
    private nodeTypeFromNode;
    private codeBuildDefaultsFor;
    private roleFromPlaceholderArn;
    /**
     * Non-template config files for CodePipeline actions
     *
     * Currently only supports tags.
     */
    private writeTemplateConfiguration;
    /**
     * This role is used by both the CodePipeline build action and related CodeBuild project. Consolidating these two
     * roles into one, and re-using across all assets, saves significant size of the final synthesized output.
     * Modeled after the CodePipeline role and 'CodePipelineActionRole' roles.
     * Generates one role per asset type to separate file and Docker/image-based permissions.
     */
    private obtainAssetCodeBuildRole;
}