Running service broker errands

This topic describes each of the service broker errands and how you can run an errand using the BOSH CLI.

Errands can manage service brokers and run mass operations on service instances created by brokers. To run an errand, see Run an Errand.

For all supported VMware Tanzu SQL with MySQL for VMs errands, see the full errand list:

find-deprecated-bindings
smoke-tests
configure-leader-follower
make-leader
make-read-only
upgrade-all-service-instances
register-broker
delete-all-service-instances-and-deregister-broker
recreate-all-service-instances

Run an errand

To run an errand:

View the BOSH deployment name for your MySQL service broker by running:
```
bosh deployments
```
Run:
```
bosh -d pivotal-mysql-GUID run-errand ERRAND-NAME
```
Where:
- pivotal-mysql-GUID is the BOSH deployment name for your MySQL service broker.
- ERRAND-NAME is the name of the errand you want to run.
For example:
```
$ bosh -d pivotal-mysql-e3ddd36247fe5b923caf run-errand find-deprecated-bindings
```

Available errands

The following sections describe each service broker errand that you can run. To run an errand, see Run an Errand.

find-deprecated-bindings

The find-deprecated-bindings errand does the following:

Lists app bindings and services keys that are deprecated in Tanzu SQL for VMs v2.10. The bindings are deprecated because they do not require TLS.
Exits whether or not a deprecated binding is found.

The find-deprecated-bindings errand has the following example output:

Stdout     +---------------------------+--------------------------------------+------------------------+--------------------------+--------------------+-------------------+-----------------------------+
           |          SERVICE          |             SERVICE GUI             |          ORG           |          SPACE           | APP OR SERVICE KEY |       TYPE        |           REASON            |
           +---------------------------+--------------------------------------+------------------------+--------------------------+--------------------+-------------------+-----------------------------+
           | tlsDB                     | a999db0b-176e-4ac8-8342-d72b338d1f0c | MYSQL-ORG-upgrade-test | MYSQL-SPACE-upgrade-test | user-cli           | ServiceKeyBinding | no tls                      |
           | tlsDB                     | a999db0b-176e-4ac8-8342-d72b338d1f0c | MYSQL-ORG-upgrade-test | MYSQL-SPACE-upgrade-test | user-cli           | ServiceKeyBinding | no dns: hostname="10.0.8.6" |
           | upgrade-outdated-instance | 34f26746-fb46-4f14-87bc-e1ddce26f340 | MYSQL-ORG-upgrade-test | MYSQL-SPACE-upgrade-test | cs-accept          | AppBinding        | no dns: hostname="10.0.8.5" |
           | tlsDB                     | a999db0b-176e-4ac8-8342-d72b338d1f0c | MYSQL-ORG-upgrade-test | MYSQL-SPACE-upgrade-test | cs-accept-tls      | AppBinding        | no dns: hostname="10.0.8.6" |
           +---------------------------+--------------------------------------+------------------------+--------------------------+--------------------+-------------------+-----------------------------+

VMware recommends that operators configure bindings to require TLS. For more information, see Configure TLS.

smoke-tests

The smoke-tests errand does the following:

Validates that the service broker has been installed and configured correctly.
Creates and deletes a new space and service instance that conducts tests.
If this errand runs successfully, Tanzu SQL for VMs has installed successfully.

configure-leader-follower

The configure-leader-follower errand does the following:

Configures replication on the follower and ensures the leader is writable.
Runs after every create or update of a leader-follower instance.
Fails and alerts operators with BOSH errand output if the service instance is in a unhealthy state.

This errand is used to trigger a leader-follower failover. You can use this errand to create custom failover scripts. For more information, see Triggering a Leader-Follower Failover.

make-leader

The make-leader errand does the following:

Promotes a follower VM to a leader.
Removes replication configuration from the VM, waits for all transactions to be applied to the VM, and sets the VM as writable.
Fails if the original leader is still writeable. This protects against data divergence.

This errand is used to trigger a leader-follower failover. You can use this errand to create custom failover scripts. For more information, see Triggering a Leader-Follower Failover.

make-read-only

The make-read-only errand does the following:

Demotes a leader VM to a follower.
Sets the VM to read-only and guarantees that apps no longer write to this VM.
Relays all in-flight transactions on the former leader VM to the follower VM if the follower VM is accessible.

This errand is used to trigger a leader-follower failover. You can use this errand to create custom failover scripts. For more information, see Triggering a Leader-Follower Failover.

upgrade-all-service-instances

The upgrade-all-service-instances errand:

Collects all the service instances that the on-demand broker has registered.
Issues an upgrade command and deploys the a new manifest to the on-demand broker for each service instance.
Adds to a retry list any instances that have ongoing BOSH tasks at the time of upgrade.
Retries any instances in the retry list until all instances are upgraded.

When you make changes to the plan configuration, the errand upgrades all the Tanzu SQL for VMs service instances to the latest version of the plan.

If any instance fails to upgrade, the errand fails immediately. This prevents systemic problems from spreading to the rest of your service instances.

register-broker

The register-broker errand:

Registers the service broker with Cloud Controller.
Activates service access for any plans that are enabled on the tile.
Deactivates service access for any plans that are deactivated on the tile.
Does nothing for any plans that are set to manual on the tile.

Run this errand whenever the broker is re-deployed with new catalog metadata to update the Marketplace.

Plans with deactivated service access are only visible to admin Cloud Foundry users. Non-admin Cloud Foundry users, including Org Managers and Space Managers, cannot see these plans.

delete-all-service-instances-and-deregister-broker

This errand destroys all on-demand service instances and deregisters the broker from the Cloud Controller. Use it with extreme caution.

The delete-all-service-instances-and-deregister-broker errand does the following:

Deactivates service access to the service offering for all orgs and spaces. The errand deactivates service access to ensure that new instances cannot be provisioned during the lifetime of the errand.
Unbinds all apps from the service instances.
Runs any pre-delete errands for each instance.
Deletes the BOSH deployment of each service instance.
Checks for deletion failure of each instance, which results in the errand failing immediately.
Determines whether any instances have been created while the errand was running. If new instances are detected, the errand returns an error. In this case, VMware recommends running the errand again.
Deregisters the broker from the Cloud Controller.

Tanzu Operations Manager runs this errand only when deleting Tanzu SQL for VMs. Running this errand removes all service instances and their data.

recreate-all-service-instances

The recreate-all-service-instances errand recreates all service instance VMs managed by an on-demand broker.

You might want use this errand in the following cases:

Rotating the Tanzu Operations Manager root certificate authority (CA). For more information about rotating CAs, see Rotating CAs and Leaf Certificates.
Fully restoring the platform during disaster recovery or migration.