From d75c91c3982ecabfcb6c6f63fb253748aa34e15e Mon Sep 17 00:00:00 2001
From: Charles Fort <cfort@woot.com>
Date: Thu, 25 Oct 2018 09:50:54 -0700
Subject: [PATCH] documented role parameter for DeploymentPreference

---
 docs/internals/generated_resources.rst                   | 3 +++
 docs/safe_lambda_deployments.rst                         | 7 ++++++-
 samtranslator/model/preferences/deployment_preference.py | 2 ++
 3 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/internals/generated_resources.rst b/docs/internals/generated_resources.rst
index b8323871e..53f4fdcf1 100644
--- a/docs/internals/generated_resources.rst
+++ b/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
 ~~~~~~~~~~~
 
diff --git a/docs/safe_lambda_deployments.rst b/docs/safe_lambda_deployments.rst
index 8346a83cd..7e8f0fdc4 100644
--- a/docs/safe_lambda_deployments.rst
+++ b/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.
diff --git a/samtranslator/model/preferences/deployment_preference.py b/samtranslator/model/preferences/deployment_preference.py
index 9ba6911a1..1eac71826 100644
--- a/samtranslator/model/preferences/deployment_preference.py
+++ b/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',