feat(codepipeline-actions): support commands action

packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-commands.ts

@@ -0,0 +1,124 @@
+import * as codepipeline from 'aws-cdk-lib/aws-codepipeline';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as cdk from 'aws-cdk-lib';
+import { Duration } from 'aws-cdk-lib';
+import { IntegTest, ExpectedResult, Match } from '@aws-cdk/integ-tests-alpha';
+import * as cpactions from 'aws-cdk-lib/aws-codepipeline-actions';
+import { Key } from 'aws-cdk-lib/aws-kms';
+import * as path from 'path';
+import { BucketDeployment, Source } from 'aws-cdk-lib/aws-s3-deployment';
+
+const app = new cdk.App();
+
+const stack = new cdk.Stack(app, 'aws-cdk-codepipeline-commands');
+
+const sourceBucketKey = new Key(stack, 'SourceBucketKey', {
+  description: 'SourceBucketKey',
+});
+const bucket = new s3.Bucket(stack, 'SourceBucket', {
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  autoDeleteObjects: true,
+  versioned: true,
+  encryptionKey: sourceBucketKey,
+});
+
+// To start the pipeline
+const bucketDeployment = new BucketDeployment(stack, 'BucketDeployment', {
+  sources: [Source.asset(path.join(__dirname, 'assets', 'nodejs.zip'))],
+  destinationBucket: bucket,
+  extract: false,
+});
+const zipKey = cdk.Fn.select(0, bucketDeployment.objectKeys);
+
+const sourceOutput = new codepipeline.Artifact('SourceArtifact');
+const sourceAction = new cpactions.S3SourceAction({
+  actionName: 'Source',
+  output: sourceOutput,
+  bucket,
+  bucketKey: zipKey,
+});
+
+const commandsOutput = new codepipeline.Artifact('CommandsArtifact', ['my-dir/**/*']);
+const commandsAction = new cpactions.CommandsAction({
+  actionName: 'Commands',
+  commands: [
+    'pwd',
+    'ls -la',
+    'mkdir -p my-dir',
+    'echo "HelloWorld" > my-dir/file.txt',
+    'export MY_OUTPUT=my-key',
+    'touch ignored.txt',
+  ],
+  input: sourceOutput,
+  output: commandsOutput,
+  outputVariables: ['MY_OUTPUT', 'CODEBUILD_BUILD_ID', 'AWS_DEFAULT_REGION'],
+});
+
+const deployBucket = new s3.Bucket(stack, 'DeployBucket', {
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  autoDeleteObjects: true,
+});
+const deployAction = new cpactions.S3DeployAction({
+  actionName: 'DeployAction',
+  extract: true,
+  input: commandsOutput,
+  bucket: deployBucket,
+  objectKey: commandsAction.variable('MY_OUTPUT'),
+});
+
+const pipelineBucketKey = new Key(stack, 'PipelineBucketKey', {
+  description: 'PipelineBucketKey',
+});
+const pipelineBucket = new s3.Bucket(stack, 'PipelineBucket', {
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  autoDeleteObjects: true,
+  encryptionKey: pipelineBucketKey,
+});
+const pipeline = new codepipeline.Pipeline(stack, 'Pipeline', {
+  artifactBucket: pipelineBucket,
+  stages: [
+    {
+      stageName: 'Source',
+      actions: [sourceAction],
+    },
+    {
+      stageName: 'Compute',
+      actions: [commandsAction],
+    },
+    {
+      stageName: 'Deploy',
+      actions: [deployAction],
+    },
+  ],
+});
+
+const integ = new IntegTest(app, 'aws-cdk-codepipeline-commands-test', {
+  testCases: [stack],
+  diffAssets: true,
+});
+
+const startPipelineCall = integ.assertions.awsApiCall('CodePipeline', 'startPipelineExecution', {
+  name: pipeline.pipelineName,
+});
+
+const getObjectCall = integ.assertions.awsApiCall('S3', 'getObject', {
+  Bucket: deployBucket.bucketName,
+  Key: 'my-key/my-dir/file.txt',
+});
+
+startPipelineCall.next(
+  integ.assertions.awsApiCall('CodePipeline', 'getPipelineState', {
+    name: pipeline.pipelineName,
+  }).expect(ExpectedResult.objectLike({
+    stageStates: Match.arrayWith([
+      Match.objectLike({
+        stageName: 'Deploy',
+        latestExecution: Match.objectLike({
+          status: 'Succeeded',
+        }),
+      }),
+    ]),
+  })).waitForAssertions({
+    totalTimeout: Duration.minutes(5),
+  }).next(getObjectCall),
+);

