Skip to content

Prepare PostgreSQL HA Backup to GCP (HyOps Blueprint)

Purpose: Provision a GCS repository and wire pgBackRest for an existing on-prem PostgreSQL HA cluster.
Owner: Platform engineering / SRE
Trigger: After platform/onprem/postgresql-ha is healthy, before DR drills or stateful workload onboarding
Impact: A reusable GCS repo exists in the selected env and PostgreSQL HA backup configuration consumes it via repo_state_ref rather than duplicated bucket values
Severity: P2
Pre-reqs: platform/onprem/postgresql-ha is ok, GCP init is ready for the target env, runtime vault decrypt works, and PG_BACKUP_GCS_SA_JSON is available in vault/env
Rollback strategy: Destroy the backup module to disable backup jobs; destroy the repo module only if you intend to retire the repository

Context

Blueprint ref: dr/postgresql-ha-backup-gcp@v1
Location: hybridops-core/blueprints/dr/postgresql-ha-backup-gcp@v1/blueprint.yml

Default step flow:

  1. org/gcp/object-repo#postgresql_ha_backup_repo
  2. platform/onprem/postgresql-ha-backup

Why this blueprint exists:

  • It prevents the operator from hardcoding gcs_bucket in the backup module.
  • It forces repository creation to happen before pgBackRest stanza creation.
  • It keeps the repo isolated with its own state_instance, so the same env can host multiple object repositories cleanly.

Preconditions and safety checks

  1. Ensure PostgreSQL HA is already healthy
cat "$HOME/.hybridops/envs/<env>/state/modules/platform__onprem__postgresql-ha/latest.json"

Expected:

  • status: ok

  • outputs.cap.db.postgresql_ha: ready

  • Ensure GCP target init/credentials are ready

hyops preflight --env <env> --target gcp
  1. Ensure the pgBackRest GCS service account JSON is present in runtime vault
export PG_BACKUP_GCS_SA_JSON="$(cat /path/to/gcs-sa.json)"
hyops secrets set --env <env> --from-env PG_BACKUP_GCS_SA_JSON
  1. Ensure Patroni passwords exist in vault
hyops secrets ensure --env <env> \
  PATRONI_SUPERUSER_PASSWORD \
  PATRONI_REPLICATION_PASSWORD

Steps

  1. Copy the shipped blueprint and fill in GCP repo details
hyops blueprint init --env <env> \
  --ref dr/postgresql-ha-backup-gcp@v1 \
  --dest-name dr-postgresql-ha-backup-gcp.yml

Set at minimum:

  • bucket_name

Then choose one project source:

  • Preferred: project_state_ref: org/gcp/project-factory
  • Fallback: project_id: <existing-project-id>

Optional:

  • location
  • storage_class
  • versioning_enabled

hyops init gcp still needs to be ready for credentials/runtime access, but it is not the preferred source of project intent for this blueprint.

Recommended bucket pattern:

  • hyops-<env>-pgbackrest-<suffix>
  • Example: hyops-dev-pgbackrest-a1

  • Keep bucket names lowercase and globally unique within GCS.

  • Validate and preflight

hyops blueprint validate --file "$HOME/.hybridops/envs/<env>/config/blueprints/dr-postgresql-ha-backup-gcp.yml"
hyops blueprint preflight --env <env> --file "$HOME/.hybridops/envs/<env>/config/blueprints/dr-postgresql-ha-backup-gcp.yml"
  1. Execute
hyops blueprint deploy --env <env> \
  --file "$HOME/.hybridops/envs/<env>/config/blueprints/dr-postgresql-ha-backup-gcp.yml" \
  --execute

Verification

  1. Confirm object repo state
cat "$HOME/.hybridops/envs/<env>/state/modules/org__gcp__object-repo/instances/postgresql_ha_backup_repo.json"

Expected:

  • status: ok
  • outputs.repo_backend: gcs

  • outputs.repo_bucket_name matches your bucket

  • Confirm backup module state

cat "$HOME/.hybridops/envs/<env>/state/modules/platform__onprem__postgresql-ha-backup/latest.json"

Expected:

  • status: ok
  • outputs.cap.db.postgresql_ha_backup: ready
  • outputs.pgbackrest_repo.type: gcs

Notes

  • This blueprint is the preferred path for GCP because it avoids the operator mistake of pointing backup at a non-existent literal bucket.
  • The backup step consumes:
  • inventory_state_ref: platform/onprem/postgresql-ha
  • repo_state_ref: org/gcp/object-repo#postgresql_ha_backup_repo
  • If you later need AWS or Azure equivalents, the same composition pattern should be used with:
  • org/aws/object-repo
  • org/azure/object-repo