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.

You may select between pgbouncer or builtin for HARP Proxy. When using pgbouncer, HARP Proxy is 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.

The builtin proxy does not require any additional software. When using builtin, HARP Proxy functions as a level 4 pass-through proxy.

PgBouncer¶

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 the DCS for monitoring purposes. This will allow interrogation with harpctl to retrieve 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 applies to circumstances when harpctl promote is used to invoke a planned transition to a new Lead Master. It uses a PgBouncer PAUSE command for this, so existing sessions are allowed to complete any pending transactions before they are held in 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 STDERR for capture and access through journald or an attached container terminal.

PgBouncer Configuration File¶

Since HARP Proxy currently utilizes PgBouncer for connection management and redirection, a pgbouncer.ini file must exist. HARP Manager builds this file based 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 HARP Proxy. Any PgBouncer process launched by HARP Proxy will use this configuration file, and it may be used for debugging or information purposes. Modifications to this automatically generated pgbouncer.ini file will be lost any time HARP Proxy is restarted, so use harpctl set proxy to alter these settings instead. Calling harpctl set proxy does not update the pgbouncer.ini file until the proxy has been restarted.

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 Command-line Tool 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_conn: 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.

Builtin Proxy¶

How it Works¶

Upon starting, HARP Proxy will listen for incoming connections on the listening address and listening port specified in the bootstrap file per proxy instance. All application client traffic will then pass through Builtin Proxy into the current Lead Master node for the Location where this proxy is operating.

In the event the Lead Master lease is not set, HARP Proxy will disconnect all connection traffic until a new Lead Master is established. This also applies to circumstances when harpctl promote is used to invoke a planned transition to a new Lead Master. The disconnect is immediate.

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 STDERR for capture and access through journald or an attached container terminal.

HARP Proxy¶

PgBouncer¶

How it Works¶

Configuration¶

Usage¶

PgBouncer Configuration File¶

Disabling and Re-enabling HARP Proxy Node Management¶

Passthrough User Authentication¶

Builtin Proxy¶

How it Works¶

Configuration¶

Usage¶

Previous topic

Next topic

Table of Contents