HARP Proxy

HARP Proxy is a daemon which acts as an abstraction layer between the client application and Postgres. It interfaces with the Consensus Layer to obtain the identity of the current Lead Master node and directs traffic to that location. In the event of a planned switchover or unplanned failover, it will automatically redirect to the new Lead Master node as dictated by the DCS.

This HARP component is currently an interface layer between the DCS and PgBouncer. As such, PgBouncer is a prerequisite and should be installed in addition, in order for HARP Proxy to fully manage its activity.

How it Works

Upon starting, HARP Proxy will launch PgBouncer if it is not already running, and leave client connections in a paused state. Afterwards, it will contact the DCS to determine the identity of the Lead Master, configure PgBouncer to use this as the target for database connections, and resume connection activity. All application client traffic will then pass through PgBouncer into the current Lead Master node for the Location where this proxy is operating.

While PgBouncer is running, HARP Proxy will check its status based on the monitor_interval configuration setting within the DCS, and store it in theDCS for monitoring purposes. This will allow interrogation with harpctl toretrieve status of all configured proxies, or any one proxy in particular.

In the event the Lead Master lease is not set, HARP Proxy will pause all connection traffic until a new Lead Master is established. This also appliesto circumstances when harpctl promote is used to invoke a planned transitionto a new Lead Master. It uses a PgBouncer PAUSE command for this, so existingsessions are allowed to complete any pending transactions before they are heldin stasis.

Configuration

HARP Proxy expects the dcs, cluster, and proxy configuration stanzas. The following is a functional example:

cluster:
   * name: mycluster

dcs:
   * driver: etcd
   * endpoints:
   *   - host1:2379
   *   - host2:2379
   *   - host3:2379

proxy:
   * name: proxy1

Usage

This is the basic usage for HARP Proxy:

Usage of ./harp_proxy:
   * -f string
   *    Optional path to config file (shorthand)
   * --config string
   *    Optional path to config file

Note that there are no arguments to launch harp_proxy as a forked daemon. This software is designed to be launched through systemd or within a container as a top-level process. This also means output is directed to STDOUT and STDERRfor capture and access through journald or an attached container terminal.

PgBouncer Configuration File

Since HARP Proxy currently utilizes PgBouncer for connection management andredirection, a pgbouncer.ini file must exist. HARP Manager builds this filebased on various run-time directives as defined in the Proxy Directives documentation.

This file will be located in the same folder as the config.yml used by HARPProxy. Any PgBouncer process launched by HARP Proxy will use this configurationfile, and it may be used for debugging or information purposes. Modifications to this automatically generated pgbouncer.ini file will be lost any timeHARP Proxy is restarted, so use harpctl set proxy to alter these settingsinstead.

Disabling and Re-enabling HARP Proxy Node Management

It is possible to temporarily pause HARP Proxy control of PgBouncer. This results in a state where the daemon continues running but does not perform any operations that could affect existing behavior of the cluster. Re-enabling management causes it to resume operation.

An example of temporarily disabling management of a specific proxy would be:

harpctl unmanage proxy proxy1

See the harpctl documentation for more details.

Proxy node management is enabled by default.

Passthrough User Authentication

We strongly recommend configuring HARP Proxy to use the auth_user and auth_query run-time directives. If these are not set, the PgBouncer userlist.txt file must include username and password hash combinations for every user PgBouncer needs to authenticate on Postgres’ behalf.

this should not be the pgbouncer user itself, as this is utilized by HARP Proxy as an admin-level user in order to operate the underlying PgBouncer service.

In clusters administered by TPAexec, a function will be created and installed in the pg_catalog schema in the template1 database during provisioning. This means any subsequently created databases will also include the function, and it will be available to PgBouncer regardless of which database the user is attempting to contact.

If TPAexec is not used, we still recommend this function definition:

CREATE OR REPLACE FUNCTION pg_catalog.pgbouncer_get_auth(p_usename TEXT)
RETURNS TABLE(username TEXT, password TEXT) AS $$
BEGIN
   * RETURN QUERY
   * SELECT usename::TEXT, passwd::TEXT FROM pg_catalog.pg_shadow
   *  WHERE usename = p_usename;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER

REVOKE ALL ON FUNCTION pg_catalog.pgbouncer_get_auth(p_usename TEXT)
   * FROM PUBLIC

GRANT EXECUTE ON FUNCTION pg_catalog.pgbouncer_get_auth(p_usename TEXT)
   *  TO <auth_user>;

Don’t forget to substitute <auth_user> for the auth_user field supplied to HARP Proxy.

Then in the Bootstrap file, the following will complete the configuration:

cluster:
   * name: mycluster

proxies:
   * monitor_interval: 5
   * default_pool_size: 20
   * max_client_connections: 1000
   * auth_user: pgb_auth
   * auth_query: "SELECT * FROM pg_catalog.pgbouncer_get_auth($1)"
   * database_name: bdrdb
   * instances:
   *   - name: proxy1
   *   - name: proxy2

It is also possible to define these fields with harpctl set proxy:

harpctl set proxy global auth_user=pgb_auth

!!! Note * This means the postgres or enterprisedb OS user that launches HARP Proxy will need a .pgpass file so that auth_user can authenticate against Postgres.