Using Errands
(See Jobs for an introduction to jobs.)
Any job that includes bin/run
script in its spec file's templates section is considered to be an errand. Operator can trigger execution of an errand at any time after the deploy and receive back script's stdout, stderr and exit code upon its completion.
Errand output is limited to one megabyte of data. If the response is larger an error will be returned instead. Release authors should ensure the full error is properly logged to disk and a summary is returned as output.
Release Definition¶
Example of an errand job smoke-tests
from Zookeeper release. bin/run
script is specified in its templates section:
--- name: smoke-tests templates: run.sh: bin/run consumes: - name: conn type: zookeeper properties: - client_port packages: - smoke-tests properties: {}
with a run.sh
template:
#!/bin/bash set -e <% conn = link('conn') %> export ZOOKEEPER_SERVERS=<%= conn.instances.map { |i| "#{i.address}:#{conn.p('client_port')}" }.join(",") %> /var/vcap/packages/smoke-tests/bin/tests
Include in a Deployment¶
There are two ways to add an errand to a deployment:
- add it to a dedicated instance group
- add it to an existing instance group (colocated) (available in bosh-release v263+)
In some cases it makes sense to place an errand in a dedicated instance group. You can add an instance group that specifies only an errand job in its jobs section:
- name: smoke-tests azs: [z1] lifecycle: errand instances: 1 jobs: - name: smoke-tests release: zookeeper properties: {} vm_type: default stemcell: default networks: - name: default
Note that above example uses lifecycle: errand
configuration to specify that smoke-tests
instances should only be present when the smoke-tests
errand is running. Cloud compute resources will be allocated right before errand is running and released when errand is finished.
Alternatively, it might make sense to colocate an errand job with other jobs in an existing instance group. This might be useful if an errand is meant to perform work local to an instance or simply to avoid adding additional resources to your deployment:
- name: zookeeper azs: [z1, z2, z3] instances: 1 jobs: - name: zookeeper release: zookeeper properties: {} - name: status release: zookeeper properties: {} vm_type: default persistent_disk: 10240 stemcell: default networks: - name: default
Execution¶
Unlike regular jobs which run continiously and get automatically restarted on failure, errand jobs are executed upon operator's request some time after a deploy and if fail do not get restarted. There is no timeout on how long an errand can execute.
Note that currently Director will acquire deployment lock for chosen deployment which will prevent execution of other commands that also require deployment lock (for example bosh deploy
or another errand execution). This behaviour will be made more granular over time allowing more commands to run in parallel against a single deployment.
After running bosh deploy
command to update your deployment, you can inspect which errands are available within a deployment via bosh errands
command:
bosh -e vbox -d zookeeper errands
Should result in:
Using environment '192.168.56.6' as client 'admin' Using deployment 'zookeeper' Name smoke-tests status 2 errands Succeeded
To execute an errand, use bosh run-errand
command.
bosh -e vbox -d zookeeper run-errand status
Should result in:
Using environment '192.168.56.6' as client 'admin' Using deployment 'zookeeper' Task 5609 Task 5609 | 01:31:57 | Preparing deployment: Preparing deployment (00:00:01) Task 5609 | 01:31:58 | Running errand: zookeeper/0015b995-5ec3-4519-8c11-6521b0aa079d (3) Task 5609 | 01:31:58 | Running errand: zookeeper/e31944b9-8bf5-4a42-8d6b-3402a85d24d8 (0) Task 5609 | 01:31:58 | Running errand: zookeeper/3e977542-d53e-4630-bc40-72011f853cb5 (4) Task 5609 | 01:31:58 | Running errand: zookeeper/671d5b1d-0310-4735-8f58-182fdad0e8bc (1) Task 5609 | 01:31:58 | Running errand: zookeeper/d9e00366-8ab1-4ea2-bae3-14cd6bf562cd (2) Task 5609 | 01:31:59 | Running errand: zookeeper/0015b995-5ec3-4519-8c11-6521b0aa079d (3) (00:00:01) Task 5609 | 01:31:59 | Fetching logs for zookeeper/0015b995-5ec3-4519-8c11-6521b0aa079d (3): Finding and packing log files Task 5609 | 01:31:59 | Running errand: zookeeper/e31944b9-8bf5-4a42-8d6b-3402a85d24d8 (0) (00:00:01) Task 5609 | 01:31:59 | Fetching logs for zookeeper/e31944b9-8bf5-4a42-8d6b-3402a85d24d8 (0): Finding and packing log files Task 5609 | 01:31:59 | Running errand: zookeeper/d9e00366-8ab1-4ea2-bae3-14cd6bf562cd (2) (00:00:01) Task 5609 | 01:31:59 | Fetching logs for zookeeper/d9e00366-8ab1-4ea2-bae3-14cd6bf562cd (2): Finding and packing log files Task 5609 | 01:32:00 | Fetching logs for zookeeper/0015b995-5ec3-4519-8c11-6521b0aa079d (3): Finding and packing log files (00:00:01) Task 5609 | 01:32:00 | Running errand: zookeeper/3e977542-d53e-4630-bc40-72011f853cb5 (4) (00:00:02) Task 5609 | 01:32:00 | Running errand: zookeeper/671d5b1d-0310-4735-8f58-182fdad0e8bc (1) (00:00:02) Task 5609 | 01:32:00 | Fetching logs for zookeeper/e31944b9-8bf5-4a42-8d6b-3402a85d24d8 (0): Finding and packing log files (00:00:01) Task 5609 | 01:32:00 | Fetching logs for zookeeper/d9e00366-8ab1-4ea2-bae3-14cd6bf562cd (2): Finding and packing log files (00:00:01) Task 5609 | 01:32:00 | Fetching logs for zookeeper/671d5b1d-0310-4735-8f58-182fdad0e8bc (1): Finding and packing log files Task 5609 | 01:32:00 | Fetching logs for zookeeper/3e977542-d53e-4630-bc40-72011f853cb5 (4): Finding and packing log files Task 5609 | 01:32:01 | Fetching logs for zookeeper/671d5b1d-0310-4735-8f58-182fdad0e8bc (1): Finding and packing log files (00:00:01) Task 5609 | 01:32:01 | Fetching logs for zookeeper/3e977542-d53e-4630-bc40-72011f853cb5 (4): Finding and packing log files (00:00:01) Task 5609 Started Mon Sep 18 01:31:57 UTC 2017 Task 5609 Finished Mon Sep 18 01:32:01 UTC 2017 Task 5609 Duration 00:00:04 Task 5609 done Instance zookeeper/0015b995-5ec3-4519-8c11-6521b0aa079d Exit Code 0 Stdout Mode: leader Stderr ZooKeeper JMX enabled by default Using config: /var/vcap/jobs/zookeeper/config/zoo.cfg Instance zookeeper/3e977542-d53e-4630-bc40-72011f853cb5 Exit Code 0 Stdout Mode: follower Stderr ZooKeeper JMX enabled by default Using config: /var/vcap/jobs/zookeeper/config/zoo.cfg Instance zookeeper/671d5b1d-0310-4735-8f58-182fdad0e8bc Exit Code 0 Stdout Mode: follower Stderr ZooKeeper JMX enabled by default Using config: /var/vcap/jobs/zookeeper/config/zoo.cfg Instance zookeeper/d9e00366-8ab1-4ea2-bae3-14cd6bf562cd Exit Code 0 Stdout Mode: follower Stderr ZooKeeper JMX enabled by default Using config: /var/vcap/jobs/zookeeper/config/zoo.cfg Instance zookeeper/e31944b9-8bf5-4a42-8d6b-3402a85d24d8 Exit Code 0 Stdout Mode: follower Stderr ZooKeeper JMX enabled by default Using config: /var/vcap/jobs/zookeeper/config/zoo.cfg 5 errand(s) Succeeded
If an errand job is colocated on multiple instances (over one or more instance groups), by default bosh run-errand
command will execute them all in parallel. You can limit number of instances used for execution via --instance
flag:
bosh -e vbox -d zookeeper run-errand status --instance zookeeper/3e977542-d53e-4630-bc40-72011f853cb5
See bosh run-errand
command description for additional ways to use --instance
flag. One of those way is to use --instance group/first
(where first
is a literal value) so that errand only runs on one of the instances.