Merge branch 'main' into 36653

Author: jasdeepbhalla

docs/DESIGN_GUIDELINES.md

@@ -1165,9 +1165,50 @@ export abstract class TopicBase extends Resource implements ITopic, IEncryptedRe
 }
 ```
 
-The `TopicGrants` class, and many others, are generated automatically. But if there
-is no auto-generated grants class for a resource, you can implement it manually,
-following the same patterns.
+The `TopicGrants` class, and many others, are generated automatically from the `grants.json`
+file present at the root of each individual module (`packages/aws-sns` for SNS constructs and 
+so on). The `grants.json` file has the following general structure:
+
+```json
+{
+  "resources": {
+    "Topic": {
+      "hasResourcePolicy": true,
+      "grants": {
+        "publish": {
+          "actions": ["sns:Publish"],
+          "keyActions": ["kms:Decrypt", "kms:GenerateDataKey*"],
+          "docSummary": "Grant topic publishing permissions to the given identity"
+        },
+        "subscribe": {
+          "actions": ["sns:Subscribe"],
+          "arnFormat": "${topicArn}/*"
+        }
+      }
+    }
+  }
+}
+```
+
+where:
+
+* `Topic` - the class to generate grants for. This will lead to a class named TopicGrants.
+* `hasResourcePolicy` - indicates whether the resource supports a resource policy. When true, all auto-generated methods in the Grants class will attempt to add statements to the resource policy when applicable. When false, the methods will only modify the principal's policy.
+* `publish` - the name of a grant.
+* `actions` - the actions to encompass in the grant.
+* `keyActions` - if the resource has an associated KMS key, also grant these permissions on the key. Notice that the resource must implement the `iam.IEncryptedResource` interface for this to work.
+* `docSummary` - the public documentation for the method.
+* `arnFormat` - In some cases, the policy applies to a specific ARN patterns, rather than just the ARN of the resource.
+
+In some cases, however, it might not be possible to specify the grant details using the `grants.json`
+file. This is usually the case when grants require additional logic, such as checking whether the
+resource is owned or unowned, or when the grant needs to modify the resource policy of the resource
+(if it has one). In these cases, you can implement the grants class manually.
+
+Historically, grant methods were implemented directly on the resource construct interface (e.g.
+`sns.ITopic.grantPublish(principal)`). For backward compatibility reasons, these methods are still
+present on the resource interfaces, but new grant implementations are only allowed through the Grants
+classes [_awslint:no-grants_].
 
 ### Metrics
 

packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.cross-account-pipeline-cfn-action.js.snapshot/CdkPipelineCfnActionStack.assets.json

@@ -198,7 +198,7 @@
    "Properties": {
     "Content": {
      "S3Bucket": "cdk-hnb659fds-assets-12345678-test-region",
-     "S3Key": "c82567645316e1499ecd064c937f1183bb4a74e95800ff64fab4d308451ba5f0.zip"
+     "S3Key": "0cfdecad2260a3a84ad0c2d08a77e03c9d25e26c7b52f26b1e1faf97aef92f18.zip"
     },
     "Description": "/opt/awscli/aws"
    }

packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.cross-account-pipeline-cfn-action.js.snapshot/CdkPipelineCfnActionStack.template.json

@@ -199,7 +199,7 @@
    "Properties": {
     "Content": {
      "S3Bucket": "cdk-hnb659fds-assets-12345678-test-region",
-     "S3Key": "c82567645316e1499ecd064c937f1183bb4a74e95800ff64fab4d308451ba5f0.zip"
+     "S3Key": "0cfdecad2260a3a84ad0c2d08a77e03c9d25e26c7b52f26b1e1faf97aef92f18.zip"
     },
     "Description": "/opt/awscli/aws"
    }