fix: update readme and IAM policies (#5)

README.md

@@ -52,6 +52,82 @@ The app has the following parameters:
 1. `PipelineName` - The CodePipeline pipeline name.
 1. `PipelineVersion` - The CodePipeline pipeline version.
 
+## IAM Roles in Test and Deploy stages
+
+IAM roles are required to provide in Test and Deploy stages. IAM policies will be attached to the provided IAM roles.
+
+### Test stage
+
+In test stage, the tests are run in CodeBuild. IAM policies are attached to the provided `IntegTestRole` to grant permissions to CodeBuild to:
+- Write logs to CloudWatch logs
+- Read artifacts from previous stage in S3 artifacts bucket.
+- Write artifacts to be used by later stage in S3 artifacts bucket.
+
+Here is the IAM policy that will be attached to the provided `IntegTestRole`:
+
+```
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Action": [
+                "logs:CreateLogGroup",
+                "logs:CreateLogStream",
+                "logs:PutLogEvents"
+            ],
+            "Resource": [
+                "arn:aws:logs:<region>:<account>:log-group:/aws/codebuild/*"
+            ],
+            "Effect": "Allow"
+        },
+        {
+            "Action": [
+                "s3:PutObject",
+                "s3:GetObject",
+                "s3:GetObjectVersion"
+            ],
+            "Resource": [
+                "arn:aws:s3:::<artifacts-bucket>/*"
+            ],
+            "Effect": "Allow"
+        },
+        {
+            "Action": [
+                "s3:ListBucket"
+            ],
+            "Resource": [
+                "arn:aws:s3:::<artifacts-bucket>"
+            ],
+            "Effect": "Allow"
+        }
+    ]
+}
+```
+
+### Deploy stage
+
+In deploy stage, the application is deployed via CloudFormation. IAM policies are attached to the provided `DeployRole` to grant permissions to CloudFormation to:
+- Read artifacts from previous stage in S3 artifacts bucket.
+
+Here is the IAM policy that will be attached to the provided `DeployRole`:
+
+```
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Action": [
+                "s3:GetObject"
+            ],
+            "Resource": [
+                "arn:aws:s3:::<artifacts-bucket>/*"
+            ],
+            "Effect": "Allow"
+        }
+    ]
+}
+```
+
 ## License Summary
 
 This sample code is made available under the MIT-0 license. See the LICENSE file.

sam/app/template.yaml

@@ -12,8 +12,8 @@ Metadata:
     SpdxLicenseId: MIT-0
     Labels: [github, cd, codepipeline, continuous-deploy, sam]
     HomePageUrl: https://github.com/awslabs/aws-sam-codepipeline-cd
-    SemanticVersion: 0.1.1
-    SourceCodeUrl: https://github.com/awslabs/aws-sam-codepipeline-cd/tree/0.1.1
+    SemanticVersion: 0.1.2
+    SourceCodeUrl: https://github.com/awslabs/aws-sam-codepipeline-cd/tree/0.1.2
     LicenseUrl: ../../LICENSE
     ReadmeUrl: ../../README.md
 
@@ -235,6 +235,7 @@ Resources:
   PipelineRole:
     Type: AWS::IAM::Role
     Properties:
+      Description: !Sub "Used by CodePipeline ${Pipeline}. Created by CloudFormation ${AWS::StackId}"
       AssumeRolePolicyDocument:
         Version: "2012-10-17"
         Statement:
@@ -397,6 +398,7 @@ Resources:
   BuildProjectRole:
     Type: AWS::IAM::Role
     Properties:
+      Description: !Sub "Used in CodeBuild project ${BuildProject}. Created by CloudFormation ${AWS::StackId}"
       AssumeRolePolicyDocument:
         Statement:
           - Action:
@@ -407,6 +409,21 @@ Resources:
                 - codebuild.amazonaws.com
         Version: '2012-10-17'
       Path: /service-role/
+  DeployStagePolicy:
+    Condtion: HasDeployStage
+    Type: AWS::IAM::Policy
+    Properties:
+      PolicyName: s3-access
+      Roles:
+        - !Ref DeployRoleName
+      PolicyDocument:
+        Version: '2012-10-17'
+        Statement:
+          - Action:
+              - s3:GetObject
+            Effect: Allow
+            Resource:
+              - !Sub arn:${AWS::Partition}:s3:::${Artifacts}/*
   SARPublishApp:
     Condition: HasPublishStage
     Type: 'AWS::Serverless::Application'