feat(kinesis): grantRead now allows the ListShards action and grant is now public

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

@@ -26,6 +26,9 @@ intake and aggregation.
 - [Streams](#streams)
   - [Encryption](#encryption)
   - [Import](#import)
+  - [Permission Grants](#permission-grants)
+    - [Read Permissions](#read-permissions)
+    - [Write Permissions](#write-permissions)
 
 ## Streams
 
@@ -119,3 +122,65 @@ const importedStream = Stream.fromStreamAttributes(
   }
 );
 ```
+
+### Permission Grants
+
+IAM roles, users or groups which need to be able to work with Amazon Kinesis streams at runtime will should be granted IAM permissions. Any object that implements the `IGrantable`
+interface (has an associated principal) can be granted permissions by calling:
+
+- `grantRead(principal)` - grants the principal read access
+- `grantWrite(principal)` - grants the principal write permissions to a Stream
+- `grantReadWrite(principal)` - grants principal read and write permissions
+
+#### Read Permissions
+
+Grant `read` access to a stream by calling the `grantRead()` API.
+If the stream has an encryption key, read permissions will also be granted to the key.
+
+```ts
+const lambdaRole = new iam.Role(this, 'Role', {
+  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+  description: 'Example role...',
+}
+
+const stream = new Stream(this, 'MyEncryptedStream', {
+    encryption: StreamEncryption.KMS
+});
+
+// give lambda permissions to read stream
+stream.grantRead(lambdaRole);
+```
+
+The following read permissions are provided to a service principal by the `grantRead()` API:
+
+- `kinesis:DescribeStream`
+- `kinesis:DescribeStreamSummary`
+- `kinesis:GetRecords`
+- `kinesis:GetShardIterator`
+- `kinesis:ListShards`
+- `kinesis:SubscribeToShard`
+
+#### Write Permissions
+
+Grant `write` permissions to a stream is provided by calling the `grantWrite()` API.
+If the stream has an encryption key, write permissions will also be granted to the key.
+
+```ts
+const lambdaRole = new iam.Role(this, 'Role', {
+  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+  description: 'Example role...',
+}
+
+const stream = new Stream(this, 'MyEncryptedStream', {
+    encryption: StreamEncryption.KMS
+});
+
+// give lambda permissions to write to stream
+stream.grantWrite(lambdaRole);
+```
+
+The following write permissions are provided to a service principal by the `grantWrite()` API:
+
+- `kinesis:ListShards`
+- `kinesis:PutRecord`
+- `kinesis:PutRecords`

packages/@aws-cdk/aws-kinesis/lib/stream.ts

@@ -115,7 +115,14 @@ abstract class StreamBase extends Resource implements IStream {
    * contents of the stream will also be granted.
    */
   public grantRead(grantee: iam.IGrantable) {
-    const ret = this.grant(grantee, 'kinesis:DescribeStream', 'kinesis:GetRecords', 'kinesis:GetShardIterator');
+    const ret = this.grant(
+      grantee,
+      'kinesis:DescribeStream',
+      'kinesis:DescribeStreamSummary',
+      'kinesis:GetRecords',
+      'kinesis:GetShardIterator',
+      'kinesis:ListShards',
+      'kinesis:SubscribeToShard');
 
     if (this.encryptionKey) {
       this.encryptionKey.grantDecrypt(grantee);
@@ -132,7 +139,11 @@ abstract class StreamBase extends Resource implements IStream {
    * contents of the stream will also be granted.
    */
   public grantWrite(grantee: iam.IGrantable) {
-    const ret = this.grant(grantee, 'kinesis:DescribeStream', 'kinesis:PutRecord', 'kinesis:PutRecords');
+    const ret = this.grant(
+      grantee,
+      'kinesis:ListShards',
+      'kinesis:PutRecord',
+      'kinesis:PutRecords');
 
     if (this.encryptionKey) {
       this.encryptionKey.grantEncrypt(grantee);
@@ -152,10 +163,13 @@ abstract class StreamBase extends Resource implements IStream {
     const ret = this.grant(
       grantee,
       'kinesis:DescribeStream',
+      'kinesis:DescribeStreamSummary',
       'kinesis:GetRecords',
       'kinesis:GetShardIterator',
+      'kinesis:ListShards',
       'kinesis:PutRecord',
-      'kinesis:PutRecords');
+      'kinesis:PutRecords',
+      'kinesis:SubscribeToShard');
 
     if (this.encryptionKey) {
       this.encryptionKey.grantEncryptDecrypt(grantee);
@@ -164,7 +178,10 @@ abstract class StreamBase extends Resource implements IStream {
     return ret;
   }
 
-  private grant(grantee: iam.IGrantable, ...actions: string[]) {
+  /**
+   * Grant the indicated permissions on this stream to the given IAM principal (Role/Group/User).
+   */
+  public grant(grantee: iam.IGrantable, ...actions: string[]) {
     return iam.Grant.addToPrincipal({
       grantee,
       actions,

packages/@aws-cdk/aws-kinesis/test/integ.stream.expected.json

@@ -40,10 +40,13 @@
             {
               "Action": [
                 "kinesis:DescribeStream",
+                "kinesis:DescribeStreamSummary",
                 "kinesis:GetRecords",
                 "kinesis:GetShardIterator",
+                "kinesis:ListShards",
                 "kinesis:PutRecord",
-                "kinesis:PutRecords"
+                "kinesis:PutRecords",
+                "kinesis:SubscribeToShard"
               ],
               "Effect": "Allow",
               "Resource": {

packages/@aws-cdk/aws-kinesis/test/test.stream.ts

@@ -305,7 +305,6 @@ export = {
   },
 
   'encryption key cannot be supplied with UNENCRYPTED as the encryption type'(test: Test) {
-
     const stack = new Stack();
     const key = new kms.Key(stack, 'myKey');
 
@@ -608,7 +607,14 @@ export = {
                 PolicyDocument: {
                   Statement: [
                     {
-                      Action: ['kinesis:DescribeStream', 'kinesis:GetRecords', 'kinesis:GetShardIterator'],
+                      Action: [
+                        'kinesis:DescribeStream',
+                        'kinesis:DescribeStreamSummary',
+                        'kinesis:GetRecords',
+                        'kinesis:GetShardIterator',
+                        'kinesis:ListShards',
+                        'kinesis:SubscribeToShard'
+                      ],
                       Effect: 'Allow',
                       Resource: {
                         'Fn::GetAtt': ['MyStream5C050E93', 'Arn']
@@ -732,7 +738,7 @@ export = {
                 PolicyDocument: {
                   Statement: [
                     {
-                      Action: ['kinesis:DescribeStream', 'kinesis:PutRecord', 'kinesis:PutRecords'],
+                      Action: ['kinesis:ListShards', 'kinesis:PutRecord', 'kinesis:PutRecords'],
                       Effect: 'Allow',
                       Resource: {
                         'Fn::GetAtt': ['MyStream5C050E93', 'Arn']
@@ -856,7 +862,16 @@ export = {
                 PolicyDocument: {
                   Statement: [
                     {
-                      Action: ['kinesis:DescribeStream', 'kinesis:GetRecords', 'kinesis:GetShardIterator', 'kinesis:PutRecord', 'kinesis:PutRecords'],
+                      Action: [
+                        'kinesis:DescribeStream',
+                        'kinesis:DescribeStreamSummary',
+                        'kinesis:GetRecords',
+                        'kinesis:GetShardIterator',
+                        'kinesis:ListShards',
+                        'kinesis:PutRecord',
+                        'kinesis:PutRecords',
+                        'kinesis:SubscribeToShard'
+                      ],
                       Effect: 'Allow',
                       Resource: {
                         'Fn::GetAtt': ['MyStream5C050E93', 'Arn']
@@ -924,7 +939,14 @@ export = {
                 PolicyDocument: {
                   Statement: [
                     {
-                      Action: ['kinesis:DescribeStream', 'kinesis:GetRecords', 'kinesis:GetShardIterator'],
+                      Action: [
+                        'kinesis:DescribeStream',
+                        'kinesis:DescribeStreamSummary',
+                        'kinesis:GetRecords',
+                        'kinesis:GetShardIterator',
+                        'kinesis:ListShards',
+                        'kinesis:SubscribeToShard'
+                      ],
                       Effect: 'Allow',
                       Resource: {
                         'Fn::GetAtt': ['MyStream5C050E93', 'Arn']
@@ -1005,7 +1027,7 @@ export = {
                 PolicyDocument: {
                   Statement: [
                     {
-                      Action: ['kinesis:DescribeStream', 'kinesis:PutRecord', 'kinesis:PutRecords'],
+                      Action: ['kinesis:ListShards', 'kinesis:PutRecord', 'kinesis:PutRecords'],
                       Effect: 'Allow',
                       Resource: {
                         'Fn::GetAtt': ['MyStream5C050E93', 'Arn']
@@ -1086,7 +1108,16 @@ export = {
                 PolicyDocument: {
                   Statement: [
                     {
-                      Action: ['kinesis:DescribeStream', 'kinesis:GetRecords', 'kinesis:GetShardIterator', 'kinesis:PutRecord', 'kinesis:PutRecords'],
+                      Action: [
+                        'kinesis:DescribeStream',
+                        'kinesis:DescribeStreamSummary',
+                        'kinesis:GetRecords',
+                        'kinesis:GetShardIterator',
+                        'kinesis:ListShards',
+                        'kinesis:PutRecord',
+                        'kinesis:PutRecords',
+                        'kinesis:SubscribeToShard'
+                      ],
                       Effect: 'Allow',
                       Resource: {
                         'Fn::GetAtt': ['MyStream5C050E93', 'Arn']

packages/@aws-cdk/aws-lambda-event-sources/test/integ.kinesis.expected.json

@@ -39,8 +39,11 @@
             {
               "Action": [
                 "kinesis:DescribeStream",
+                "kinesis:DescribeStreamSummary",
                 "kinesis:GetRecords",
-                "kinesis:GetShardIterator"
+                "kinesis:GetShardIterator",
+                "kinesis:ListShards",
+                "kinesis:SubscribeToShard"
               ],
               "Effect": "Allow",
               "Resource": {

packages/@aws-cdk/aws-lambda-event-sources/test/integ.kinesiswithdlq.expected.json

@@ -53,8 +53,11 @@
             {
               "Action": [
                 "kinesis:DescribeStream",
+                "kinesis:DescribeStreamSummary",
                 "kinesis:GetRecords",
-                "kinesis:GetShardIterator"
+                "kinesis:GetShardIterator",
+                "kinesis:ListShards",
+                "kinesis:SubscribeToShard"
               ],
               "Effect": "Allow",
               "Resource": {

packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts

@@ -27,8 +27,11 @@ export = {
           {
             'Action': [
               'kinesis:DescribeStream',
+              'kinesis:DescribeStreamSummary',
               'kinesis:GetRecords',
-              'kinesis:GetShardIterator'
+              'kinesis:GetShardIterator',
+              'kinesis:ListShards',
+              'kinesis:SubscribeToShard'
             ],
             'Effect': 'Allow',
             'Resource': {

packages/@aws-cdk/aws-logs-destinations/test/kinesis.test.ts

@@ -51,7 +51,7 @@ test('stream can be subscription destination', () => {
       Statement: [
         {
           Action: [
-            'kinesis:DescribeStream',
+            'kinesis:ListShards',
             'kinesis:PutRecord',
             'kinesis:PutRecords',
           ],
@@ -122,7 +122,7 @@ test('stream can be subscription destination twice, without duplicating permissi
       Statement: [
         {
           Action: [
-            'kinesis:DescribeStream',
+            'kinesis:ListShards',
             'kinesis:PutRecord',
             'kinesis:PutRecords',
           ],