# PostgreSQL HA OCF resource agent

A modular PostgreSQL HA implementation of `ocf:loxthelion:managed-container`.
Pacemaker invokes the agent to manage a rootless systemd/Quadlet maintenance
container. PostgreSQL is started and stopped independently with `pg_ctl`.

## Project layout

- `reference/`: original agent and immutable known-good reference copy.
- `refactored/`: executable agent, nine sourced shell modules, and a Python state helper.
- `tests/`: offline structural and behavioral comparison checks.
- `cluster-context/` and `runtime-context/`: saved lab configuration and state;
  these snapshots are not live status. Environment credentials are redacted.
- `notes/`: refactor plan, validation report, and file hashes.
- `HANDOFF.md`: scope, architecture, and behavior that must be preserved.

## Validation

Requires Bash, Python 3, and the OCF shell library (normally
`/usr/lib/ocf/lib/heartbeat/ocf-shellfuncs`). From the repository root:

```bash
python3 tests/verify_refactor.py
python3 tests/test_promotion_scores.py
python3 tests/test_promotion_scheduler.py
python3 tests/test_disconnected_state.py
python3 tests/test_promotion_cleanup.py
sha256sum -c notes/REFACTOR-SHA256SUMS
```

The tests preserve the original 29 lifecycle function bodies and exercise the
added promotion-scoring layer without operating the live cluster. The operator
has reported successful production SBD fencing, automatic promotion, VIP movement,
and former-primary rewind/rejoin in a three-node cluster.

Read [operations](docs/operations.md), [testing and snapshot provenance](docs/testing.md),
and [the review findings](docs/review.md). Historical lab snapshots and notes are
not current production configuration. Keep `target-role=Promoted`, single-primary
limits, and the VIP's Promoted-role colocation and promotion-before-start ordering.

The public entrypoint remains `/usr/lib/ocf/resource.d/loxthelion/managed-container`.
No production changes are part of this documentation freeze.

## Clone

```bash
git clone ssh://git@gitea.loxthelion.com:2222/david/ocf-managed-container.git
```

## RPM builds

Gitea Actions builds development RPMs on `main` pushes and pull requests using
an `ubuntu-latest` runner with a Fedora 43 job container. See
[packaging instructions](packaging/README.md) for local builds and artifacts.
[License provenance remains pending](packaging/PROVENANCE.md); release publishing
and automated deployment are not configured.

## Promotion scoring

Scores are 1000 for a healthy primary, 100 for a strictly verified streaming
standby, 50 for a recently verified eligible disconnected standby, and -INFINITY
otherwise. See [the scoring design](notes/DISCONNECTED-STANDBY.md) for identity,
local state ownership, the 300-second default freshness policy and limitations.
Fencing remains mandatory; scores do not authorize unfenced manual promotion.