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/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/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/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
    STATE_PATH="$HOME/.hybridops/envs/<env>/state/modules/platform__postgresql-ha/latest.json"
[ -f "$STATE_PATH" ] || STATE_PATH="$HOME/.hybridops/envs/<env>/state/modules/platform__onprem__postgresql-ha/latest.json"
cat "$STATE_PATH"

Expected:

  • status: ok

  • outputs.cap.db.postgresql_ha: ready

  • Ensure GCP target init/credentials are ready

    hyops preflight --env <env> --target gcp

  • 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

  • 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

The shipped blueprint is a scaffold. Replace every CHANGE_ME_* value in the runtime copy before preflight or deploy.

Set at minimum:

  • bucket_name
  • location

Then choose one project source:

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

Optional:

  • 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"

  • 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

    STATE_PATH="$HOME/.hybridops/envs/<env>/state/modules/platform__postgresql-ha-backup/latest.json"
[ -f "$STATE_PATH" ] || STATE_PATH="$HOME/.hybridops/envs/<env>/state/modules/platform__onprem__postgresql-ha-backup/latest.json"
cat "$STATE_PATH"

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/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