packages/aws-cdk-lib/aws-codepipeline-actions/README.md

@@ -1257,3 +1257,104 @@ pipeline.addStage({
 
 See [the AWS documentation](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-StepFunctions.html)
 for information on Action structure reference.
+
+## Compute
+
+### Commands
+
+The Commands action allows you to run shell commands in a virtual compute instance. When you run the action, commands
+specified in the action configuration are run in a separate container. All artifacts that are specified as input
+artifacts to a CodeBuild action are available inside of the container running the commands. This action allows you
+to specify commands without first creating a CodeBuild project.
+
+```ts
+// Source action
+const bucket = new s3.Bucket(this, 'SourceBucket', {
+  versioned: true,
+});
+const sourceArtifact = new codepipeline.Artifact('SourceArtifact');
+const sourceAction = new codepipeline_actions.S3SourceAction({
+  actionName: 'Source',
+  output: sourceArtifact,
+  bucket,
+  bucketKey: 'my.zip',
+});
+
+// Commands action
+const outputArtifact = new codepipeline.Artifact('OutputArtifact');
+const commandsAction = new codepipeline_actions.CommandsAction({
+  actionName: 'Commands',
+  commands: [
+    'echo "some commands"',
+  ],
+  input: sourceArtifact,
+  output: outputArtifact,
+});
+
+const pipeline = new codepipeline.Pipeline(this, 'Pipeline', {
+  stages: [
+    {
+      stageName: 'Source',
+      actions: [sourceAction],
+    },
+    {
+      stageName: 'Commands',
+      actions: [commandsAction],
+    },
+  ],
+});
+```
+
+If you want to filter the files to be included in the output artifact, you can specify their paths as the second
+argument to `Artifact`.
+
+```ts
+declare const sourceArtifact: codepipeline.Artifact;
+
+// filter files to be included in the output artifact
+const outputArtifact = new codepipeline.Artifact('OutputArtifact', ['my-dir/**/*']);
+const commandsAction = new codepipeline_actions.CommandsAction({
+  actionName: 'Commands',
+  commands: [
+    'mkdir -p my-dir',
+    'echo "HelloWorld" > my-dir/file.txt',
+  ],
+  input: sourceArtifact,
+  output: outputArtifact,
+});
+```
+
+You can also specify the `outputVariables` property in the `CommandsAction` to emit environment variables that can be used
+in subsequent actions. The variables are those defined in your shell commands or exported as defaults by the CodeBuild service.
+For a reference of CodeBuild environment variables, see
+[Environment variables in build environments](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html)
+in the CodeBuild User Guide.
+
+To use the output variables in a subsequent action, you can use the `variable` method on the action:
+
+```ts
+declare const sourceArtifact: codepipeline.Artifact;
+declare const outputArtifact: codepipeline.Artifact;
+
+const commandsAction = new codepipeline_actions.CommandsAction({
+  actionName: 'Commands',
+  commands: [
+    'export MY_OUTPUT=my-key',
+  ],
+  input: sourceArtifact,
+  output: outputArtifact,
+  outputVariables: ['MY_OUTPUT', 'CODEBUILD_BUILD_ID'], // CODEBUILD_BUILD_ID is a variable defined by CodeBuild
+});
+
+// Deploy action
+const deployAction = new codepipeline_actions.S3DeployAction({
+  actionName: 'DeployAction',
+  extract: true,
+  input: outputArtifact,
+  bucket: new s3.Bucket(this, 'DeployBucket'),
+  objectKey: commandsAction.variable('MY_OUTPUT'), // the variable emitted by the Commands action
+});
+```
+
+See [the AWS documentation](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-Commands.html)
+for more details about using Commands action in CodePipeline.

packages/aws-cdk-lib/aws-codepipeline-actions/lib/commands/commands-action.ts

@@ -0,0 +1,138 @@
+import { Construct } from 'constructs';
+import * as codepipeline from '../../../aws-codepipeline';
+import * as iam from '../../../aws-iam';
+import * as cdk from '../../../core';
+import { Action } from '../action';
+
+/**
+ * Construction properties of the `CommandsAction`.
+ */
+export interface CommandsActionProps extends codepipeline.CommonAwsActionProps {
+  /**
+   * The source to use as input for this action.
+   */
+  readonly input: codepipeline.Artifact;
+
+  /**
+   * The list of additional input artifacts for this action.
+   *
+   * @default - no extra inputs
+   */
+  readonly extraInputs?: codepipeline.Artifact[];
+
+  /**
+   * The output artifact for this action.
+   *
+   * You can filter files that you want to export as the output artifact for the action.
+   *
+   * @example
+   * new codepipeline.Artifact('CommandsArtifact', ['my-dir/**']);
+   *
+   * @default - no output artifact
+   */
+  readonly output?: codepipeline.Artifact;
+
+  /**
+   * The names of the variables in your environment that you want to export.
+   *
+   * These variables can be referenced in other actions by using the `variable` method
+   * of this class.
+   *
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
+   * @default - No output variables are exported
+   */
+  readonly outputVariables?: string[];
+
+  /**
+   * Shell commands for the Commands action to run.
+   *
+   * All formats are supported except multi-line formats.
+   *
+   * The length of the commands array must be between 1 and 50.
+   */
+  readonly commands: string[];
+}
+
+/**
+ * CodePipeline compute action that uses AWS Commands.
+ */
+export class CommandsAction extends Action {
+  private readonly outputVariables: string[];
+  constructor(props: CommandsActionProps) {
+    super({
+      ...props,
+      category: codepipeline.ActionCategory.COMPUTE,
+      provider: 'Commands',
+      artifactBounds: { minInputs: 1, maxInputs: 10, minOutputs: 0, maxOutputs: 1 },
+      inputs: [props.input, ...props.extraInputs || []],
+      outputs: props.output ? [props.output] : [],
+      commands: props.commands,
+      outputVariables: props.outputVariables,
+    });
+
+    if (props.commands.length < 1 || props.commands.length > 50) {
+      throw new Error(`The length of the commands array must be between 1 and 50, got: ${props.commands.length}`);
+    }
+
+    if (props.outputVariables !== undefined && (props.outputVariables.length < 1 || props.outputVariables.length > 15)) {
+      throw new Error(`The length of the outputVariables array must be between 1 and 15, got: ${props.outputVariables.length}`);
+    }
+
+    this.outputVariables = props.outputVariables || [];
+  }
+
+  /**
+   * Reference a CodePipeline variable exported in the Commands action.
+   *
+   * @param variableName the name of the variable exported by `outputVariables`
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
+   */
+  public variable(variableName: string): string {
+    if (!this.outputVariables.includes(variableName)) {
+      throw new Error(`Variable '${variableName}' is not exported by \`outputVariables\`, exported variables: ${this.outputVariables.join(', ')}`);
+    }
+    return this.variableExpression(variableName);
+  }
+
+  protected bound(scope: Construct, stage: codepipeline.IStage, options: codepipeline.ActionBindOptions):
+  codepipeline.ActionConfig {
+    const logGroupArn = cdk.Stack.of(scope).formatArn({
+      service: 'logs',
+      resource: 'log-group',
+      resourceName: `/aws/codepipeline/${stage.pipeline.pipelineName}`,
+      arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+    });
+    const logGroupArnWithWildcard = `${logGroupArn}:*`;
+
+    // grant the Pipeline role the required permissions to put the logs in the log group
+    // see: https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-Commands.html#action-reference-Commands-policy
+    options.role.addToPrincipalPolicy(new iam.PolicyStatement({
+      resources: [logGroupArn, logGroupArnWithWildcard],
+      actions: [
+        'logs:CreateLogGroup',
+        'logs:CreateLogStream',
+        'logs:PutLogEvents',
+      ],
+    }));
+
+    // grant the Pipeline role the required permissions to view the logs in the Commands action on the CodePipeline console
+    // see: https://docs.aws.amazon.com/codepipeline/latest/userguide/security-iam-permissions-console-logs.html
+    options.role.addToPrincipalPolicy(new iam.PolicyStatement({
+      resources: [logGroupArnWithWildcard],
+      actions: [
+        'logs:GetLogEvents',
+      ],
+    }));
+
+    // allow the Role access to the Bucket, if there are any inputs/outputs
+    if ((this.actionProperties.inputs ?? []).length > 0) {
+      options.bucket.grantRead(options.role);
+    }
+    if ((this.actionProperties.outputs ?? []).length > 0) {
+      options.bucket.grantWrite(options.role);
+    }
+
+    // `CommandsAction` does not need the `configuration` in the `ActionConfig`.
+    return {};
+  }
+}

packages/aws-cdk-lib/aws-codepipeline-actions/lib/index.ts

@@ -6,6 +6,7 @@ export * from './codebuild/build-action';
 export * from './codecommit/source-action';
 export * from './codedeploy/ecs-deploy-action';
 export * from './codedeploy/server-deploy-action';
+export * from './commands/commands-action';
 export * from './ecr/source-action';
 export * from './ecs/deploy-action';
 export * from './elastic-beanstalk/deploy-action';