Jobs, hooks and schedules
This page runs jobs when you ask, at points in a deployment’s life and on a
schedule. guestbook has had one job since A seed job:
seed, which runs at every install and update once counter is ready. Each job is a *.job.yaml
file in the app directory, and its context says where it runs. Give
guestbook three more.
count runs inside the running counter service and adds one to the visits.
name: countcontext: serviceservice: countercommand: redis-cli incr visitstimeout: 30on_failure: abortreport starts a container of its own from an image, with the counter’s
volume mounted read-only, and prints what is in it.
name: reportcontext: containerimage: busybox:1.36entrypoint: ["sh", "-c"]command: echo "report for $REPORT_FOR" && ls /dataenvironment: REPORT_FOR: "{{ stack_name }} in {{ environment }}"user: "65534:65534"volumes: - data:/data:rotimeout: 60A container job’s timeout counts from the moment its command starts.
Getting its image onto the node and making and starting its container come
first, under a bound of their own: 15 minutes, or the job’s timeout when
that is longer.
ping-shelf is an HTTP request from the node to the catalogue’s server. It
tries three more times, five seconds apart, before it fails.
name: ping-shelfcontext: httpurl: http://127.0.0.1:18090/index.yamlmethod: GETheaders: Accept: text/yamlmax_retries: 3retry_interval: 5timeout: 30A graphql job posts a query to an endpoint and reads the answer. guestbook
serves no GraphQL, so schema is written to show the shape and never run.
name: schemacontext: graphqlurl: http://127.0.0.1:18090/graphqlquery: | { __schema { queryType { name } } }timeout: 30app.yaml ties them to the deployment’s life. hooks names the jobs that run
at each point, in order: count after every install, report before every
update and ping-shelf after it. crons runs count every five minutes on a
node that holds the deployment. Replace app.yaml.
name: guestbookversion: "1.3.0"title: Guestbookdescription: A page, an API under its path and a countercategory: demohomepage: https://example.com/guestbooksource: https://example.com/guestbook.giticon: icon.svgtags: [demo, redis, nginx]features: [api]hidden: falselicense: id: MITvars: greeting@string!: the line the page answers at /greeting maxSigners@int: how many people may sign open@bool: whether signing is open apiPort@port: the port the API listens on dataPath@path: where the counter keeps its data theme@json: colours the page uses owner: email@email: who runs the guestbook homepage@url:endpoint: the owner's page password@secret: the owner's passwordhooks: post_install: - count pre_update: - report post_update: - ping-shelfcrons: count: "*/5 * * * *"A service job needs a running service, so it may run after install and
around update, backup and restore, never before install. The table of which
context each hook allows is in
Lifecycle hooks.
Update guestbook. The update runs report first and ping-shelf last.
$ shc validate ~/learn/guestbook...$ shc update guestbook...shc job alone lists its verbs. ls lists the jobs SHC knows and show one
job’s definition.
$ shc job...$ shc job ls...$ shc job show count -s guestbook...Run count and wait for it. --wait prints the run’s status and output when
it ends.
$ shc job run count -s guestbook --wait...$ shc exec -s guestbook -S counter -- redis-cli get visits...$ shc job run report -s guestbook --wait...--var overrides one of the deployment’s variables for that run alone, and
the deployment keeps its own.
$ shc job run report -s guestbook --var greeting="For the report." --wait...Without --wait a run is queued and the command prints its number. status
takes that number, or the job’s name for its newest run.
$ shc job run ping-shelf -s guestbook...$ shc job status ping-shelf -s guestbook...$ shc job ps --job ping-shelf --limit 5...$ shc job history --job count --limit 5...ps lists runs still going and history the ones that ended. A run that is
still pending can be cancelled with the reason recorded. A run is pending only
for the moment before a node takes it, so the walk of this page does not type
it.
$ shc job cancel 42 --reason "queued by mistake" --yesThe cron in app.yaml became a schedule for this deployment. schedule
changes it without editing the app: the next update of guestbook puts the
app’s own cron back.
$ shc schedule...$ shc schedule ls -s guestbook...$ shc schedule info count -s guestbook...$ shc schedule edit count "*/10 * * * *" -s guestbook...$ shc schedule disable count -s guestbook...$ shc schedule enable count -s guestbook...add schedules a job the app did not, and rm removes it.
$ shc schedule add report "0 3 * * *" -s guestbook --description "the nightly report"...$ shc schedule ls -s guestbook...$ shc schedule rm report -s guestbook --yes...The cluster runs schedules of its own: maintenance and health checks of its
modules. cron ls lists them with when each fires next.
$ shc cron...$ shc cron ls...Some work can only be done while a service is down: copying a database’s
files, or a migration that must not race the old version. before names a
service and the state it must be in, and the job runs in that gap. On an
update, the service’s old replicas stop, the job runs, and the new replicas
start only once it exits 0; if it fails, so does the update. On an install
there are no old replicas, and the job runs as any start job does.
copy-aof copies Redis’s append-only files while counter is stopped, so
the copy is never half written. A first install has no files yet, so the
job ends at once there.
name: copy-aofcontext: containerimage: busybox:1.36entrypoint: ["sh", "-c"]command: test -d /data/appendonlydir || exit 0; mkdir -p /data/copy && cp -a /data/appendonlydir/. /data/copy/volumes: - data:/databefore: [counter:stopped]timeout: 60Update guestbook, then read the run and the copy. peek shares counter’s
volumes, so it sees the copy beside the files it was made from.
$ shc validate ~/learn/guestbook...$ shc update guestbook...$ shc job history --job copy-aof --limit 1...$ shc exec -s guestbook -S peek -- ls -d /data/copy/data/copy$ shc exec -s guestbook -S counter -- redis-cli pingPONGEvery update of guestbook would now stop counter for the copy. Remove the
job and update again, so the next pages update it with counter running.
$ rm ~/learn/guestbook/copy-aof.job.yaml$ shc update guestbook...Keep guestbook installed for the next page.
Next: Volumes.