Amazon ECS CodeDeploy IAM Role - Amazon Elastic Container Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon ECS CodeDeploy IAM Role

Before you can use the CodeDeploy blue/green deployment type with Amazon ECS, the CodeDeploy service needs permissions to update your Amazon ECS service on your behalf. These permissions are provided by the CodeDeploy IAM role (ecsCodeDeployRole).

Note

Users also require permissions to use CodeDeploy; these permissions are described in Blue/green deployment required IAM permissions.

There are two managed policies provided. The AWSCodeDeployRoleForECS policy, shown below, gives CodeDeploy permission to update any resource using the associated action. The AWSCodeDeployRoleForECSLimited policy, shown below, gives CodeDeploy more limited permissions.

AWSCodeDeployRoleForECS
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "ecs:DescribeServices", "ecs:CreateTaskSet", "ecs:UpdateServicePrimaryTaskSet", "ecs:DeleteTaskSet", "elasticloadbalancing:DescribeTargetGroups", "elasticloadbalancing:DescribeListeners", "elasticloadbalancing:ModifyListener", "elasticloadbalancing:DescribeRules", "elasticloadbalancing:ModifyRule", "lambda:InvokeFunction", "cloudwatch:DescribeAlarms", "sns:Publish", "s3:GetObject", "s3:GetObjectVersion" ], "Resource": "*", "Effect": "Allow" }, { "Action": ["iam:PassRole"], "Effect": "Allow", "Resource": "*", "Condition": { "StringLike": { "iam:PassedToService": ["ecs-tasks.amazonaws.com"] } } } ] }
AWSCodeDeployRoleForECSLimited
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "ecs:DescribeServices", "ecs:CreateTaskSet", "ecs:UpdateServicePrimaryTaskSet", "ecs:DeleteTaskSet", "cloudwatch:DescribeAlarms" ], "Resource": "*", "Effect": "Allow" }, { "Action": ["sns:Publish"], "Resource": "arn:aws:sns:*:*:CodeDeployTopic_*", "Effect": "Allow" }, { "Action": [ "elasticloadbalancing:DescribeTargetGroups", "elasticloadbalancing:DescribeListeners", "elasticloadbalancing:ModifyListener", "elasticloadbalancing:DescribeRules", "elasticloadbalancing:ModifyRule" ], "Resource": "*", "Effect": "Allow" }, { "Action": ["lambda:InvokeFunction"], "Resource": "arn:aws:lambda:*:*:function:CodeDeployHook_*", "Effect": "Allow" }, { "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Resource": "*", "Condition": { "StringEquals": {"s3:ExistingObjectTag/UseWithCodeDeploy": "true"} }, "Effect": "Allow" }, { "Action": ["iam:PassRole"], "Effect": "Allow", "Resource": [ "arn:aws:iam::*:role/ecsTaskExecutionRole", "arn:aws:iam::*:role/ECSTaskExecution*" ], "Condition": { "StringLike": { "iam:PassedToService": ["ecs-tasks.amazonaws.com"] } } } ] }

Creating the CodeDeploy AWSCodeDeployRoleForECS role

You can use the following procedures to create a CodeDeploy role for Amazon ECS

Amazon Web Services Management Console
To create the service role for CodeDeploy (IAM console)
  1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane of the IAM console, choose Roles, and then choose Create role.

  3. For Trusted entity type, choose Amazon Web Service.

  4. For Service or use case, choose CodeDeploy, and then choose the CodeDeploy - ECS use case.

  5. Choose Next.

  6. In the Attach permissions policy section, ensure that the AWSCodeDeployRoleForECS policy is selected.

  7. (Optional) Set a permissions boundary. This is an advanced feature that is available for service roles, but not service-linked roles.

    1. Open the Set permissions boundary section, and then choose Use a permissions boundary to control the maximum role permissions.

      IAM includes a list of the Amazon managed and customer-managed policies in your account.

    2. Select the policy to use for the permissions boundary.

  8. Choose Next.

  9. Enter a role name or a role name suffix to help you identify the purpose of the role.

    Important

    When you name a role, note the following:

    • Role names must be unique within your Amazon Web Services account, and can't be made unique by case.

      For example, don't create roles named both PRODROLE and prodrole. When a role name is used in a policy or as part of an ARN, the role name is case sensitive, however when a role name appears to customers in the console, such as during the sign-in process, the role name is case insensitive.

    • You can't edit the name of the role after it's created because other entities might reference the role.

  10. (Optional) For Description, enter a description for the role.

  11. (Optional) To edit the use cases and permissions for the role, in the Step 1: Select trusted entities or Step 2: Add permissions sections, choose Edit.

  12. (Optional) To help identify, organize, or search for the role, add tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM resources in the IAM User Guide.

  13. Review the role, and then choose Create role.

