Skip to content
SHC Docs

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.

~/learn/guestbook/count.job.yaml
name: count
context: service
service: counter
command: redis-cli incr visits
timeout: 30
on_failure: abort

report starts a container of its own from an image, with the counter’s volume mounted read-only, and prints what is in it.

~/learn/guestbook/report.job.yaml
name: report
context: container
image: busybox:1.36
entrypoint: ["sh", "-c"]
command: echo "report for $REPORT_FOR" && ls /data
environment:
REPORT_FOR: "{{ stack_name }} in {{ environment }}"
user: "65534:65534"
volumes:
- data:/data:ro
timeout: 60

A 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.

~/learn/guestbook/ping-shelf.job.yaml
name: ping-shelf
context: http
url: http://127.0.0.1:18090/index.yaml
method: GET
headers:
Accept: text/yaml
max_retries: 3
retry_interval: 5
timeout: 30

A 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.

~/learn/guestbook/schema.job.yaml
name: schema
context: graphql
url: http://127.0.0.1:18090/graphql
query: |
{
__schema {
queryType { name }
}
}
timeout: 30

app.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.

~/learn/guestbook/app.yaml
name: guestbook
version: "1.3.0"
title: Guestbook
description: A page, an API under its path and a counter
category: demo
homepage: https://example.com/guestbook
source: https://example.com/guestbook.git
icon: icon.svg
tags: [demo, redis, nginx]
features: [api]
hidden: false
license:
id: MIT
vars:
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 password
hooks:
post_install:
- count
pre_update:
- report
post_update:
- ping-shelf
crons:
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.

home01
$ 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.

home01
$ 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.

home01
$ 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.

home01
$ 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.

home01
$ 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.

explained, not walked: a run is pending only for a moment
$ shc job cancel 42 --reason "queued by mistake" --yes

The 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.

home01
$ 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.

home01
$ 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.

home01
$ 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.

~/learn/guestbook/copy-aof.job.yaml
name: copy-aof
context: container
image: busybox:1.36
entrypoint: ["sh", "-c"]
command: test -d /data/appendonlydir || exit 0; mkdir -p /data/copy && cp -a /data/appendonlydir/. /data/copy/
volumes:
- data:/data
before: [counter:stopped]
timeout: 60

Update 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.

home01
$ shc validate ~/learn/guestbook
...
$ shc update guestbook
...
$ shc job history --job copy-aof --limit 1
...
home01
$ shc exec -s guestbook -S peek -- ls -d /data/copy
/data/copy
$ shc exec -s guestbook -S counter -- redis-cli ping
PONG

Every 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.

home01
$ rm ~/learn/guestbook/copy-aof.job.yaml
$ shc update guestbook
...

Keep guestbook installed for the next page.

Next: Volumes.