Run a command on a schedule
Add a scheduled job that runs a command in the app's image, with its whole environment, on one of its machines.
The job runs /bin/sh -c "<command>" in the app's image, with its whole environment (variables,
secrets and database bindings) on one of the app's machines. Replace app-id with the app's
id and job-id with the job's id.
Prerequisites
- An image that contains
/bin/sh. You can add a job before the app is deployed; it starts running once the app is deployed and its machine reports in. - Permission for
deploy:CreateJobon the app;deploy:RunJobto run it now,deploy:DescribeJobsto read its runs,deploy:UpdateJobto change, enable or disable it,deploy:DeleteJobto delete it. - In the console, also
deploy:DescribeAppto open the app's page (without it the page is not found).
Add the job
- Open the app's Scheduled jobs tab, then choose Add job.
- For Name, enter
nightly-cleanup. - For Schedule, enter
0 3 * * *, or choose a preset. The schedule is stated in words with its next run times. - For Command, enter
node bin/cleanup.js. - (Optional) For a compose app, for Service, choose the service whose image and environment the job runs with.
- (Optional) For Timeout (minutes), enter a value. The default is 60.
- (Optional) Turn on Start even if the previous run is still going (
concurrencyallow). - Choose Add job. The job is listed with its next run and a switch that enables or disables it.
dcloud deploy jobs create app-id --name nightly-cleanup \
--schedule '0 3 * * *' --command 'node bin/cleanup.js'
dcloud deploy jobs run app-id job-idPOST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/jobs
{ "name": "nightly-cleanup", "schedule": "0 3 * * *", "command": "node bin/cleanup.js" }resource "dcloud_app_job" "nightly_cleanup" {
app_id = dcloud_app.web.id
name = "nightly-cleanup"
schedule = "0 3 * * *"
command = "node bin/cleanup.js"
timeout_sec = 900
concurrency = "skip"
}A second job with the same name is refused with 409 "This app already has a job named
"nightly-cleanup"", and a job over the app's job quota with 409 "Quota exceeded: …".
Run now starts a job outside its schedule; the machine picks it up on its next poll. Before
any machine of the app has reported in, it is refused with 409 "The app has no machine that has
reported in yet. Deploy it first". Every run, with
its exit code and the last lines it printed, is listed under the job's runs (View runs), and is a
line in the app's activity.
Job settings
| Field | Rule | Default |
|---|---|---|
name |
lowercase letters, digits and hyphens, at most 63 characters; unique within the app | required |
schedule |
five-field cron in UTC: minute hour day-of-month month day-of-week; *, a-b, */n, lists, jan–dec, sun–sat; or @hourly … @yearly |
required |
command |
run with /bin/sh -c; the image needs a shell |
required |
service |
compose apps: whose image and environment the job runs with | the published service |
timeoutSec |
10–86400; the run is stopped and recorded as timed_out after this long |
3600 |
concurrency |
skip: a run due while the previous one is still going is recorded as skipped; allow: it starts anyway |
skip |
enabled |
a disabled job is not run on schedule; Run now still works | true |
When day-of-month and day-of-week are both set, a day matching either fires, as in cron: 0 0 1 * 1
runs on the 1st and on every Monday. Only UTC is supported.
What a run sees
The image of the deployment that is live, and the environment as of that deployment: a variable
saved without redeploying reaches jobs when it reaches the app. For a compose app the job joins the
app's network, so db resolves as it does for the services. A run that is due while the machine is
down is not run late. Where the job runs is in
What runs on your machines.
Run outcomes
Each run is succeeded (exit 0), failed, timed_out, skipped, or lost (the machine stopped
reporting on it, or no machine picked up a run-now within ten minutes). The last 100 lines of output
are kept with the run; the newest 500 runs of each job are kept. A failed, timed-out or lost run
emails the organization's owners and admins, at most once a day per job while it keeps failing; the
first failure after a success is emailed at once.
Result
The job runs on its schedule on one of the app's machines. How many jobs an app may have is a quota; see Quotas.