Amazon CLI

Replace all user input with your own information.

  1. Create a file named codedeploy-trust-policy.json that contains the trust policy to use for the CodeDeploy IAM role.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": ["codedeploy.amazonaws.com"] }, "Action": "sts:AssumeRole" } ] }
  2. Create an IAM role named ecsCodedeployRole using the trust policy created in the previous step.

    aws iam create-role \ --role-name ecsCodedeployRole \ --assume-role-policy-document file://codedeploy-trust-policy.json
  3. Attach the AWSCodeDeployRoleForECS or AWSCodeDeployRoleForECSLimited managed policy to the ecsTaskRole role.

    aws iam attach-role-policy \ --role-name ecsCodedeployRole \ --policy-arn arn:aws-cn::iam::aws:policy/AWSCodeDeployRoleForECS
    aws iam attach-role-policy \ --role-name ecsCodedeployRole \ --policy-arn arn:aws-cn::iam::aws:policy/AWSCodeDeployRoleForECSLimited

Adding permissions for blue/green deployments

If the tasks in your Amazon ECS service using the blue/green deployment type require the use of the task execution role or a task role override, then you must add the iam:PassRole permission for each task execution role or task role override to the CodeDeploy IAM role as a policy. For more information, see Amazon ECS task execution IAM role and Task IAM role.

Use the following procedure to create the policy

Amazon Web Services Management Console
To use the JSON policy editor to create a policy
  1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane on the left, choose Policies.

    If this is your first time choosing Policies, the Welcome to Managed Policies page appears. Choose Get Started.

  3. At the top of the page, choose Create policy.

  4. In the Policy editor section, choose the JSON option.

  5. Enter the following JSON policy document:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:PassRole", "Resource": ["arn:aws:iam::<aws_account_id>:role/<ecsTaskExecutionRole_or_TaskRole_name>"] } ] }
  6. Choose Next.

    Note

    You can switch between the Visual and JSON editor options anytime. However, if you make changes or choose Next in the Visual editor, IAM might restructure your policy to optimize it for the visual editor. For more information, see Policy restructuring in the IAM User Guide.

  7. On the Review and create page, enter a Policy name and a Description (optional) for the policy that you are creating. Review Permissions defined in this policy to see the permissions that are granted by your policy.

  8. Choose Create policy to save your new policy.

After you create the policy, attach the policy to the CodeDeploy role. For information about how to attach the policy to the role, see Modifying a role permissions policy (console) in the Amazon Identity and Access Management User Guide.

Amazon CLI

Replace all user input with your own information.

  1. Create a file called blue-green-iam-passrole.json with the following content.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:PassRole", "Resource": ["arn:aws:iam::<aws_account_id>:role/<ecsTaskExecutionRole_or_TaskRole_name>"] } ] }
  2. Use the following command to create the IAM policy using the JSON policy document file.

    aws iam create-policy \ --policy-name cdTaskExecutionPolicy \ --policy-document file://blue-green-iam-passrole.json
  3. Retrieve the ARN of the IAM policy you created using the following command.

    aws iam list-policies --scope Local --query 'Policies[?PolicyName==`cdTaskExecutionPolicy`].Arn'
  4. Use the following command to attach the policy to the CodeDeploy IAM role.

    aws iam attach-role-policy \ --role-name ecsCodedeployRole \ --policy-arn arn:aws-cn:iam:111122223333:aws:policy/cdTaskExecutionPolicy