feat(core): addToRolePolicy() for custom resource provider (#20449)

Since we only get a singleton we need a `addToRolePolicy()` method to
add statements when the singleton is used for multiple custom resources.


----

### All Submissions:

* [x] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/master/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/master/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/master/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

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

Author: jogold

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

@@ -626,6 +626,23 @@ const roleArn = provider.roleArn;
 
 This role ARN can then be used in resource-based IAM policies.
 
+To add IAM policy statements to this role, use `addToRolePolicy()`:
+
+```ts
+const provider = CustomResourceProvider.getOrCreateProvider(this, 'Custom::MyCustomResourceType', {
+  codeDirectory: `${__dirname}/my-handler`,
+  runtime: CustomResourceProviderRuntime.NODEJS_12_X,
+});
+provider.addToRolePolicy({
+  Effect: 'Allow',
+  Action: 's3:GetObject',
+  Resource: '*',
+})
+```
+
+Note that `addToRolePolicy()` uses direct IAM JSON policy blobs, *not* a
+`iam.PolicyStatement` object like you will see in the rest of the CDK.
+
 #### The Custom Resource Provider Framework
 
 The [`@aws-cdk/custom-resources`] module includes an advanced framework for

packages/@aws-cdk/core/lib/custom-resource-provider/custom-resource-provider.ts

@@ -6,6 +6,7 @@ import { AssetStaging } from '../asset-staging';
 import { FileAssetPackaging } from '../assets';
 import { CfnResource } from '../cfn-resource';
 import { Duration } from '../duration';
+import { Lazy } from '../lazy';
 import { Size } from '../size';
 import { Stack } from '../stack';
 import { Token } from '../token';
@@ -187,6 +188,8 @@ export class CustomResourceProvider extends Construct {
    */
   public readonly roleArn: string;
 
+  private policyStatements?: any[];
+
   protected constructor(scope: Construct, id: string, props: CustomResourceProviderProps) {
     super(scope, id);
 
@@ -212,15 +215,11 @@ export class CustomResourceProvider extends Construct {
       packaging: FileAssetPackaging.ZIP_DIRECTORY,
     });
 
-    const policies = !props.policyStatements ? undefined : [
-      {
-        PolicyName: 'Inline',
-        PolicyDocument: {
-          Version: '2012-10-17',
-          Statement: props.policyStatements,
-        },
-      },
-    ];
+    if (props.policyStatements) {
+      for (const statement of props.policyStatements) {
+        this.addToRolePolicy(statement);
+      }
+    }
 
     const role = new CfnResource(this, 'Role', {
       type: 'AWS::IAM::Role',
@@ -232,7 +231,7 @@ export class CustomResourceProvider extends Construct {
         ManagedPolicyArns: [
           { 'Fn::Sub': 'arn:${AWS::Partition}:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole' },
         ],
-        Policies: policies,
+        Policies: Lazy.any({ produce: () => this.renderPolicies() }),
       },
     });
     this.roleArn = Token.asString(role.getAtt('Arn'));
@@ -267,6 +266,46 @@ export class CustomResourceProvider extends Construct {
     this.serviceToken = Token.asString(handler.getAtt('Arn'));
   }
 
+  /**
+   * Add an IAM policy statement to the inline policy of the
+   * provider's lambda function's role.
+   *
+   * **Please note**: this is a direct IAM JSON policy blob, *not* a `iam.PolicyStatement`
+   * object like you will see in the rest of the CDK.
+   *
+   *
+   * @example
+   * declare const myProvider: CustomResourceProvider;
+   *
+   * myProvider.addToRolePolicy({
+   *   Effect: 'Allow',
+   *   Action: 's3:GetObject',
+   *   Resources: '*',
+   * });
+   */
+  public addToRolePolicy(statement: any): void {
+    if (!this.policyStatements) {
+      this.policyStatements = [];
+    }
+    this.policyStatements.push(statement);
+  }
+
+  private renderPolicies() {
+    if (!this.policyStatements) {
+      return undefined;
+    }
+
+    const policies = [{
+      PolicyName: 'Inline',
+      PolicyDocument: {
+        Version: '2012-10-17',
+        Statement: this.policyStatements,
+      },
+    }];
+
+    return policies;
+  }
+
   private renderEnvironmentVariables(env?: { [key: string]: string }) {
     if (!env || Object.keys(env).length === 0) {
       return undefined;

packages/@aws-cdk/core/test/custom-resource-provider/custom-resource-provider.test.ts

@@ -210,6 +210,33 @@ describe('custom resource provider', () => {
 
   });
 
+  test('addToRolePolicy() can be used to add statements to the inline policy', () => {
+    // GIVEN
+    const stack = new Stack();
+
+    // WHEN
+    const provider = CustomResourceProvider.getOrCreateProvider(stack, 'Custom:MyResourceType', {
+      codeDirectory: TEST_HANDLER,
+      runtime: CustomResourceProviderRuntime.NODEJS_12_X,
+      policyStatements: [
+        { statement1: 123 },
+        { statement2: { foo: 111 } },
+      ],
+    });
+    provider.addToRolePolicy({ statement3: 456 });
+
+    // THEN
+    const template = toCloudFormation(stack);
+    const role = template.Resources.CustomMyResourceTypeCustomResourceProviderRoleBD5E655F;
+    expect(role.Properties.Policies).toEqual([{
+      PolicyName: 'Inline',
+      PolicyDocument: {
+        Version: '2012-10-17',
+        Statement: [{ statement1: 123 }, { statement2: { foo: 111 } }, { statement3: 456 }],
+      },
+    }]);
+  });
+
   test('memorySize, timeout and description', () => {
     // GIVEN
     const stack = new Stack();

packages/aws-cdk-lib/README.md

@@ -657,6 +657,23 @@ const roleArn = provider.roleArn;
 
 This role ARN can then be used in resource-based IAM policies.
 
+To add IAM policy statements to this role, use `addToRolePolicy()`:
+
+```ts
+const provider = CustomResourceProvider.getOrCreateProvider(this, 'Custom::MyCustomResourceType', {
+  codeDirectory: `${__dirname}/my-handler`,
+  runtime: CustomResourceProviderRuntime.NODEJS_12_X,
+});
+provider.addToRolePolicy({
+  Effect: 'Allow',
+  Action: 's3:GetObject',
+  Resource: '*',
+})
+```
+
+Note that `addToRolePolicy()` uses direct IAM JSON policy blobs, *not* a
+`iam.PolicyStatement` object like you will see in the rest of the CDK.
+
 #### The Custom Resource Provider Framework
 
 The [`@aws-cdk/custom-resources`] module includes an advanced framework for