How to run a container on a schedule with ECS and EventBridge Scheduler, what the IAM and networking setup involves, how retries and failures behave, and how to avoid overlapping runs.

An ECS scheduled task is a container that Amazon ECS starts on a schedule, runs to completion and stops. The schedule lives in EventBridge Scheduler, which calls the ECS RunTask API with your cluster, task definition and network settings at each tick, so nightly cleanups, report generation and data syncs run without a server that sits idle the rest of the day.
Pointing a schedule at a task definition takes a few minutes; the surrounding setup takes longer. The schedule needs an IAM role that may run the task and pass its roles, the task needs subnets and a security group, a run that fails inside the container is invisible to the scheduler, and a slow run can still be going when the next one starts.
This guide starts with the same nightly job written as an Encore cron job, then builds it by hand with EventBridge Scheduler and ECS on Fargate.
Encore is a backend framework with built-in infrastructure. A cron job is a declaration in code that calls one of your API endpoints on a schedule. Cron jobs are Encore Platform managed and need no extra cloud infrastructure, so there is no schedule resource or task definition for the job in your account. The endpoint runs inside the service that already has access to the bucket or database it cleans up.

Run in your terminal to get started locally.
Exports are written to an object storage bucket with the creation time in the key. The cron job runs at 03:00 UTC every day and deletes anything older than a week:
// Service exports stores generated reports and deletes them after a week.
package exports
import (
"context"
"path"
"strings"
"time"
"encore.dev/cron"
"encore.dev/rlog"
"encore.dev/storage/objects"
)
// Keys look like "acct_7/20261118T084238Z.csv", so the age is in the name.
var Exports = objects.NewBucket("exports", objects.BucketConfig{})
const keep = 7 * 24 * time.Hour
// Every day at 03:00 UTC. No EventBridge rule or task definition to create.
var _ = cron.NewJob("purge-old-exports", cron.JobConfig{
Title: "Delete exports older than 7 days",
Schedule: "0 3 * * *",
Endpoint: PurgeOldExports,
})
type PurgeResult struct {
Deleted int `json:"deleted"`
}
// PurgeOldExports is safe to run twice: a second run finds nothing to delete.
//
//encore:api private
func PurgeOldExports(ctx context.Context) (*PurgeResult, error) {
cutoff := time.Now().Add(-keep)
res := &PurgeResult{}
for entry, err := range Exports.List(ctx, &objects.Query{}) {
if err != nil {
return nil, err
}
stamp := strings.TrimSuffix(path.Base(entry.Name), path.Ext(entry.Name))
created, err := time.Parse("20060102T150405Z", stamp)
if err != nil || created.After(cutoff) {
continue
}
if err := Exports.Remove(ctx, entry.Name); err != nil {
return nil, err
}
res.Deleted++
}
rlog.Info("purged exports", "deleted", res.Deleted)
return res, nil
}
The cron docs note that an endpoint may be called more than once, so the job is written to be idempotent: a second run finds nothing left to delete. Cron jobs do not run under encore run or in Preview Environments. We tested this one with encore test, which uses a local bucket: with one export eight days old and one from today, the first call deleted one object and kept today's, and a second call deleted none.
Schedules use cron syntax in UTC or an Every interval that divides 24 hours evenly, and each run's outcome shows in the Platform Dashboard's cron view. On AWS, the service itself runs on Fargate or EKS in your own account, and the job is part of the same deploy.
Best fit: Recurring jobs that are part of your application, such as cleanups, syncs and digests, where the code needs the same database, bucket and secrets as the service.
You need a task definition for the job's container, a cluster, private subnets with a route to the AWS APIs it calls, a security group, and an IAM role for EventBridge Scheduler. The role needs ecs:RunTask on the task definition and iam:PassRole for the task role and the execution role:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ecs:RunTask",
"Resource": "arn:aws:ecs:eu-central-1:123456789012:task-definition/purge-exports:*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": [
"arn:aws:iam::123456789012:role/purge-exports-task",
"arn:aws:iam::123456789012:role/ecs-task-execution"
]
}
]
}
The schedule itself names the target cluster, the role and the EcsParameters for the run. Unlike Encore's cron, EventBridge Scheduler supports a time zone, so 03:00 stays 03:00 Vienna time across daylight saving changes:
Three behaviors catch people out. The retry policy covers failed RunTask calls, for example when Fargate has no capacity, up to 185 attempts and 24 hours; once the task starts, a container that exits non-zero counts as delivered, so alert on ECS task state change events with a non-zero exit code. The scheduler does not know whether the previous run finished, so overlapping runs are possible when a job runs long. And every run pays the container's cold start, image pull included, which matters for jobs on short intervals.
For a purely age-based cleanup like the one above, an S3 lifecycle rule needs no job at all; scheduled tasks earn their place when the job needs application logic or a database.
Best fit: Batch jobs that need a different image, more memory or a longer runtime than the services, on ECS clusters you already manage.
Run the job as an ECS scheduled task when it is a separate program with its own image and resource needs, and set up the exit-code alert before you rely on it. Keep it inside the application when it uses the same code, database and secrets as the services, which is where a cron job on an endpoint avoids a second deployable. Pick Encore when you want those jobs declared next to the endpoint they call, with no schedule resource to manage, and the services deployed to your own AWS or GCP account.
Create an EventBridge Scheduler schedule whose target is the ECS RunTask API. The schedule names the cluster, the task definition, the launch type and the network configuration, and uses an IAM role that is allowed to call ecs:RunTask and pass the task's roles. Each time the schedule fires, ECS starts a new task that runs to completion.
Yes. It retries when the RunTask call itself fails, up to the retry policy's limits of 185 attempts and 24 hours. Once RunTask succeeds, the schedule has done its job: a container that starts and then exits with an error is not retried. Alert on ECS task state changes with a non-zero exit code to catch those failures.
EventBridge Scheduler starts a new task on every tick, whether or not the previous one has finished. Make the job idempotent, keep its runtime well under the interval, or take a lock at the start, for example a row lock in Postgres, and exit if another run holds it.
Declare the job in code with cron.NewJob, pointing at an API endpoint and an Every interval or a cron Schedule. Cron jobs are managed by the Encore platform and do not run locally or in preview environments, so you call the endpoint yourself when testing.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.