docs(aws-custom-resource): explain deviating policy names (#19458)

Some API calls do not require the exact corresponding IAM permissions.

We don't have a mapping to do this properly, so we have to punt to
the user (and have to make them aware of this).

Relates to #19355.


----

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

Author: rix0rrr

packages/@aws-cdk/custom-resources/README.md

@@ -354,7 +354,7 @@ This sample demonstrates the following concepts:
 
 ### Customizing Provider Function name
 
-In multi-account environments or when the custom resource may be re-utilized across several 
+In multi-account environments or when the custom resource may be re-utilized across several
 stacks it may be useful to manually set a name for the Provider Function Lambda and therefore
 have a predefined service token ARN.
 
@@ -401,9 +401,19 @@ the `installLatestAwsSdk` prop to `false`.
 You must provide the `policy` property defining the IAM Policy that will be applied to the API calls.
 The library provides two factory methods to quickly configure this:
 
-* **`AwsCustomResourcePolicy.fromSdkCalls`** - Use this to auto-generate IAM Policy statements based on the configured SDK calls.
-Note that you will have to either provide specific ARN's, or explicitly use `AwsCustomResourcePolicy.ANY_RESOURCE` to allow access to any resource.
-* **`AwsCustomResourcePolicy.fromStatements`** - Use this to specify your own custom statements.
+* **`AwsCustomResourcePolicy.fromSdkCalls`** - Use this to auto-generate IAM
+  Policy statements based on the configured SDK calls. Keep two things in mind
+  when using this policy:
+  * This policy variant assumes the IAM policy name has the same name as the API
+    call. This is true in 99% of cases, but there are exceptions (for example,
+    S3's `PutBucketLifecycleConfiguration` requires
+    `s3:PutLifecycleConfiguration` permissions, Lambda's `Invoke` requires
+    `lambda:InvokeFunction` permissions). Use `fromStatements` if you want to
+    do a call that requires different IAM action names.
+  * You will have to either provide specific ARNs, or explicitly use
+    `AwsCustomResourcePolicy.ANY_RESOURCE` to allow access to any resource.
+* **`AwsCustomResourcePolicy.fromStatements`** - Use this to specify your own
+  custom statements.
 
 The custom resource also implements `iam.IGrantable`, making it possible to use the `grantXxx()` methods.
 

packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts

@@ -199,6 +199,13 @@ export class AwsCustomResourcePolicy {
    *
    * Each SDK call with be translated to an IAM Policy Statement in the form of: `call.service:call.action` (e.g `s3:PutObject`).
    *
+   * This policy generator assumes the IAM policy name has the same name as the API
+   * call. This is true in 99% of cases, but there are exceptions (for example,
+   * S3's `PutBucketLifecycleConfiguration` requires
+   * `s3:PutLifecycleConfiguration` permissions, Lambda's `Invoke` requires
+   * `lambda:InvokeFunction` permissions). Use `fromStatements` if you want to
+   * do a call that requires different IAM action names.
+   *
    * @param options options for the policy generation
    */
   public static fromSdkCalls(options: SdkCallsPolicyOptions) {