feat: new resource interfaces shared by both L1s and L2s

[otaviomacedo]

This PR introduces a new set of minimal L1 interfaces to address resources in the CDK APIs.

New interfaces

They are named like IBucketRef (and IInstanceRef, IKeyRef, etc), which is an interface similar to IBucket but lives at the L1 level instead of the L2 level. It allows "pointing to a bucket" in a typed way. The L1 CfnBucket implements IBucketRef, and the L2 IBucket extends IBucketRef. IBucketRef doesn't have any of the additional handwritten conveniences afforded by IBucket, but because it doesn't involve any handwritten code this it to be implemented by the L1 CfnBucket.

We've then gone through all APIs where an IBucket was expected, and if that call site didn't use any of the facilities exposed by IBucket we've replaced the type with IBucketRef.

The result is that in those APIs, it is now possible to transparently pass both L1 and L2 resources, instead of only L2 resources. This gives you the freedom of picking between L1s and L2s as your need dictate.

If you are implementing IBucket yourself

If you are writing classes that implement IBucket, you now have an additional implementation burden:

interface IBucketRef {
  /** This property is new */
  public readonly bucketRef: BucketReference;
}

You should copy this value from elsewhere, for example from CfnBucket or a Bucket you wrap:

export MyBucketClass implements IBucket {
  
  /** Add a getter for it */
  public get bucketRef(): BucketReference {
    return this.wrappedBucket.bucketRef;
  }
}

Future work

This work is the first step in a series of changes that will make it easier for L1 and L2 classes to interoperate, and to progressively add enhancements to L1s in a way that doesn't require implementing full L2s. The goal is to make CDK more expressive with less upfront work.

Experimental

This work is considered experimental, and it may change; we may still add { account; region } to to the BucketReference struct (which is why you should copy it an underlying object, and not try to construct one yourself).

We may also roll back this change entirely and remove the interfaces we introduced here, so don't start referencing IBucketRef in your own code just yet.

To limit the impact, these are introduced currently only for the following services: IAM, S3, EC2, KMS, CloudFront.

Feedback

If you have opinions on this change, don't hesitate to let us know via the issue tracker or via a Direct Message on Slack.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: b00f7bc
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[rix0rrr]

• I think we probably need to extend IResource rather than IConstruct.

• I wonder if ICfnAlias sends the wrong message. I was thinking IAliasRef might be nicer (but I'm open to better ideas)

[otaviomacedo]

I think we probably need to extend IResource rather than IConstruct.

But IResource extends IConstruct, and then we have the same problem.

I wonder if ICfnAlias sends the wrong message. I was thinking IAliasRef might be nicer (but I'm open to better ideas)

Not particularly attached to any name. I can change it to I[Resource]Ref, but it's going to be even harder to exclude these interfaces from the construct-interface-extends-iconstruct rule.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.