chore: remove references to discouraged grant* methods in examples. (#36784)

In the examples, there are some references to `grant*` methods in L2s, that are now discouraged (though not formally deprecated). Replace these examples with the preferred way, which is using the `grants` attribute of the construct.

Some surrounding text also had to be updated to match the examples.


----

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

Author: otaviomacedo

CONTRIBUTING.md

@@ -988,37 +988,37 @@ finalized, will be added to the AWS CDK with a specific suffix: `BetaX`. APIs
 with the preview suffix will never be removed, instead they will be deprecated
 and replaced by either the stable version (without the suffix), or by a newer
 preview version. For example, assume we add the method
-`grantAwesomePowerBeta1`:
+`addSecondaryResourceBeta1()` to a class:
 
 ```ts
 /**
- * This method grants awesome powers
+ * This method adds a secondary resource to the main one
  */
-grantAwesomePowerBeta1();
+addSecondaryResourceBeta1(res: SomeResource);
 ```
 
 Times goes by, we get feedback that this method will actually be much better
-if it accepts a `Principal`. Since adding a required property is a breaking
-change, we will add `grantAwesomePowerBeta2()` and deprecate
-`grantAwesomePowerBeta1`:
+if it accepts an additional required `options` parameter. Since adding a required 
+parameter to a method is a breaking change, we will add `addSecondaryResourceBeta2()`
+and deprecate `addSecondaryResourceBeta1`:
 
 ```ts
 /**
-* This method grants awesome powers to the given principal
+* This method adds a secondary resource, with more options
 *
 * @param grantee The principal to grant powers to
 */
-grantAwesomePowerBeta2(grantee: iam.IGrantable)
+addSecondaryResourceBeta2(res: SomeResource, options: SecondaryResourceOptions);
 
 /**
-* This method grants awesome powers
-* @deprecated use grantAwesomePowerBeta2
+ * This method adds a secondary resource to the main one
+* @deprecated use addSecondaryResourceBeta1
 */
-grantAwesomePowerBeta1()
+addSecondaryResourceBeta1(res: SomeResource);
 ```
 
 When we decide it's time to graduate the API, the latest preview version will
-be deprecated and the final version - `grantAwesomePower` will be added.
+be deprecated and the final version - `addSecondaryResource` will be added.
 
 ## Documentation
 

packages/@aws-cdk/aws-elasticache-alpha/README.md

@@ -397,7 +397,7 @@ declare const role: iam.Role;
 
 // grant "elasticache:Connect" action permissions to role
 user.grantConnect(role);
-serverlessCache.grantConnect(role);
+serverlessCache.grants.connect(role);
 ```
 
 ### Import an existing user and user group

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

@@ -245,7 +245,7 @@ const vpc = new ec2.Vpc(this, 'TheVPC', {
 const securityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', { vpc });
     securityGroup.addEgressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(443));
 for (const gateway of provider.gatewayInstances) {
-  bucket.grantWrite(gateway);
+  bucket.grants.write(gateway);
   gateway.addSecurityGroup(securityGroup);
 }
 ```

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

@@ -32,27 +32,29 @@ Managed policies can be attached using `xxx.addManagedPolicy(ManagedPolicy.fromA
 
 ## Granting permissions to resources
 
-Many of the AWS CDK resources have `grant*` methods that allow you to grant other resources access to that resource. As an example, the following code gives a Lambda function write permissions (Put, Update, Delete) to a DynamoDB table.
+Many of the AWS CDK resources have grant methods (accessible via the `grants` attribute) that allow you to grant other 
+resources access to that resource. As an example, the following code gives a Lambda function write permissions 
+(Put, Update, Delete) to a DynamoDB table.
 
 ```ts
 declare const fn: lambda.Function;
 declare const table: dynamodb.Table;
 
-table.grantWriteData(fn);
+table.grants.writeData(fn);
 ```
 
-The more generic `grant` method allows you to give specific permissions to a resource:
+The more generic `actions` method allows you to give specific permissions to a resource:
 
 ```ts
 declare const fn: lambda.Function;
 declare const table: dynamodb.Table;
 
-table.grant(fn, 'dynamodb:PutItem');
+table.grants.actions(fn, 'dynamodb:PutItem');
 ```
 
-The `grant*` methods accept an `IGrantable` object. This interface is implemented by IAM principal resources (groups, users and roles), policies, managed policies and resources that assume a role such as a Lambda function, EC2 instance or a Codebuild project.
+The grant methods accept an `IGrantable` object. This interface is implemented by IAM principal resources (groups, users and roles), policies, managed policies and resources that assume a role such as a Lambda function, EC2 instance or a Codebuild project.
 
-You can find which `grant*` methods exist for a resource in the [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html).
+You can find which grant methods exist for a resource in the [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html).
 
 ## Roles
 
@@ -70,8 +72,8 @@ automatically if you associate the construct with other constructs from the
 AWS Construct Library (for example, if you tell an *AWS CodePipeline* to trigger
 an *AWS Lambda Function*, the Pipeline's Role will automatically get
 `lambda:InvokeFunction` permissions on that particular Lambda Function),
-or if you explicitly grant permissions using `grant` functions (see the
-previous section).
+or if you explicitly grant permissions using the public methods in the 
+`RoleGrants` class (see the previous section).
 
 ### Opting out of automatic permissions management
 
@@ -186,7 +188,7 @@ const fn = new lambda.Function(this, 'MyLambda', {
 });
 
 const bucket = new s3.Bucket(this, 'Bucket');
-bucket.grantRead(fn);
+bucket.grants.read(fn);
 ```
 
 The following report will be generated.
@@ -445,7 +447,8 @@ new iam.Role(this, 'Role', {
 
 ### Granting a principal permission to assume a role
 
-A principal can be granted permission to assume a role using `grantAssumeRole`.
+A principal can be granted permission to assume a role using `assumeRole` from the `RoleGrants` class.
+For convenience, an instance of this class is available via the `grants` attribute on the `Role` class.
 
 Note that this does not apply to service principals or account principals as they must be added to the role trust policy via `assumeRolePolicy`.
 
@@ -455,7 +458,7 @@ const role = new iam.Role(this, 'role', {
   assumedBy: new iam.AccountPrincipal(this.account)
 });
 
-role.grantAssumeRole(user);
+role.grants.assumeRole(user);
 ```
 
 ### Granting service and account principals permission to assume a role

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

@@ -68,14 +68,14 @@ Or more conveniently, write permissions to the log group can be granted as follo
 
 ```ts
 const logGroup = new logs.LogGroup(this, 'LogGroup');
-logGroup.grantWrite(new iam.ServicePrincipal('es.amazonaws.com'));
+logGroup.grants.write(new iam.ServicePrincipal('es.amazonaws.com'));
 ```
 
 Similarly, read permissions can be granted to the log group as follows.
 
 ```ts
 const logGroup = new logs.LogGroup(this, 'LogGroup');
-logGroup.grantRead(new iam.ServicePrincipal('es.amazonaws.com'));
+logGroup.grants.read(new iam.ServicePrincipal('es.amazonaws.com'));
 ```
 
 Be aware that any ARNs or tokenized values passed to the resource policy will be converted into AWS Account IDs.

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

@@ -61,14 +61,14 @@ myTopic.addSubscription(new subscriptions.SqsSubscription(queue));
 Note that subscriptions of queues in different accounts need to be manually confirmed by
 reading the initial message from the queue and visiting the link found in it.
 
- The `grantSubscribe` method adds a policy statement to the topic's resource policy, allowing the specified principal to perform the `sns:Subscribe` action.
+ The `topic.grants.subscribe` method adds a policy statement to the topic's resource policy, allowing the specified principal to perform the `sns:Subscribe` action.
  It's useful when you want to allow entities, such as another AWS account or resources created later, to subscribe to the topic at their own pace, separating permission granting from the actual subscription process.
 
 ```ts
 declare const accountPrincipal: iam.AccountPrincipal;
 const myTopic = new sns.Topic(this, 'MyTopic');
 
-myTopic.grantSubscribe(accountPrincipal);
+myTopic.grants.subscribe(accountPrincipal);
 ```
 
 ### Filter policy

packages/aws-cdk-lib/pipelines/ORIGINAL_API.md

@@ -628,7 +628,7 @@ The Action can also be used as a Grantable after having been added to a Pipeline
 const action = new pipelines.ShellScriptAction({ /* ... */ });
 pipeline.addStage('Test').addActions(action);
 
-bucket.grantRead(action);
+bucket.grants.read(action);
 ```
 
 #### Additional files from the source repository