TPA hooks v23

TPA can set up fully-functional clusters with no user intervention, and already provides a broad variety of settings to control your cluster configuration, including custom repositories and packages, custom Postgres configuration (both pg_hba.conf and postgresql.conf), and so on.

You can write hook scripts to address specific needs that are not met by the available configuration settings. Hooks allow you to execute arbitrary Ansible tasks during the deployment.

Hooks are the ultimate extension mechanism for TPA, and there is no limit to what you can do with them. Please use them with caution, and keep in mind the additional maintenance burden you are taking on. The TPA developers have no insight into your hook code, and cannot guarantee compatibility between releases beyond invoking hooks at the expected stage.

Summary

If you create files with specific names under the hooks subdirectory of your cluster directory, TPA will invoke them at various stages of the deployment process, as described below.

$ mkdir ~/clusters/speedy/hooks
$ cat > ~/clusters/speedy/hooks/pre-deploy.yml
---
- debug: msg="hello world!"

Hook scripts are invoked with include_tasks, so they are expected to be YAML files containing a list of Ansible tasks (not a playbook, which contains a list of plays). Unless otherwise documented below, hooks are unconditionally executed for all hosts in the deployment.

General-purpose hooks

pre-deploy

TPA invokes hooks/pre-deploy.yml immediately after bootstrapping Python—but before doing anything else like configuring repositories and installing packages. This is the earliest stage at which you can execute your own code.

You can use this hook to set up custom repository configuration, beyond what you can do with apt_repositories or yum_repositories.

post-repo

TPA invokes hooks/post-repo.yml after configuring package repositories. You can use it to make corrections to the repository configuration before beginning to install packages.

pre-initdb

TPA invokes hooks/pre-initdb.yml before deciding whether or not to run initdb to create PGDATA if it does not exist. You should not ordinarily need to use this hook (but if you use it to create PGDATA yourself, then TPA will skip initdb).

postgres-config

TPA invokes hooks/postgres-config.yml after generating Postgres configuration files, including pg_hba.conf and the files in conf.d, but before the server has been started.

You can use this hook, for example, to create additional configuration files under conf.d.

postgres-config-final

TPA invokes hooks/postgres-config-final.yml after starting Postgres and creating users, databases, and extensions. You can use this hook to execute SQL commands, for example, to perform custom extension configuration or create database objects.

harp-config

TPA invokes hooks/harp-config.yml after generating HARP configuration files, but before the HARP service has been started.

You can use this hook, for example, to perform any customizations to the HARP proxy that are not provided by the built-in interface of TPA.

Please note that this hook will be run in any node that installs HARP packages, including BDR nodes.

post-deploy

TPA invokes hooks/post-deploy.yml at the end of the deployment.

You can go on to do whatever you want after this stage.

If you use this hook to make changes to any configuration files that were generated or altered during the TPA deployment, you run the risk that the next tpaexec deploy will overwrite your changes (since TPA doesn't know what your hook might have done).

BDR3 hooks

These hooks are specific to BDRv3 deployments.

bdr-pre-node-creation

TPA invokes hooks/bdr-pre-node-creation.yml on all instances before creating a BDR node on any instance for the first time. The hook will not be invoked if all required BDR nodes already exist.

bdr-post-group-creation

TPA invokes hooks/bdr-post-group-creation.yml on all instances after creating any BDR node group on the first_bdr_primary instance. The hook will not be invoked if the required BDR groups already exist.

bdr-pre-group-join

TPA invokes hooks/bdr-pre-group-join.yml on all instances after creating, changing or removing the replication sets and configuring the required subscriptions, before the node join.

You can use this hook to execute SQL commands and perform other adjustments to the replication set configuration and subscriptions that might be required before the node join starts.

For example, you can adjust the BDR witness replication set to automatically add new tables and create DDL filters in general.

Other hooks

postgres-pre-update, postgres-post-update

The update-postgres command invokes hooks/postgres-pre-update.yml on a particular instance before it installs any packages, and invokes hooks/postgres-post-update.yml after the package installation is complete. Both hooks are invoked only on the instance being updated.

You can use these hooks to customise the update process for your environment (e.g., to install other packages and stop and restart services that TPA does not manage).

New hooks

EDB adds new hooks to TPA as the need arises. If your use case is not covered by the existing hooks, please contact us to discuss the matter.