feat(ecr): allow fromLookup method to return dummy repository without error if target repository was not found

packages/@aws-cdk-testing/framework-integ/test/aws-ecr/test/integ.repository-lookup.js.snapshot/EcrRepoLookupStack.template.json

@@ -101,6 +101,23 @@
      ]
     ]
    }
+  },
+  "DummyRepoArn": {
+   "Value": {
+    "Fn::Join": [
+     "",
+     [
+      "arn:",
+      {
+       "Ref": "AWS::Partition"
+      },
+      ":ecr:us-east-1:123456789012:repository/DUMMY_ARN"
+     ]
+    ]
+   }
+  },
+  "IsDummy": {
+   "Value": "true"
   }
  },
  "Parameters": {

packages/@aws-cdk-testing/framework-integ/test/aws-ecr/test/integ.repository-lookup.ts

@@ -27,6 +27,14 @@ new CfnOutput(lookupStack, 'RepositoryUri', {
   value: lookupRepo.repositoryUri,
 });
 
+const dummyRepo = ecr.Repository.fromLookup(lookupStack, 'DummyRepo', {
+  repositoryArn: 'arn:aws:ecr:us-east-1:123456789012:repository/does-not-exist-repo',
+  mustExist: false,
+});
+
+new CfnOutput(lookupStack, 'DummyRepoArn', { value: dummyRepo.repositoryArn });
+new CfnOutput(lookupStack, 'IsDummy', { value: String(ecr.Repository.isLookupDummy(dummyRepo)) });
+
 new IntegTest(app, 'EcrRepoLookupTest', {
   enableLookups: true,
   stackUpdateWorkflow: false,

packages/aws-cdk-lib/aws-ecr/README.md

@@ -229,6 +229,23 @@ const repositoryFromLookup = ecr.Repository.fromLookup(this, 'ImportedRepoByLook
 });
 ```
 
+If the target repository is not found in your account when using `Repository.fromLookup()`, an error will be thrown.
+To prevent the error in the case, you can receive a dummy repository without the error
+by setting `mustExist` to `false`. The dummy repository has a `repositoryArn` of
+`arn:{partition}:ecr:us-east-1:123456789012:repository/DUMMY_ARN`. You can check if the
+repository is a dummy repository by using the `Repository.isLookupDummy()` method.
+
+```ts
+const dummy = ecr.Repository.fromLookup(this, 'ImportedRepoByLookup', {
+  repositoryArn: 'arn:aws:ecr:us-east-1:123456789012:repository/does-not-exist-repo',
+  mustExist: false,
+});
+
+if (ecr.Repository.isLookupDummy(dummy)) {
+  // alternative process
+}
+```
+
 ## CloudWatch event rules
 
 You can publish repository events to a CloudWatch event rule with `onEvent`:

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

@@ -23,6 +23,7 @@ import {
   Arn,
   ValidationError,
   UnscopedValidationError,
+  ArnComponents,
 } from '../../core';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
 import { AutoDeleteImagesProvider } from '../../custom-resource-handlers/dist/aws-ecr/auto-delete-images-provider.generated';
@@ -620,19 +621,43 @@ export interface RepositoryLookupOptions {
    * @default - Do not filter on repository ARN
    */
   readonly repositoryArn?: string;
+
+  /**
+   * Whether to throw an error if the repository was not found.
+   *
+   * If it is set to `false` and the repository was not found, a dummy
+   * repository with the arn 'arn:{partition}:ecr:us-east-1:123456789012:repository/DUMMY_ARN'
+   * will be returned. You can check if the repository is a dummy repository by using the
+   * `Repository.isLookupDummy()` method.
+   *
+   * @default true
+   */
+  readonly mustExist?: boolean;
 }
 
 export interface RepositoryAttributes {
   readonly repositoryName: string;
   readonly repositoryArn: string;
 }
 
+const dummyArnComponents: ArnComponents = {
+  service: 'ecr',
+  region: 'us-east-1',
+  account: '123456789012',
+  resource: 'repository',
+  resourceName: 'DUMMY_ARN',
+};
+
 /**
  * Define an ECR repository
  */
 export class Repository extends RepositoryBase {
   /**
    * Lookup an existing repository
+   *
+   * If you set `mustExist` to `false` in `options` and the repository was not found,
+   * this method will return a dummy repository with the arn 'arn:{partition}:ecr:us-east-1:123456789012:repository/DUMMY_ARN'.
+   * You can check if the repository is a dummy repository by using the `Repository.isLookupDummy()` method.
    */
   public static fromLookup(scope: Construct, id: string, options: RepositoryLookupOptions): IRepository {
     if (Token.isUnresolved(options.repositoryName) || Token.isUnresolved(options.repositoryArn)) {
@@ -659,15 +684,10 @@ export class Repository extends RepositoryBase {
       } as cxschema.CcApiContextQuery,
       dummyValue: [
         {
-          Arn: Stack.of(scope).formatArn({
-            service: 'ecr',
-            region: 'us-east-1',
-            account: '123456789012',
-            resource: 'repository',
-            resourceName: 'DUMMY_ARN',
-          }),
+          Arn: Stack.of(scope).formatArn(dummyArnComponents),
         },
       ],
+      mustExist: options.mustExist,
     }).value;
 
     const repository = response[0];
@@ -679,6 +699,17 @@ export class Repository extends RepositoryBase {
     });
   }
 
+  /**
+   * Checks if the repository returned by the `Repository.fromLookup()` method is a dummy repository,
+   * i.e., a repository that was not found.
+   *
+   * This method can only be used if the `mustExist` option is set to `false` in the `options`
+   * for the `Repository.fromLookup()` method.
+   */
+  public static isLookupDummy(repository: IRepository): boolean {
+    return repository.repositoryArn === Stack.of(repository).formatArn(dummyArnComponents);
+  }
+
   /**
    * Import a repository
    */