Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Elastic Whenever

Build Status MIT License Gem Version

Manage ECS scheduled tasks like Whenever gem.


Add this line to your application's Gemfile:

gem 'elastic_whenever'

And then execute:

$ bundle

Or install it yourself as:

$ gem install elastic_whenever


You can use it almost like Whenever. However, please be aware that you must specify an identifier.

$ elastic_whenever --help
Usage: elastic_whenever [options]
    -i, --update identifier          Clear and create scheduled tasks by schedule file
    -c, --clear identifier           Clear scheduled tasks
    -l, --list identifier            List scheduled tasks
    -s, --set variables              Example: --set 'environment=staging'
        --cluster cluster            ECS cluster to run tasks
        --task-definition task_definition
                                     Task definition name, If omit a revision, use the latest revision of the family automatically. Example: --task-deifinition oneoff-application:2
        --container container        Container name defined in the task definition
        --launch-type launch_type    Launch type. EC2 or FARGATE. Default: EC2
        --assign-public-ip           Assign a public IP. Default: DISABLED (FARGATE only)
        --security-groups groups     Example: --security-groups 'sg-2c503655,sg-72f0cb0a' (FARGATE only)
        --subnets subnets            Example: --subnets 'subnet-4973d63f,subnet-45827d1d' (FARGATE only)
        --platform-version version   Optionally specify the platform version. Default: LATEST (FARGATE only)
    -f, --file schedule_file         Default: config/schedule.rb
        --iam-role name              IAM role name used by CloudWatch Events. Default: ecsEventsRole
        --rule-state state           The state of the CloudWatch Events Rule (ENABLED or DISABLED), default: ENABLED
        --profile profile_name       AWS shared profile name
        --access-key aws_access_key_id
                                     AWS access key ID
        --secret-key aws_secret_access_key
                                     AWS secret access key
        --region region              AWS region
    -v, --version                    Print version
    -V, --verbose                    Run rake jobs without --silent

NOTE: Currently, Elastic Whenever supports the Whenever syntax partially. We strongly encourage to use dry-run mode for verifying tasks to be created.

$ elastic_whenever --cluster ecs-test --task-definition example:2 --container cron
cron(0 3 * * ? *) ecs-test example:2 cron bundle exec rake hoge:run

## [message] Above is your schedule file converted to scheduled tasks; your scheduled tasks was not updated.
## [message] Run `elastic_whenever --help' for more options.

Setting variables

Elastic Whenever supports setting variables via the --set option as Whenever does.


elastic_whenever --set 'environment=staging&some_var=foo'

if @environment == 'staging'
  every '0 1 * * *' do
    rake 'some_task_on_staging'
elsif @some_var == 'foo'
  every '0 10 * * *' do
    rake 'some_task'

Especially, @environment defaults to "production".

How it works

Elastic Whenever creates CloudWatch Events for every command. Each rule has a one to one mapping to a target. for example, the following input will generate two Rules each with one Target.

every '0 0 * * *' do
  rake "hoge:run"
  command "awesome"

The scheduled task's name is a digest value calculated from an identifier, commands, and so on.

NOTE: You should not use the same identifier across different clusters because CloudWatch Events rule names are unique across all clusters.

Compatibility with Whenever


Whenever supports custom job type with job_type method, but Elastic Whenever doesn't support it.

# [warn] Skipping unsupported method: job_type
job_type :awesome, '/usr/local/bin/awesome :task :fun_level'


Whenever supports environment variables with env method, but Elastic Whenever doesn't support it. You should use task definitions to set environment variables.

# [warn] Skipping unsupported method: env
env "VERSION", "v1"


Whenever has a template to describe as cron, but Elastic Whenever doesn't have the template. Therefore, :job_template option is ignored.

set :job_template, "/bin/zsh -l -c ':job'" # ignored


Elastic Whenever processes frequency passed to every block almost like Whenever.

# Whenever
#   0 15 * * * /bin/bash -l -c 'cd /home/user/app && RAILS_ENV=production bundle exec rake hoge:run --silent'
# Elastic Whenever
#   cron(0 15 * * ? *) ecs-test myapp:2 web bundle exec rake hoge:run --silent
every :day, at: "3:00" do
  rake "hoge:run"

# Whenever
#   0,10,20,30,40,50 * * * * /bin/bash -l -c 'awesome'
# Elastic Whenever
#   cron(0,10,20,30,40,50 * * * ? *) ecs-test myapp:2 web awesome
every 10.minutes do
  command "awesome"

However, handling of the day of week is partially different because it follows scheduled expression.

# Whenever
#   0 0 * * 1 /bin/bash -l -c 'awesome'
# Elastic Whenever
#   cron(0 0 ? * 2 *) ecs-test myapp:2 web awesome
every :monday do
  command "awesome"

Therefore, cron syntax is converted to scheduled expression like the following:

# cron(0 0 ? * 2 *) ecs-test myapp:2 web awesome
every "0 0 * * 1" do
  command "awesome"

Absolutely, you can also write scheduled expression.

# cron(0 0 ? * 2 *) ecs-test myapp:2 web awesome
every "0 0 ? * 2 *" do
  command "awesome"


Whenever supports :reboot as a cron option, but Elastic Whenever doesn't support it.

# [warn] `reboot` is not supported option. Ignore this task.
every :reboot do
  rake "hoge:run"

Bundle commands

Whenever checks if the application uses bundler and automatically adds a prefix to commands. However, Elastic Whenever always adds a prefix on a premise that the application is using bundler.

# Whenever
#   With bundler    -> bundle exec rake hoge:run
#   Without bundler -> rake hoge:run
# Elastic Whenever
#   bundle exec rake hoge:run
rake "hoge:run"

If you don't want to add the prefix, set bundle_command to empty as follows:

set :bundle_command, ""


Whenever supports runner job with old Rails versions, but Elastic Whenever supports Rails 4 and above only.

# Whenever
#   Before them -> script/runner
#   Rails 3     -> script/rails runner
#   Rails 4     -> bin/rails runner
# Elastic Whenever
#   bin/rails runner
runner ""


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at