Using BOSH errands with your tile

Life cycle errands are BOSH errands (scripts) that run at the beginning and end of an installed product’s availability time. Product teams create errands as part of a product package, and a product can only run errands the package includes.

About BOSH errands

In Tanzu Operations Manager v2.0 and later, you can select co-located errands on existing VMs. When errands are not co-located, BOSH deploys a new VM for each errand defined in the tile metadata. Co-located errands can run alongside other jobs or errands on existing VMs in an operator’s deployment.

Products can have two kinds of errands:

Post-deploy errands run after a product installs but before Tanzu Operations Manager makes it available for use.
Pre-delete errands run after you delete a product, but before Tanzu Operations Manager finishes removing it from use.

To save deployment time, you can set errand run rules that dictate whether errands run. Tile authors can set defaults for these run rules.

For more information about:

BOSH errands, see the BOSH documentation.
Errands in Tanzu Operations Manager, see Managing errands in Tanzu Operations Manager.

Define a co-located errand

System tests might incur costs from using third-party services, IaaS resources, and others.

Rather than deploying a new VM for each errand, co-located errands run on an existing VM. Errands can run alongside other jobs on a VM, and multiple errands can be co-located on the same VM. Co-located errands run faster than traditional errands and use less disk and IP space.

To configure a co-located errand, define the following properties in the pre_delete_errands and post_deploy_errands sections of the tile metadata.

Property	Description
`name: MY-ERRAND`	Provide the name of the errand job. The example manifest in the following section uses "`example_colocated_errand`."
`colocated: true`	Set this value to `true` to enable co-located errands. If you do not set this value, Tanzu Operations Manager ignores all other errand attributes in this section.
`run_default: on`	(Optional) You can set the run rules to `on` or `off`. See Errand Run Rules for more information. If you do not define this property, Tanzu Operations Manager sets the run default to `on`. The operator can override this setting using the Tanzu Operations Manager API or the tile's Errand Config tab.
`instances: []`	(Optional) Provide an array that tells BOSH where to run the errand. Use the name of an instance group, such as `web_server`, or a single instance, such as `web_server/first`. If you do not define this property or you provide an empty array, the errand runs on every instance of the job in the operator's deployment.
`label: ERRAND-LABEL`	Define the errand name to be shown in the tile's Errand Config tab and above Apply Changes. The example manifest in the following section uses "`colocated errand on web_server`."
`description: TEXT`	(Optional) Provide a description for the errand. The description you set appears in the tile's Errand Config tab.
`impact_warning: TEXT`	(Optional) Provide an impact warning to appear in the Review Pending Changes tab before running the errand.

After you define the errand as described, add the errand to the job properties in the job_types section.

Co-located errand example manifest

The following example shows co-located post_deploy_errands and pre_delete_errands sections in the tile metadata.

post_deploy_errands:
  - name: example-errand
    colocated: false
    impact_warning: "This is an impact warning for your post-deploy errand."
  - name: example_colocated_errand
    colocated: true
    run_default: on
    instances:
      - web_server/first
    label: colocated errand on web_server
    description: This errand prints a message to prove co-located errands work.

pre_delete_errands:
  - name: example-errand
    impact_warning: "This is an impact warning for your pre-delete errand."

The following example shows the co-located errands referenced in the job_type:

job_types:
 - name: web_server
    resource_label: Web Server
    templates:
      - name: web_server
        release: example-release
        provides: |
          web_server_info: (( .properties.example_selector.selected_option.parsed_manifest(provides_section) ))
        consumes: |
          web_server_info: (( .properties.example_selector.selected_option.parsed_manifest(consumes_section) ))
      - name: time_logger
        release: example-release
      - name: example_colocated_errand
        release: example-release
    release: example-release
    static_ip: 1
    dynamic_ip: 0
    max_in_flight: 1

Post-deploy errands

Post-deploy errands run after a product is installed, but before Tanzu Operations Manager makes it available for use.

Typical post-deploy errands include smoke tests or acceptance tests, database initialization or database migration, and service broker registration.

Post-deploy errands run by default. You can prevent a post-deploy errand from running by setting the run rule to Off under Pending Changes in the Tanzu Operations Manager Installation Dashboard or on the service’s Settings tab Errands pane, before you install the product.

This is an example of an Errand in the Settings tab of a MySQL for VMs service.

For example, Redis has a Broker Registrar post-deploy errand that the VMware Tanzu Application Service for VMs tile uses to register its service broker with the Cloud Controller. It also publishes the service plans.

If you select Off from the drop-down menu for Redis’s Broker Registrar errand before installation, the Redis service broker is not registered with the Cloud Controller and the service plans are not made public.

Pre-delete errands

Pre-delete errands run after you choose to delete a product, but before Tanzu Operations Manager finishes deleting it.

Typical pre-delete errands include cleanup of application artifacts and service broker de-registration.

For example, VMware Tanzu SQL [MySQL] has a Broker Deregister pre-delete errand that:

Purges the service offering
Purges all service instances
Purges all application bindings
Deletes the service broker from the Cloud Controller

When you choose to delete the VMware Tanzu SQL [MySQL] product, Tanzu Operations Manager first runs the Broker Deregister pre-delete errand, and then deletes the product.

Pre-delete errands run by default. You can prevent a pre-delete errand from running by setting the run rule to Off under Pending Changes in the Tanzu Operations Manager Installation Dashboard or on the product tile’s Settings tab, Errands pane, before installing the product.

Errand run rules

Some errands do not always need to run. For example, installing a minor patch to a existing service might not require re-registering its broker. Tanzu Operations Manager lets you save installation time by turning errands off or on.

Errand run rules are set in two places:

One-Time Rules under Pending Changes in the Tanzu Operations Manager Installation Dashboard. These rules only apply to the next time you run Apply Changes and do not persist after the next successful installation.
Persistent Rules in the tile’s Errands pane. These rules persist through subsequent installations, until changed in the Errands pane.

For more information, see Managing errands in your Tanzu Operations Manager deployment.