Merge branch 'master' of github.com:aws/aws-cdk into v2/forward-merge-20220413

Author: MrArnoldPalmer

packages/@aws-cdk-containers/ecs-service-extensions/README.md

@@ -9,6 +9,11 @@
 
 <!--END STABILITY BANNER-->
 
+> ⚠️ v2 of this library is now available! It is compatible with AWS CDK v2 and available in
+> multiple languages.
+> The source code for v2 lives [here](https://github.com/cdklabs/cdk-ecs-service-extensions).
+> To migrate from this library to v2, see the [Migration Guide](https://github.com/cdklabs/cdk-ecs-service-extensions/blob/main/MIGRATING.md).
+
 This library provides a high level, extensible pattern for constructing services
 deployed using Amazon ECS.
 

packages/@aws-cdk/aws-apprunner/README.md

@@ -65,7 +65,7 @@ new apprunner.Service(this, 'Service', {
   source: apprunner.Source.fromEcr({
     imageConfiguration: { port: 80 },
     repository: ecr.Repository.fromRepositoryName(this, 'NginxRepository', 'nginx'),
-    tag: 'latest',
+    tagOrDigest: 'latest',
   }),
 });
 ```

packages/@aws-cdk/aws-apprunner/lib/service.ts

@@ -219,8 +219,14 @@ export interface EcrProps {
   /**
    * Image tag.
    * @default - 'latest'
+   * @deprecated use `tagOrDigest`
    */
   readonly tag?: string;
+  /**
+   * Image tag or digest (digests must start with `sha256:`).
+   * @default - 'latest'
+   */
+  readonly tagOrDigest?: string;
 }
 
 /**
@@ -313,7 +319,9 @@ export class EcrSource extends Source {
     return {
       imageRepository: {
         imageConfiguration: this.props.imageConfiguration,
-        imageIdentifier: this.props.repository.repositoryUriForTag(this.props.tag || 'latest'),
+        imageIdentifier: this.props.repository.repositoryUriForTagOrDigest(
+          this.props.tagOrDigest || this.props.tag || 'latest',
+        ),
         imageRepositoryType: ImageRepositoryType.ECR,
       },
       ecrRepository: this.props.repository,

packages/@aws-cdk/aws-codebuild/lib/linux-arm-build-image.ts

@@ -42,12 +42,12 @@ export class LinuxArmBuildImage implements IBuildImage {
    * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-ecr.html
    *
    * @param repository The ECR repository
-   * @param tag Image tag (default "latest")
+   * @param tagOrDigest Image tag or digest (default "latest", digests must start with `sha256:`)
    * @returns An aarch64 Linux build image from an ECR repository.
    */
-  public static fromEcrRepository(repository: ecr.IRepository, tag: string = 'latest'): IBuildImage {
+  public static fromEcrRepository(repository: ecr.IRepository, tagOrDigest: string = 'latest'): IBuildImage {
     return new LinuxArmBuildImage({
-      imageId: repository.repositoryUriForTag(tag),
+      imageId: repository.repositoryUriForTagOrDigest(tagOrDigest),
       imagePullPrincipalType: ImagePullPrincipalType.SERVICE_ROLE,
       repository,
     });

packages/@aws-cdk/aws-codebuild/lib/project.ts

@@ -1785,11 +1785,11 @@ export class LinuxBuildImage implements IBuildImage {
    * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-ecr.html
    *
    * @param repository The ECR repository
-   * @param tag Image tag (default "latest")
+   * @param tagOrDigest Image tag or digest (default "latest", digests must start with `sha256:`)
    */
-  public static fromEcrRepository(repository: ecr.IRepository, tag: string = 'latest'): IBuildImage {
+  public static fromEcrRepository(repository: ecr.IRepository, tagOrDigest: string = 'latest'): IBuildImage {
     return new LinuxBuildImage({
-      imageId: repository.repositoryUriForTag(tag),
+      imageId: repository.repositoryUriForTagOrDigest(tagOrDigest),
       imagePullPrincipalType: ImagePullPrincipalType.SERVICE_ROLE,
       repository,
     });
@@ -1946,15 +1946,15 @@ export class WindowsBuildImage implements IBuildImage {
    * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-ecr.html
    *
    * @param repository The ECR repository
-   * @param tag Image tag (default "latest")
+   * @param tagOrDigest Image tag or digest (default "latest", digests must start with `sha256:`)
    */
   public static fromEcrRepository(
     repository: ecr.IRepository,
-    tag: string = 'latest',
+    tagOrDigest: string = 'latest',
     imageType: WindowsImageType = WindowsImageType.STANDARD): IBuildImage {
 
     return new WindowsBuildImage({
-      imageId: repository.repositoryUriForTag(tag),
+      imageId: repository.repositoryUriForTagOrDigest(tagOrDigest),
       imagePullPrincipalType: ImagePullPrincipalType.SERVICE_ROLE,
       imageType,
       repository,

packages/@aws-cdk/aws-codebuild/lib/source.ts

@@ -496,6 +496,18 @@ interface ThirdPartyGitSourceProps extends GitSourceProps {
    * @default every push and every Pull Request (create or update) triggers a build
    */
   readonly webhookFilters?: FilterGroup[];
+
+  /**
+   * The URL that the build will report back to the source provider.
+   * Can use built-in CodeBuild variables, like $AWS_REGION.
+   *
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/create-project-cli.html#cli.source.buildstatusconfig.targeturl
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
+   *
+   * @example "$CODEBUILD_PUBLIC_BUILD_URL"
+   * @default - link to the AWS Console for CodeBuild to a particular build execution
+   */
+  readonly buildStatusUrl?: string;
 }
 
 /**
@@ -507,6 +519,7 @@ abstract class ThirdPartyGitSource extends GitSource {
   private readonly reportBuildStatus: boolean;
   private readonly webhook?: boolean;
   private readonly webhookTriggersBatchBuild?: boolean;
+  protected readonly buildStatusUrl?: string;
 
   protected constructor(props: ThirdPartyGitSourceProps) {
     super(props);
@@ -515,6 +528,7 @@ abstract class ThirdPartyGitSource extends GitSource {
     this.reportBuildStatus = props.reportBuildStatus ?? true;
     this.webhookFilters = props.webhookFilters || [];
     this.webhookTriggersBatchBuild = props.webhookTriggersBatchBuild;
+    this.buildStatusUrl = props.buildStatusUrl;
   }
 
   public bind(_scope: Construct, project: IProject): SourceConfig {
@@ -633,10 +647,53 @@ class S3Source extends Source {
   }
 }
 
+/**
+ * Common properties between {@link GitHubSource} and {@link GitHubEnterpriseSource}.
+ */
+interface CommonGithubSourceProps extends ThirdPartyGitSourceProps {
+  /**
+   * This parameter is used for the `context` parameter in the GitHub commit status.
+   * Can use built-in CodeBuild variables, like $AWS_REGION.
+   *
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/create-project-cli.html#cli.source.buildstatusconfig.context
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
+   *
+   * @example "My build #$CODEBUILD_BUILD_NUMBER"
+   * @default "AWS CodeBuild $AWS_REGION ($PROJECT_NAME)"
+   */
+  readonly buildStatusContext?: string
+}
+
+abstract class CommonGithubSource extends ThirdPartyGitSource {
+  private readonly buildStatusContext?: string;
+
+  constructor(props: CommonGithubSourceProps) {
+    super(props);
+    this.buildStatusContext = props.buildStatusContext;
+  }
+
+  public bind(scope: CoreConstruct, project: IProject): SourceConfig {
+    const superConfig = super.bind(scope, project);
+    return {
+      sourceProperty: {
+        ...superConfig.sourceProperty,
+        buildStatusConfig: this.buildStatusContext !== undefined || this.buildStatusUrl !== undefined
+          ? {
+            context: this.buildStatusContext,
+            targetUrl: this.buildStatusUrl,
+          }
+          : undefined,
+      },
+      sourceVersion: superConfig.sourceVersion,
+      buildTriggers: superConfig.buildTriggers,
+    };
+  }
+}
+
 /**
  * Construction properties for {@link GitHubSource} and {@link GitHubEnterpriseSource}.
  */
-export interface GitHubSourceProps extends ThirdPartyGitSourceProps {
+export interface GitHubSourceProps extends CommonGithubSourceProps {
   /**
    * The GitHub account/user that owns the repo.
    *
@@ -655,7 +712,7 @@ export interface GitHubSourceProps extends ThirdPartyGitSourceProps {
 /**
  * GitHub Source definition for a CodeBuild project.
  */
-class GitHubSource extends ThirdPartyGitSource {
+class GitHubSource extends CommonGithubSource {
   public readonly type = GITHUB_SOURCE_TYPE;
   private readonly httpsCloneUrl: string;
 
@@ -680,7 +737,7 @@ class GitHubSource extends ThirdPartyGitSource {
 /**
  * Construction properties for {@link GitHubEnterpriseSource}.
  */
-export interface GitHubEnterpriseSourceProps extends ThirdPartyGitSourceProps {
+export interface GitHubEnterpriseSourceProps extends CommonGithubSourceProps {
   /**
    * The HTTPS URL of the repository in your GitHub Enterprise installation.
    */
@@ -697,7 +754,7 @@ export interface GitHubEnterpriseSourceProps extends ThirdPartyGitSourceProps {
 /**
  * GitHub Enterprise Source definition for a CodeBuild project.
  */
-class GitHubEnterpriseSource extends ThirdPartyGitSource {
+class GitHubEnterpriseSource extends CommonGithubSource {
   public readonly type = GITHUB_ENTERPRISE_SOURCE_TYPE;
   private readonly httpsCloneUrl: string;
   private readonly ignoreSslErrors?: boolean;
@@ -765,6 +822,18 @@ export interface BitBucketSourceProps extends ThirdPartyGitSourceProps {
    * @example 'aws-cdk'
    */
   readonly repo: string;
+
+  /**
+   * This parameter is used for the `name` parameter in the Bitbucket commit status.
+   * Can use built-in CodeBuild variables, like $AWS_REGION.
+   *
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/create-project-cli.html#cli.source.buildstatusconfig.context
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
+   *
+   * @example "My build #$CODEBUILD_BUILD_NUMBER"
+   * @default "AWS CodeBuild $AWS_REGION ($PROJECT_NAME)"
+   */
+  readonly buildStatusName?: string;
 }
 
 /**
@@ -773,10 +842,12 @@ export interface BitBucketSourceProps extends ThirdPartyGitSourceProps {
 class BitBucketSource extends ThirdPartyGitSource {
   public readonly type = BITBUCKET_SOURCE_TYPE;
   private readonly httpsCloneUrl: any;
+  private readonly buildStatusName?: string;
 
   constructor(props: BitBucketSourceProps) {
     super(props);
     this.httpsCloneUrl = `https://bitbucket.org/${props.owner}/${props.repo}.git`;
+    this.buildStatusName = props.buildStatusName;
   }
 
   public bind(_scope: Construct, _project: IProject): SourceConfig {
@@ -790,6 +861,12 @@ class BitBucketSource extends ThirdPartyGitSource {
       sourceProperty: {
         ...superConfig.sourceProperty,
         location: this.httpsCloneUrl,
+        buildStatusConfig: this.buildStatusName !== undefined || this.buildStatusUrl !== undefined
+          ? {
+            context: this.buildStatusName,
+            targetUrl: this.buildStatusUrl,
+          }
+          : undefined,
       },
       sourceVersion: superConfig.sourceVersion,
       buildTriggers: superConfig.buildTriggers,

packages/@aws-cdk/aws-codebuild/test/codebuild.test.ts

@@ -1028,6 +1028,78 @@ describe('secondary sources', () => {
   });
 });
 
+describe('sources with customised build status configuration', () => {
+  test('GitHub', () => {
+    const context = 'My custom CodeBuild worker!';
+    const stack = new cdk.Stack();
+    const source = codebuild.Source.gitHub({
+      owner: 'awslabs',
+      repo: 'aws-cdk',
+      buildStatusContext: context,
+    });
+
+    new codebuild.Project(stack, 'MyProject', { source });
+    Template.fromStack(stack).findParameters('AWS::CodeBuild::Project', {
+      Source: {
+        buildStatusConfig: {
+          context: context,
+        },
+      },
+    });
+  });
+
+  test('GitHub Enterprise', () => {
+    const context = 'My custom CodeBuild worker!';
+    const stack = new cdk.Stack();
+    const source = codebuild.Source.gitHubEnterprise({
+      httpsCloneUrl: 'url',
+      buildStatusContext: context,
+    });
+    new codebuild.Project(stack, 'MyProject', { source });
+    Template.fromStack(stack).findParameters('AWS::CodeBuild::Project', {
+      Source: {
+        buildStatusConfig: {
+          context: context,
+        },
+      },
+    });
+  });
+
+  test('BitBucket', () => {
+    const context = 'My custom CodeBuild worker!';
+    const stack = new cdk.Stack();
+    const source = codebuild.Source.bitBucket({ owner: 'awslabs', repo: 'aws-cdk' });
+    new codebuild.Project(stack, 'MyProject', { source });
+    Template.fromStack(stack).findParameters('AWS::CodeBuild::Project', {
+      Source: {
+        buildStatusConfig: {
+          context: context,
+        },
+      },
+    });
+  });
+});
+
+describe('sources with customised build status configuration', () => {
+  test('GitHub with targetUrl', () => {
+    const targetUrl = 'https://example.com';
+    const stack = new cdk.Stack();
+    const source = codebuild.Source.gitHub({
+      owner: 'awslabs',
+      repo: 'aws-cdk',
+      buildStatusUrl: targetUrl,
+    });
+    new codebuild.Project(stack, 'MyProject', { source });
+    Template.fromStack(stack).findParameters('AWS::CodeBuild::Project', {
+      Source: {
+        buildStatusConfig: {
+          targetUrl: targetUrl,
+        },
+      },
+    });
+  });
+});
+
 describe('secondary source versions', () => {
   test('allow secondary source versions', () => {
     const stack = new cdk.Stack();

packages/@aws-cdk/aws-ecr/lib/repository.ts

@@ -42,14 +42,24 @@ export interface IRepository extends IResource {
   repositoryUriForTag(tag?: string): string;
 
   /**
-   * Returns the URI of the repository for a certain tag. Can be used in `docker push/pull`.
+   * Returns the URI of the repository for a certain digest. Can be used in `docker push/pull`.
    *
    *    ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPOSITORY[@DIGEST]
    *
    * @param digest Image digest to use (tools usually default to the image with the "latest" tag if omitted)
    */
   repositoryUriForDigest(digest?: string): string;
 
+  /**
+   * Returns the URI of the repository for a certain tag or digest, inferring based on the syntax of the tag. Can be used in `docker push/pull`.
+   *
+   *    ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPOSITORY[:TAG]
+   *    ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPOSITORY[@DIGEST]
+   *
+   * @param tagOrDigest Image tag or digest to use (tools usually default to the image with the "latest" tag if omitted)
+   */
+  repositoryUriForTagOrDigest(tagOrDigest?: string): string;
+
   /**
    * Add a policy statement to the repository's resource policy
    */
@@ -162,6 +172,22 @@ export abstract class RepositoryBase extends Resource implements IRepository {
     return this.repositoryUriWithSuffix(digestSuffix);
   }
 
+  /**
+   * Returns the URL of the repository. Can be used in `docker push/pull`.
+   *
+   *    ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPOSITORY[:TAG]
+   *    ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPOSITORY[@DIGEST]
+   *
+   * @param tagOrDigest Optional image tag or digest (digests must start with `sha256:`)
+   */
+  public repositoryUriForTagOrDigest(tagOrDigest?: string): string {
+    if (tagOrDigest?.startsWith('sha256:')) {
+      return this.repositoryUriForDigest(tagOrDigest);
+    } else {
+      return this.repositoryUriForTag(tagOrDigest);
+    }
+  }
+
   /**
    * Returns the repository URI, with an appended suffix, if provided.
    * @param suffix An image tag or an image digest.

packages/@aws-cdk/aws-ecs/README.md

@@ -393,8 +393,8 @@ obtained from either DockerHub or from ECR repositories, built directly from a l
 
 - `ecs.ContainerImage.fromRegistry(imageName)`: use a public image.
 - `ecs.ContainerImage.fromRegistry(imageName, { credentials: mySecret })`: use a private image that requires credentials.
-- `ecs.ContainerImage.fromEcrRepository(repo, tag)`: use the given ECR repository as the image
-  to start. If no tag is provided, "latest" is assumed.
+- `ecs.ContainerImage.fromEcrRepository(repo, tagOrDigest)`: use the given ECR repository as the image
+  to start. If no tag or digest is provided, "latest" is assumed.
 - `ecs.ContainerImage.fromAsset('./image')`: build and upload an
   image directly from a `Dockerfile` in your source directory.
 - `ecs.ContainerImage.fromDockerImageAsset(asset)`: uses an existing