Merge pull request #724 from guardian/nicl/improve-cdk-base-readme

Improve cdk base readme

.gitignore

@@ -15,3 +15,6 @@ roles/.vagrant
 
 .metals
 .vscode
+.bloop
+project/metals.sbt
+project/project

roles/cdk-base/README.md

@@ -1,26 +1,33 @@
-CDK Base
-========
+# CDK Base
 
-**WARNING: this role is experimental and not recommended for Production use
-yet.**
+**Note: this role is experimental. It is safe to use but the precise behaviour
+and required tags are still subject to change.**
 
 This role includes boot tasks that the Guardian's EC2 CDK patterns and best
 practices rely on.
 
 At the moment this means the following:
 
-* fetch instance tags and store under /etc/config
-* ship cloud-init logs to a Kinesis stream
-
-We strongly recommend [enabling tag metadata on your
-instance](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-launchtemplatedata-metadataoptions.html#cfn-ec2-launchtemplate-launchtemplatedata-metadataoptions-instancemetadatatags)
-as this does not require remote AWS API calls at runtime.
+- fetch instance tags and store under /etc/config
+- ship cloud-init logs to a Kinesis stream
 
 To ship logs, ensure your instance has the following tag:
 
     LogKinesisStreamName
 
-set to the name of your logging Kinesis Stream.
+set to the name of your logging Kinesis stream.
+
+Also ensure your instances have permissions, scoped to the same Kinesis stream:
+
+    kinesis:DescribeStream
+    kinesis:PutRecord
+
+If you are using @guardian/cdk version 41.1.0 or greater the required tag and
+permissions are automatically added.
+
+_While not required, it is strongly recommended to [enable tag metadata on your
+instance](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-launchtemplatedata-metadataoptions.html#cfn-ec2-launchtemplate-launchtemplatedata-metadataoptions-instancemetadatatags)
+as this allows tag lookup without requiring remote AWS API calls at runtime._
 
 For more information on behaviour, see
 [instance-tag-discovery](https://github.com/guardian/instance-tag-discovery) and