Migrate a9s PostgreSQL Custom Parameters

info

Due to the changes in the underlying schema of custom parameters of a9s PostgreSQL in v77.0.0, it is important to ensure the migration of custom parameters for all existing PostgreSQL Service Instances. This manual serves as a guide for the migration of custom parameters for the deleted, stopped & failed PostgreSQL Service Instances. This migration is to update the internal data structure only; meanwhile, the old schema remains backward-compatible until its planned removal in v80.0.0.

Pre-requisites

Before upgrading to v77.0.0, ensure that a backup is performed for all a9s PostgreSQL Service Instances via the platform backup framework. See Backups and Restores

Instructions

Updating the Deployments & Service Instances

Once the backups are created, perform the following steps in the stated order:

• Re-deploy the a9s PostgreSQL Data Service as usual using the latest manifest from the anynines-deployment v77.0.0.
• Execute the templates-uploader BOSH errand.
• Update all existing a9s PostgreSQL Service Instances to trigger the automatic migration of the internal custom parameter structure. This can be done by executing the deployment-updater errand, see a9s Deployment Updater.
• Execute the rake task to perform the migration of custom parameters for deleted, stopped and failed Service Instances because these states are skipped for updates by the a9s Deployment Updater.

Executing the manual task

This task targets the migration of custom parameters for stopped, deleted and failed PostgreSQL Service Instances that are not automatically migrated by the a9s Deployment Updater.

On the respective a9s Service Broker Virtual Machine, execute the following rake task:

sudo -i
/var/vcap/jobs/anynines-service-broker/bin/rake custom_params:<action>

where action can be selected from the following list of actions:

Action	Description
help	Displays information about the usage, arguments and environment.
list_services	Displays information about the catalog services with plan and instance counts.
plan[a9s-postgresql<version>,<targeted-state>]	Displays information about which instances will be effected if an apply is run with the mentioned version and targeted-state. Note that mentioning no state will set the default target states to deleted, stopped and failed.
apply[a9s-postgresql<version>,<targeted-state>]	Performs the migration on the targeted Service Instances.

Tips

• It is recommended to execute the plan command first to have an overview of the Service Instances that will be impacted by the arguments. Once the report provided by plan has been read and validated, execute the apply command with the same arguments to perform the migration.

• Each time the Rake task is executed, an undo log containing one JSON record for each instance visited is written. Each entry includes the before and after state of every key touched. The path for undo logs can be seen in the output of plan action.

Examples

The following example shows the list of Postgresql 15 Service Instances in stopped state that will be targeted if an apply action is run with the mentioned version and state:

sudo -i
/var/vcap/jobs/anynines-service-broker/bin/rake custom_params:plan[a9s-postgresql15,stopped]

Multiple states can also be targeted via a comma separated list:

sudo -i
/var/vcap/jobs/anynines-service-broker/bin/rake custom_params:plan[a9s-postgresql15,stopped,failed]

The example below performs the migration on all Postgresql 15 Service Instances in stopped state:

sudo -i
/var/vcap/jobs/anynines-service-broker/bin/rake custom_params:apply[a9s-postgresql15,stopped]

warning

The Platform Operator is responsible to check for existing Service Instances of all PostgreSQL versions services and ensure the execution of the Migration task for the Service Instances of each version respectively.

Mentioning no state, like in the example below, will result in the migration to be performed on all the default states for this task i.e. deleted, stopped and failed.

sudo -i
/var/vcap/jobs/anynines-service-broker/bin/rake custom_params:apply[a9s-postgresql15]

info

Both tasks are safe to repeat: apply skips instances already migrated, and plan never performs migration.

Optional Environment Arguments

Adding CONFIRM=yes to the command that executes the Rake task pre-answers the confirmation prompt that apply asks for before it writes. For example:

sudo -i
/var/vcap/jobs/anynines-service-broker/bin/rake CONFIRM=yes custom_params:apply[a9s-postgresql15]

A path for UNDO_LOG_DIR can be passed to specify a directory for the undo log. The value for this argument defaults to LOG_DIR, the job's log directory on a BOSH VM, then to the application's log directory. The run refuses to start if the file cannot be created.