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

Scheduled Tasks (cron)

You can run Amazon ECS tasks on a cron-like schedule using CloudWatch Events rules and targets.

If you have tasks to run at set intervals in your cluster, such as a backup operation or a log scan, you can use the Amazon ECS console to create a CloudWatch Events rule that runs one or more tasks in your cluster at the specified times. Your scheduled event rule can be set to either a specific interval (run every N minutes, hours, or days), or for more complicated scheduling, you can use a cron expression. For more information, see Schedule Expressions for Rules in the Amazon CloudWatch Events User Guide.

Creating a scheduled task

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

  2. Choose the cluster in which to create your scheduled task.

  3. On the Cluster: cluster-name page, choose Scheduled Tasks, Create.

  4. For Schedule rule name, enter a unique name for your schedule rule. Up to 64 letters, numbers, periods, hyphens, and underscores are allowed.

  5. (Optional) For Schedule rule description, enter a description for your rule. Up to 512 characters are allowed.

  6. For Schedule rule type, choose whether to use a fixed interval schedule or a cron expression for your schedule rule. For more information, see Schedule Expressions for Rules in the Amazon CloudWatch Events User Guide.

    • For Run at fixed interval, enter the interval and unit for your schedule.

    • For Cron expression, enter the cron expression for your task schedule. These expressions have six required fields, and fields are separated by white space. For more information, and examples of cron expressions, see Cron Expressions in the Amazon CloudWatch Events User Guide.

  7. Create a target for your schedule rule.

    1. For Target id, enter a unique identifier for your target. Up to 64 letters, numbers, periods, hyphens, and underscores are allowed.

    2. For Launch type, choose whether your service should run tasks on Fargate infrastructure, or Amazon EC2 container instances that you maintain. For more information, see Amazon ECS Launch Types.

      Important

      This feature is not yet available for Fargate tasks in the eu-west-2 (London), ap-northeast-2 (Seoul), and us-west-1 (N. California) Regions.

    3. For Task definition, choose the family and revision (family:revision) of the task definition to run for this target.

    4. For Platform version, choose the platform version to use for this target. For more information, see AWS Fargate Platform Versions.

      Note

      Platform versions are only applicable to tasks that use the Fargate launch type.

    5. For Number of tasks, enter the number of instantiations of the specified task definition to run on your cluster when the rule executes.

    6. (Optional) For Task role override, choose the IAM role to use for the task in your target, instead of the task definition default. For more information, see IAM Roles for Tasks. Only roles with the Amazon EC2 Container Service Task Role trust relationship are shown here. For more information about creating an IAM role for your tasks, see Creating an IAM Role and Policy for your Tasks. You must add iam:PassRole permissions for any task role overrides to the CloudWatch IAM role. For more information, see CloudWatch Events IAM Role.

    7. If your scheduled task's task definition uses the awsvpc network mode, you must configure a VPC, subnet, and security group settings for your scheduled task. For more information, see Task Networking with the awsvpc Network Mode.

      1. For Cluster VPC, if you selected the EC2 launch type, choose the VPC in which your container instances reside. If you selected the Fargate launch type, select the VPC that the Fargate tasks should use. Ensure that the VPC you choose is not configured to require dedicated hardware tenancy as that is not supported by Fargate tasks.

      2. For Subnets, choose the available subnets for your scheduled task placement.

        Important

        Only private subnets are supported for the awsvpc network mode. Because tasks do not receive public IP addresses, a NAT gateway is required for outbound internet access, and inbound internet traffic should be routed through a load balancer.

      3. For Security groups, a security group has been created for your scheduled tasks, which allows HTTP traffic from the internet (0.0.0.0/0). To edit the name or the rules of this security group, or to choose an existing security group, choose Edit and then modify your security group settings.

      4. For Auto-assign Public IP, choose whether to have your tasks receive a public IP address. If you are using Fargate tasks, a public IP address must be assigned to the task's elastic network interface, with a route to the internet, or a NAT gateway that can route requests to the internet. This allows the task to pull container images.

    8. For CloudWatch Events IAM role for this target, choose an existing CloudWatch Events service role (ecsEventsRole) that you may have already created. Or, choose Create new role to create the required IAM role that allows CloudWatch Events to make calls to Amazon ECS to run tasks on your behalf. For more information, see CloudWatch Events IAM Role.

      Important

      If your scheduled tasks require the use of the task execution role, or if they use a task role override, then you must add iam:PassRole permissions for your task execution role or task role override to the CloudWatch IAM role. For more information, see CloudWatch Events IAM Role.

    9. (Optional) In the Container overrides section, you can expand individual containers and override the command and/or environment variables for that container that are defined in the task definition.

  8. (Optional) To add additional targets (other tasks to run when this rule is executed), choose Add targets and repeat the previous substeps for each additional target.

  9. Choose Create.

To edit a scheduled task

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

  2. Choose the cluster in which to edit your scheduled task.

  3. On the Cluster: cluster-name page, choose Scheduled Tasks.

  4. Select the box to the left of the schedule rule to edit, and choose Edit.

  5. Edit the fields to update and choose Update.