jobs.html.md.erb

---
title: BOSH Jobs and Errands
---

A BOSH job is a blueprint that describes:

* A set of processes
* Rules for deploying and running the processes
* Resources that the processes need

The creator of a BOSH deployment organizes the processes that need to run in the
deployment into logical groups.
Each group provides a discrete function for the deployment.
BOSH calls these groups **jobs**.
BOSH jobs are the fundamental building blocks of a BOSH deployment.

Using a job as a blueprint, BOSH creates configuration files and software to run
on a VM.
BOSH calls these files and software an **instance** of the job.

There is a one-to-many-to-many mapping between jobs, instances of jobs, and VMs.
Specifically:

* BOSH can create multiple instances from the same job.
* Multiple VMs can each run an instance of the same job.
* Instances created from different jobs can run on the same VM.

For example, four VMs could each run an instance of the Cloud Controller job,
with one VM running both a Cloud Controller job instance and an instance of a
DEA job.

## <a id="jobs-vs-errands"></a>Errands ##

An **errand** is a type of BOSH job that runs once or only on demand. Examples include smoke tests and Cloud Foundry service broker binding.

To distinguish an errand from a job, set the `lifecycle` property for
the errand in the [Jobs Block](./deployment-manifest.html#jobs) of the
deployment manifest to `errand`.
If this property is not set, BOSH uses the default value `service` and
configures instances of the job to run as long as the deployment runs.

<p class="note"><strong>Note</strong>: Since BOSH requests and provisions a new
VM for each errand, the resource pool for a BOSH deployment with errands must
include one additional VM per errand.
If you receive an error message about insufficient VM capacity, you must adjust
the <a href="./deployment-manifest.html#jobs">Jobs Block</a> of your deployment
manifest.</p>
<p class="note"><strong>Note</strong>: Errands do not have a notion of persistence. Persistent disk migration for errands is not supported.</p>

## <a id="job-parts"></a>Parts of a BOSH Job or BOSH Errand ##

Both jobs and errands are defined in a BOSH [release](./create-release.html).

BOSH jobs consist of three parts: specifications, templates, and monitoring.

BOSH errands consist of two parts: specifications and templates.
BOSH does not monitor the health of any processes in instances of an errand.

### <a id="specification"></a>Specifications ###

A job specification, or **spec**, is a YAML document that lists:

* Required [packages](./packages.html): A package contains source code and a script. The script describes how to compile the source code and install the resultant binary. Optionally, a package can contain the names of other packages this package depends on.
* Job templates: The names and file paths to [job templates](#templates) that the job uses.
* Job properties: BOSH uses job properties when creating an instance of a job. Typical job properties include account names, passwords, shared secrets, hostnames, IP addresses, port numbers, and descriptions.

### <a id="templates"></a>Templates ###

Templates contain information shared across jobs or errands, such as account
names and passwords.
Templates consist of plain text and Ruby code for variable substitution and flow
control.
BOSH evaluates these templates as Ruby ERB template files when creating an
instance of a job.

At compile time, BOSH uses job templates to create the control scripts and
configuration files that the BOSH [agent](./terminology.html#agent) needs to run
the processes in a job instance.

### <a id="monitoring"></a>Monitoring ###

#### <a id="job-monitoring"></a>Job Monitoring ####

BOSH uses [monit](http://mmonit.com/monit/) to manage and monitor the health of
processes in an instance of a job.
Using `monit`, BOSH can start, stop, and restart instances of a job when
necessary.

A functioning `monit` requires, at a minimum, three parts for each process in a
job:

* `with pidfile`: Name and path to the file containing the process ID (PID)
* `start program`: Command `monit` uses to start the process
* `stop program`: Command `monit` uses to stop the process

See the [monit file example](#running-jobs).

<p class="note"><strong>Note</strong>: When developing or testing a release, you can use an empty <code>monit</code> file.</p>

#### <a id="errand-monitoring"></a>Errand Monitoring ####

BOSH does not monitor the health of any processes in an instance of an errand.

## <a id="running"></a>Running Jobs and Errands ##

BOSH ensures an instance of a job or errand always runs in a predictable,
deterministic environment by creating a new VM specifically for the instance.

### <a id="running-jobs"></a>Running Jobs ###

BOSH creates instances of the job on VMs as part of the deployment process.
BOSH monitors the instances it deploys and restarts any that fail, keeping them
running for as long as the deployment runs.

BOSH runs jobs using the commands provided in the `monit` file.

Example `monit` file:

<pre class="terminal">
check process postgres
  with pidfile /var/vcap/sys/run/postgres/postgres.pid
  start program "/var/vcap/jobs/postgres/bin/postgres_ctl start"
  stop program "/var/vcap/jobs/postgres/bin/postgres_ctl stop"
</pre>

#### <a id="canceling-jobs"></a>Canceling Jobs ####

You cannot cancel jobs.

### <a id="errand-running"></a>Running Errands ###

An operator runs a BOSH errand using the `bosh run errand` command.
To facilitate this, an errand defined in a BOSH release must provide an
executable `/bin/run` script.

BOSH does the following when it runs an errand:

1. Initiates a deployment lock that does the following:
 * Prevents all other deploys
 * Prevents the running of the BOSH CLI `cloudcheck` command
 * Prevents the health monitor from scanning and fixing current deployments
1. Provisions and configures the VM for the errand
1. Installs the errand code and all required packages and templates
1. Runs the processes specified by the errand
1. Sends all output of the errand to the BOSH CLI for output
1. Releases the deployment lock
1. Releases the VM back into the resource pool

Use `bosh run errand ERRAND-NAME` to run an errand. ERRAND-NAME must be the name of an errand provided in the deployment manifest.

Example:

<pre class="terminal">
$ bosh run errand smoke-test
</pre>

The `bosh run errand` command compiles all packages that the errand requires
and executes the `/bin/run` script that the BOSH release provides for the
errand.

**Example Executable /bin/run Script**

This is an example `/bin/run` script for a BOSH errand that de-registers a
service broker.

<pre class="bash">
#!/bin/bash

set -e

export PATH=$PATH:/var/vcap/packages/ruby/bin

cd /var/vcap/packages/broker-registrar

bundle exec ./bin/broker-registrar delete                \
    --cf-address '&lt;%= p("cf.api_url") %&gt;'                \
    --cf-username '&lt;%= p("cf.admin_username") %&gt;'        \
    --cf-password '&lt;%= p("cf.admin_password") %&gt;'        \
    --broker-name '&lt;%= p("broker.name") %&gt;'              \
    --broker-url 'http://&lt;%= p("broker.host") %&gt;:&lt;%= p("broker.port") %&gt;' \
    --broker-username '&lt;%= p("broker.username") %&gt;'      \
    --broker-password '&lt;%= p("broker.password") %&gt;'
</pre>

#### <a id="canceling-jobs"></a>Canceling Errands ####

Use `bosh cancel task <task_id>` to cancel a running errand.

<pre class="terminal">
$ bosh cancel task 123
</pre>

The `bosh cancel task` command terminates the errand process, releases the
deployment lock, and returns the errand VM to the resource pool.