Skip to content

Blueprint contract

Status: Draft
Version: 0.1

1. Identity

  • blueprint_id: dr/postgresql-cloudsql-failback-onprem@v1
  • epoch: 2026E
  • lifecycle: deploy | drill | status
  • maturity: planned

2. Purpose

  • outcome:
  • Return service from a managed GCP DR primary back to an on-prem PostgreSQL HA cluster using a controlled, evidence-driven failback process.
  • non-goals:
  • MUST NOT attempt to resume an ambiguous pre-DR Patroni timeline.
  • MUST NOT treat failback as a trivial reverse of promotion.
  • MUST NOT silently destroy managed DR state after failback.

3. Inputs

3.1 Required inputs

  • managed DR primary contract
  • on-prem target contract or on-prem rebuild blueprint inputs
  • explicit failback confirmation flag
  • maintenance window confirmation

3.2 Optional inputs

  • reseed mode selection
  • reverse replication mode selection when later supported
  • post-failback standby retention policy

3.3 Input resolution

  • Managed source identity MUST be consumed from managed DR state.
  • On-prem target SHOULD be consumed from an explicit rebuild/reseed contract.
  • Secrets MUST be resolved via HyOps vault or environment.

4. Step composition

4.1 Required steps

The blueprint SHOULD contain at least:

  1. managed source verification
  2. maintenance window and write-freeze confirmation
  3. on-prem target rebuild or reseed
  4. data synchronization or restore completion verification
  5. endpoint cutback publication
  6. post-failback backup/standby policy step

4.2 Ordering and dependency rules

  • Write-freeze confirmation MUST occur before reseed or synchronization finalization.
  • On-prem rebuild or reseed MUST complete before cutback publication.
  • Post-failback standby retention or destroy policy MUST occur after cutback, not before.

5. State contracts

5.1 Consumed state

  • managed DR primary contract
  • on-prem target or rebuild contract
  • repository or export provenance contract as required by the selected failback mode

5.2 Published state

  • on-prem active primary endpoint
  • failback completion status
  • post-failback backup/standby posture

6. Safety and failure semantics

  • Failback MUST be modeled as a reseed/new-lineage operation unless reverse replication is explicitly implemented and validated.
  • The blueprint MUST fail if maintenance window or write-freeze confirmation is absent.
  • The blueprint MUST distinguish between reseed failure, validation failure, and cutback-publication failure.

7. Evidence

Minimum evidence set:

  • maintenance window confirmation
  • managed source verification
  • reseed/synchronization evidence
  • cutback publication evidence
  • resulting on-prem readiness evidence

8. Security

  • Export/replication credentials MUST NOT be published in state outputs.
  • Managed and on-prem endpoint evidence MUST be redacted where appropriate.
  • Destructive cleanup of managed standby resources MUST remain explicit and separate.

9. Change control

Breaking changes require an updated blueprint contract and compatibility notes.