Menu
Amazon EC2 Container Service
Developer Guide (API Version 2014-11-13)

Troubleshooting IAM Roles for Tasks

If you are having trouble configuring IAM roles for tasks in your cluster, you can try this known good configuration to help debug your own configuration.

The following procedure helps you to:

  • Create a CloudWatch Logs log group to store your test logs

  • Create a task IAM role that has full Amazon ECS permissions

  • Register a task definition with a known good AWS CLI configuration that is compatible with IAM roles for tasks

  • Run a task from that task definition to test your container instance support for IAM roles for tasks

  • View the container logs from that task in CloudWatch Logs to verify that it works

To test IAM roles for tasks with a known good configuration

  1. Create a CloudWatch Logs log group called ecs-tasks.

    1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

    2. In the left navigation pane, choose Logs.

    3. Choose Actions, Create log group.

    4. For Log Group Name, enter ecs-tasks.

    5. Choose Create log group to finish.

  2. Create an IAM role for your task to use.

    1. Open the IAM console at https://console.aws.amazon.com/iam/.

    2. In the navigation pane, choose Roles, Create new role.

    3. For AWS Service Role, choose Amazon EC2 Container Service Task Role.

    4. On the Attach Policy page, choose AmazonEC2ContainerServiceFullAccess, and then choose Next Step.

    5. On the Set role name and review page, for Role name, enter ECS-task-full-access and choose Create role.

  3. Register a task definition that uses your new role.

    1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.

    2. In the navigation pane, choose Task Definitions.

    3. On the Task Definitions page, choose Create new Task Definition.

    4. Scroll to the bottom of the page and choose Configure via JSON.

    5. Paste the sample task definition JSON below into the text area (replacing the pre-populated JSON there) and choose Save.

      Note

      Replace the awslogs-region value with the region that you created your CloudWatch Logs log group in.

      Copy
      { "taskRoleArn": "ECS-task-full-access", "containerDefinitions": [ { "memory": 128, "essential": true, "name": "amazonlinux", "image": "amazonlinux", "entryPoint": [ "/bin/bash", "-c" ], "command": [ "yum install -y aws-cli; aws ecs list-tasks --region us-west-2" ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "ecs-tasks", "awslogs-region": "us-west-2", "awslogs-stream-prefix": "iam-role-test" } } } ], "family": "iam-role-test" }
    6. Verify your information and choose Create.

  4. Run a task from your task definition.

    1. On the Task Definition: iam-role-test registration confirmation page, choose Actions, Run Task.

    2. On the Run Task page, choose Run Task to run your task.

  5. View the container logs in the CloudWatch Logs console.

    1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

    2. In the left navigation pane, choose Logs.

    3. Choose the ecs-tasks log group.

    4. Choose the most recent log stream.

    5. Scroll down to view the last lines of the log stream. You should see the output of the aws ecs list-tasks command.

      Copy
      { "taskArns": [ "arn:aws:ecs:us-east-1:aws_account_id:task/d48feb62-46e2-4cbc-a36b-e0400b993d1d" ] }

      Note

      If you receive an "Unable to locate credentials" error, then IAM roles for tasks is not enabled on your container instances. For more information, see Enabling Task IAM Roles on your Container Instances.