Running Errands

Page last updated:

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

Overview

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

For all supported MySQL for Pivotal Platform errands, see the full errand list:

Run an Errand

To run an errand:

  1. View the BOSH deployment name for your MySQL service broker by running:

    bosh deployments
    
  2. 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 above.

find-deprecated-bindings

The find-deprecated-bindings errand does the following:

  • Lists app bindings and services keys that are deprecated in MySQL for Pivotal Platform v2.7. 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, MySQL for Pivotal Platform 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 also 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 also 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 also 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 does the following:

  • Collects all of 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 MySQL for Pivotal Platform 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 does the following:

  • Registers the service broker with Cloud Controller.
  • Enables service access for any plans that are enabled on the tile.
  • Disables service access for any plans that are disabled on the tile.
  • Does nothing for any plans that are set to manual on the tile.

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

Plans with disabled 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

Warning: This errand destroys all of the 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:

  • Disables service access to the service offering for all orgs and spaces. The errand disables 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.

Ops Manager runs this errand only when deleting MySQL for Pivotal Platform. 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 Ops Manager root certificate authority (CA). For more information about rotating CAs, see Rotate CAs and Leaf Certificates.
  • Fully restoring the platform during disaster recovery or migration.