docs: document role parameter for DeploymentPreference (#642)

Author: imphasing

docs/internals/generated_resources.rst

@@ -70,6 +70,7 @@ Example:
       AutoPublishAlias: live
       DeploymentPreference: 
         Type: Linear10PercentEvery10Minutes
+        Role: "arn"
       ...
 
 
@@ -83,6 +84,8 @@ AWS::CodeDeploy::DeploymentGroup   MyFunction\ **DeploymentGroup**
 AWS::IAM::Role                     CodeDeployServiceRole
 ================================== ================================
 
+  NOTE: ``AWS::IAM::Role`` resources are only generated if no Role parameter is supplied for DeploymentPreference
+
 With Events
 ~~~~~~~~~~~
 

docs/safe_lambda_deployments.rst

@@ -105,6 +105,9 @@ resource:
           # Validation Lambda functions that are run before & after traffic shifting
           PreTraffic: !Ref PreTrafficLambdaFunction
           PostTraffic: !Ref PostTrafficLambdaFunction
+        # Provide a custom role for CodeDeploy traffic shifting here, if you don't supply one
+        # SAM will create one for you with default permissions
+        Role: !Ref IAMRoleForCodeDeploy # Parameter example, you can pass an IAM ARN
 
   AliasErrorMetricGreaterThanZeroAlarm:
     Type: "AWS::CloudWatch::Alarm"
@@ -162,6 +165,7 @@ resource:
       FunctionName: 'CodeDeployHook_preTrafficHook'
       DeploymentPreference:
         Enabled: false
+        Role: ""
       Environment:
         Variables:
           CurrentVersion: !Ref MyLambdaFunction.Version
@@ -176,6 +180,7 @@ CloudFormation, the following happens:
 - During traffic shifting, if any of the CloudWatch Alarms go to *Alarm* state, CodeDeploy will immediately flip the Alias back to old version and report a failure to CloudFormation.
 - After traffic shifting completes, CodeDeploy will invoke the **PostTraffic Hook** Lambda function. This is similar to PreTraffic Hook where the function must callback to CodeDeploy to report a Success or a Failure. PostTraffic hook is a great place to run integration tests or other validation actions.
 - If everything went well, the Alias will be pointing to the new Lambda Version.
+- If you supply the "Role" argument to the DeploymentPreference, it will prevent SAM from creating a role and instead use the provided CodeDeploy role for traffic shifting
 
 NOTE: Verify that your AWS SDK version supports PutLifecycleEventHookExecutionStatus. For example, Python requires SDK version 1.4.8 or newer.
 
@@ -294,7 +299,7 @@ Internally, SAM will create the following resources in your CloudFormation stack
    SAM template belongs to its own Deployment Group.
 -  Adds ``UpdatePolicy`` on ``AWS::Lambda::Alias`` resource that is
    connected to the function's Deployment Group resource.
--  One ``AWS::IAM::Role`` called "CodeDeployServiceRole".
+-  One ``AWS::IAM::Role`` called "CodeDeployServiceRole", if no custom role is provided
 
 CodeDeploy assumes that there are no dependencies between Deployment Groups and hence will deploy them in parallel.
 Since every Lambda function is to its own CodeDeploy DeploymentGroup, they will be deployed in parallel.

samtranslator/model/preferences/deployment_preference.py

@@ -17,6 +17,8 @@
     version.
 :param alarms: A list of Cloudwatch Alarm references that if ever in the alarm state during a deployment (or
     before a deployment starts) cause the deployment to fail and rollback.
+:param role: An IAM role ARN that CodeDeploy will use for traffic shifting, an IAM role will not be created if 
+    this is supplied
 :param enabled: Whether this deployment preference is enabled (true by default)
 """
 DeploymentPreferenceTuple = namedtuple('DeploymentPreferenceTuple',