# Amazon ECS
AWS Systems Manager Automation provides predefined runbooks for Amazon Elastic Container Service. For more information about runbooks, see [Working with runbooks](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-documents.html). For information about how to view runbook content, see [View runbook content](automation-runbook-reference.md#view-automation-json).
**Topics**
+ [`AWSSupport-CollectECSInstanceLogs`](automation-awssupport-collectecsinstancelogs.md)
+ [`AWS-InstallAmazonECSAgent`](automation-aws-install-ecs-agent.md)
+ [`AWS-ECSRunTask`](aws-run-ecs-task.md)
+ [`AWSSupport-TroubleshootECSContainerInstance`](automation-aws-troubleshoot-ecs-container-instance.md)
+ [`AWSSupport-TroubleshootECSTaskFailedToStart`](automation-aws-troubleshootecstaskfailedtostart.md)
+ [`AWS-UpdateAmazonECSAgent`](automation-aws-update-ecs-agent.md)
# `AWSSupport-CollectECSInstanceLogs`
**Description**
The `AWSSupport-CollectECSInstanceLogs` runbook collects operating system and Amazon Elastic Container Service (Amazon ECS) related log files from an Amazon Elastic Compute Cloud (Amazon EC2) instance to help you troubleshoot common Amazon ECS issues. While the automation is collecting the associated log files, changes are made to the file system. These changes include the creation of temporary directories and a log directory, the copying of log files to these directories, and compressing the log files into an archive.
If you specify a value for the `LogDestination` parameter, the target instance must have the AWS Command Line Interface (AWS CLI) for Linux instances or AWS Tools for Windows PowerShell for Windows instances installed. The automation evaluates the policy status of the Amazon Simple Storage Service (Amazon S3) bucket you specify. To help with the security of the logs gathered from your Amazon EC2 instance, if the policy status `isPublic` is set to `true` , or if the access control list (ACL) grants `READ|WRITE` permissions to the `All Users` Amazon S3 predefined group, the logs are not uploaded. Additionaly, if the provided bucket is not available in your account, the logs are not uploaded. For more information about Amazon S3 predefined g roups, see [ Amazon S3 predefined groups](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#specifying-grantee-predefined-groups) in the *Amazon Simple Storage Service User Guide* .
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-CollectECSInstanceLogs)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, Windows
**Parameters**
+ AutomationAssumeRole
Type: String
Description: (Optional) The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts this runbook.
+ ECSInstanceId
Type: String
Description: (Required) The ID of the instance you want to collect logs from. The instance you specify must be managed by Systems Manager.
+ LogDestination
Type: String
Description: (Optional) The Amazon S3 bucket in your AWS account to upload the archived logs to.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:ListCommandInvocations`
+ `ssm:ListCommands`
+ `ssm:SendCommand`
+ `ssm:DescribeInstanceInformation`
We recommend that the Amazon EC2 instance you specify in the `ECSInstanceId` parameter has an IAM role with the `AmazonSSMManagedInstanceCore` Amazon managed policy attached. To upload the log archive to the Amazon S3 bucket you specify in the `LogDestination` parameter, you must add following permissions:
+ `s3:PutObject`
+ `s3:ListBucket`
+ `s3:GetBucketPolicyStatus`
+ `s3:GetBucketAcl`
**Document Steps**
+ `assertInstanceIsManaged` - Verifies whether the instance you specify in the `ECSInstanceId` parameter is managed by Systems Manager.
+ `getInstancePlatform` - Gets information about the operating system (OS) platform of the instance specified in the `ECSInstanceId` parameter.
+ `verifyInstancePlatform` - Branches the automation based on the OS platform.
+ `runLogCollectionScriptOnLinux` - Gathers operating system and Amazon ECS related log files on Linux instances and creates an archive file in the `/var/log/collectECSlogs` directory.
+ `runLogCollectionScriptOnWindows` - Gathers operating system and Amazon ECS related log files on Windows instances and creates an archive file in the `C:\ProgramData\collectECSlogs` directory.
+ `verifyIfS3BucketProvided` - Verifies whether a value was specified for the `LogDestination` parameter.
+ `runUploadScript` - Branches the automation step based on the OS platform.
+ `runUploadScriptOnLinux` - Uploads the log archive to the Amazon S3 bucket specified in the `LogDestination` parameter and deletes the archived log file from OS.
+ `runUploadScriptOnWindows` - Uploads the log archive to the Amazon S3 bucket specified in the `LogDestination` parameter and deletes the archived log file from OS.
# `AWS-InstallAmazonECSAgent`
**Description**
The `AWS-InstallAmazonECSAgent` runbook installs the Amazon Elastic Container Service (Amazon ECS) agent on the Amazon Elastic Compute Cloud (Amazon EC2) instance you specify. This runbook only supports Amazon Linux and Amazon Linux 2 instances.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-InstallAmazonECSAgent)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ AutomationAssumeRole
Type: String
Description: (Optional) The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts this runbook.
+ InstanceIds
Type: StringList
Description: (Required) The IDs of the Amazon EC2 instances you want to install the Amazon ECS agent on.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ssm:GetCommandInvocation`
+ `ec2:DescribeImages`
+ `ec2:DescribeInstanceAttribute`
+ `ec2:DescribeInstances`
**Document Steps**
`aws:executeScript` - Installs the Amazon ECS agent on the Amazon EC2 instances you specify in the `InstanceIds` parameter.
**Outputs**
InstallAmazonECSAgent.SuccessfulInstances - The ID of the instance where installation of the Amazon ECS agent succeeded.
InstallAmazonECSAgent.FailedInstances - The ID of the instance where installation of the Amazon ECS agent failed.
InstallAmazonECSAgent.InProgressInstances - The ID of the instance where installation of the Amazon ECS agent is in progress.
# `AWS-ECSRunTask`
**Description**
The `AWS-ECSRunTask` runbook runs the Amazon Elastic Container Service (Amazon ECS) task that you specify.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-ECSRunTask)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ AutomationAssumeRole
Type: String
Description: (Optional) The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts this runbook.
+ capacityProviderStrategy
Type: String
Description: (Optional) The capacity provider strategy to use for the task.
+ cluster
Type: String
Description: (Optional) The short name or ARN of the cluster to run your task on. If you do not specify a cluster, the default cluster is used.
+ count
Type: String
Description: (Optional) The number of instantiations of the specified task to place on your cluster. You can specify up to 10 tasks for each request.
+ enableECSManagedTags
Type: Boolean
Description: (Optional) Specifies whether to use Amazon ECS managed tags for the task. For more information, see [Tagging your Amazon ECS resources](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-using-tags.html) in the *Amazon Elastic Container Service Developer Guide*.
+ enableExecuteCommand
Type: Boolean
Description: (Optional) Determines whether to activate the execute command functionality for the containers in this task. If true, this activates execute command functionality on all containers in the task.
+ group
Type: String
Description: (Optional) The name of the task group to associate with the task. The default value is the family name of the task definition. For example, `family:my-family-name`.
+ launchType
Type: String
Valid values: EC2 \$1 FARGATE \$1 EXTERNAL
Description: (Optional) The infrastructure to run your standalone task on.
+ networkConfiguration
Type: String
Description: (Optional) The network configuration for the task. This parameter is required for task definitions that use the `awsvpc` network mode to receive their own elastic network interface, and it isn't supported for other network modes.
+ overrides
Type: String
Description: (Optional) A list of container overrides in JSON format that specify the name of a container in the specified task definition and the overrides it should receive. You can override the default command for a container that's specified in the task definition or Docker image with a command override. You can also override existing environment variables that are specified in the task definition or Docker image on a container. Additionally, you can add new environment variables with an environment override.
+ placementConstraints
Type: String
Description: (Optional) An array of placement constraint objects to use for the task. You can specify up to 10 constraints for each task including constraints in the task definition and those specified at runtime.
+ placementStrategy
Type: String
Description: (Optional) The placement strategy objects to use for the task. You can specify a maximum of 5 strategy rules for each task.
+ platformVersion
Type: String
Description: (Optional) The platform version that the task uses. A platform version is only specified for tasks hosted on Fargate. If a platform version isn't specified, the `LATEST` platform version is used.
+ propagateTags
Type: String
Description: (Optional) Determines whether tags propagate from the task definition to the task. If no value is specified, the tags aren't propagated. Tags can only be propagated to the task during task creation.
+ referenceId
Type: String
Description: (Optional) The reference ID to use for the task. The reference ID can have a maximum length of 1024 characters.
+ startedBy
Type: String
Description: (Optional) An optional tag specified when a task is started. This helps you identify which tasks belong to a specific job by filtering the results of a `ListTasks` API operation. Up to 36 letters (uppercase and lowercase), numbers, hyphens (-), and underscores (\$1) are allowed.
+ tags
Type: String
Description: (Optional) Metadata that you want to apply to the task to help you categorize and organize tasks. Each tag consists of a user-defined key and value.
+ taskDefinition
Type: String
Description: (Optional) The `family` and `revision` (`family`:`revision`) or full ARN of the task definition to run. If a revision isn't specified, the latest `ACTIVE` revision is used.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ecs:RunTask`
**Document Steps**
`aws:executeScript` - Runs the Amazon ECS task based on the values that you specify for the runbook input parameters.
# `AWSSupport-TroubleshootECSContainerInstance`
**Description**
The `AWSSupport-TroubleshootECSContainerInstance` runbook helps you troubleshoot an Amazon Elastic Compute Cloud (Amazon EC2) instance that fails to register with an Amazon ECS cluster. This automation reviews whether the user data for the instance contains the correct cluster information, whether the instance profile contains the required permissions, and network configuration issues.
**Important**
To successfully run this automation, the state of your Amazon EC2 instance must be `running` , and the Amazon ECS cluster state must be `ACTIVE` .
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootECSContainerInstance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ AutomationAssumeRole
Type: String
Description: (Optional) The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts this runbook.
+ ClusterName
Type: String
Description: (Required) The name of the Amazon ECS cluster that the instance failed to register with.
+ InstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 instance you want to troubleshoot.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:DescribeIamInstanceProfileAssociations`
+ `ec2:DescribeInstanceAttribute`
+ `ec2:DescribeInstances`
+ `ec2:DescribeNetworkAcls`
+ `ec2:DescribeRouteTables`
+ `ec2:DescribeSecurityGroups`
+ `ec2:DescribeSubnets`
+ `ec2:DescribeVpcEndpoints`
+ `ec2:DescribeVpcs`
+ `iam:GetInstanceProfile`
+ `iam:GetRole`
+ `iam:SimulateCustomPolicy`
+ `iam:SimulatePrincipalPolicy`
**Document Steps**
aws:executeScript: Reviews whether the Amazon EC2 instance meets the prerequisites needed to register with an Amazon ECS cluster.
# `AWSSupport-TroubleshootECSTaskFailedToStart`
**Description**
The `AWSSupport-TroubleshootECSTaskFailedToStart` runbook helps you troubleshoot why an Amazon Elastic Container Service (Amazon ECS) task in an Amazon ECS cluster failed to start. You must run this runbook in the same AWS Region as your task that failed to start. The runbook analyzes the following common issues that can prevent a task from starting:
+ Network connectivity to the configured container registry
+ Missing IAM permissions required by the task execution role
+ VPC endpoint connectivity
+ Security group rule configuration
+ AWS Secrets Manager secrets references
+ Logging configuration
**Note**
If the analysis determines that network connectivity needs to be tested, a Lambda function and requisite IAM role are created in your account. These resources are used to simulate the network connectivity of your failed task. The automation deletes these resources when they're no longer required. However, if the automation fails to delete the resources, you must do so manually.
When a Lambda IAM role is provided, the automation will use it instead of creating a new one. The provided Lambda IAM role must include the AWS managed policy `AWSLambdaVPCAccessExecutionRole` and have a trust policy that allows it to be assumed by the Lambda service principal `lambda.amazonaws.com`.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootECSTaskFailedToStart)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ AutomationAssumeRole
Type: String
Description: (Optional) The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts this runbook.
+ LambdaRoleArn
Type: String
Description: (Optional) The ARN of the IAM role that allows the AWS Lambda function to access the required AWS services and resources. If no role is specified, this Systems Manager Automation will create one IAM role for Lambda in your account with the name `NetworkToolSSMRunbookExecution` that includes the managed policy: `AWSLambdaVPCAccessExecutionRole`.
+ ClusterName
Type: String
Description: (Required) The name of the Amazon ECS cluster where the task failed to start.
+ CloudwatchRetentionPeriod
Type: Integer
Description: (Optional) The retention period, in days, for the Lambda function logs to be stored in Amazon CloudWatch Logs. This is only necessary if the analysis determines network connectivity needs to be tested.
Valid values: 1 \$1 3 \$1 5 \$1 7 \$1 14 \$1 30 \$1 60 \$1 90
Default: 30
+ TaskId
Type: String
Description: (Required) The ID of the failed task. Use the most recently failed task.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `cloudtrail:LookupEvents`
+ `ec2:DeleteNetworkInterface`
+ `ec2:DescribeDhcpOptions`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceAttribute`
+ `ec2:DescribeIamInstanceProfileAssociations`
+ `ec2:DescribeSecurityGroups`
+ `ec2:DescribeNetworkAcls`
+ `ec2:DescribeNetworkInterfaces`
+ `ec2:DescribeRouteTables`
+ `ec2:DescribeSubnets`
+ `ec2:DescribeVpcEndpoints`
+ `ec2:DescribeVpcs`
+ `ec2:DescribeVpcAttribute`
+ `elasticfilesystem:DescribeFileSystems`
+ `elasticfilesystem:DescribeMountTargets`
+ `elasticfilesystem:DescribeMountTargetSecurityGroups`
+ `elasticfilesystem:DescribeFileSystemPolicy`
+ `ecr:DescribeImages`
+ `ecr:GetRepositoryPolicy`
+ `ecs:DescribeContainerInstances`
+ `ecs:DescribeServices`
+ `ecs:DescribeTaskDefinition`
+ `ecs:DescribeTasks`
+ `iam:AttachRolePolicy`
+ `iam:CreateRole`
+ `iam:DeleteRole`
+ `iam:DetachRolePolicy`
+ `iam:GetInstanceProfile`
+ `iam:GetRole`
+ `iam:ListRoles`
+ `iam:ListUsers`
+ `iam:PassRole`
+ `iam:SimulateCustomPolicy`
+ `iam:SimulatePrincipalPolicy`
+ `kms:DescribeKey`
+ `lambda:CreateFunction`
+ `lambda:DeleteFunction`
+ `lambda:GetFunctionConfiguration`
+ `lambda:InvokeFunction`
+ `lambda:TagResource`
+ `logs:DescribeLogGroups`
+ `logs:PutRetentionPolicy`
+ `secretsmanager:DescribeSecret`
+ `ssm:DescribeParameters`
+ `sts:GetCallerIdentity`
When `LambdaRoleArn` is provided, the automation does not need to create the role and the following permissions can be excluded:
+ `iam:CreateRole`
+ `iam:DeleteRole`
+ `iam:AttachRolePolicy`
+ `iam:DetachRolePolicy`
**Document Steps**
+ `aws:executeScript` - Verifies that the user or role who started the automation has the required IAM permissions. If you don't have sufficient permissions to use this runbook, the missing required permissions are included in the output of the automation.
+ `aws:branch` - Branches based on whether you have permissions to all required actions for the runbook.
+ `aws:executeScript` - Creates a Lambda function in your VPC if the analysis determines network connectivity needs to be tested.
+ `aws:branch` - Branches based on the results of the previous step.
+ `aws:executeScript` - Analyzes possible causes for the failure to start your task.
+ `aws:executeScript` - Deletes resources created by this automation.
+ `aws:executeScript` - Formats the output of the automation to return the results of the analysis to the console. You can review the analysis after this step before the automation completes.
+ `aws:branch` - Branches based on whether the Lambda function and associated resources were created and need to be deleted.
+ `aws:sleep` - Sleeps for 30 minutes so the elastic network interface for the Lambda function can be deleted.
+ `aws:executeScript` - Deletes the Lambda function network interface.
+ `aws:executeScript` - Formats the output of the Lambda function network interface deletion step.
# `AWS-UpdateAmazonECSAgent`
**Description**
The `AWS-UpdateAmazonECSAgent` runbook updates the Amazon Elastic Container Service (Amazon ECS) agent on the Amazon Elastic Compute Cloud (Amazon EC2) instance you specify. This runbook only supports Amazon Linux and Amazon Linux 2 instances.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-UpdateAmazonECSAgent)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ AutomationAssumeRole
Type: String
Description: (Optional) The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts this runbook.
+ ClusterARN
Type: StringList
Description: (Required) The Amazon Resource Name (ARN) of the Amazon ECS cluster your container instances is registered with.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ssm:GetCommandInvocation`
+ `ec2:DescribeImages`
+ `ec2:DescribeInstanceAttribute`
+ `ec2:DescribeImage`
+ `ec2:DescribeInstance`
+ `ec2:DescribeInstanceAttribute`
+ `ecs:DescribeContainerInstances`
+ `ecs:DescribeClusters`
+ `ecs:ListContainerInstances`
+ `ecs:UpdateContainerAgent`
**Document Steps**
`aws:executeScript` - Updates the Amazon ECS agent on the Amazon ECS cluster you specify in the `ClusterARN` parameters.
**Outputs**
UpdateAmazonECSAgent.UpdatedContainers - The ID of the instance where the update of the Amazon ECS agent succeeded.
UpdateAmazonECSAgent.FailedContainers - The ID of the instance where the update of the Amazon ECS agent failed.
UpdateAmazonECSAgent.InProgressContainers - The ID of the instance where the update of the Amazon ECS agent is in progress.