Skip to content

Blueprint contract

Status: Draft
Version: 0.1

1. Identity

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

2. Purpose

  • outcome:
  • Promote a managed GCP PostgreSQL standby to become the active DR write primary during a controlled incident or drill.
  • non-goals:
  • MUST NOT create a standby from scratch.
  • MUST NOT silently assume the on-prem primary is safe to leave online.
  • MUST NOT automate application cutover without explicit policy and guard confirmation.

3. Inputs

3.1 Required inputs

  • standby state contract selection
  • explicit promotion confirmation flag
  • source fencing confirmation
  • cutover intent or no-cutover drill mode

3.2 Optional inputs

  • maximum acceptable lag
  • application endpoint publication policy
  • post-promotion backup policy

3.3 Input resolution

  • Standby identity MUST be consumed from the standby blueprint/module state.
  • Promotion guards MUST be explicit operator inputs or explicit state signals.

4. Step composition

4.1 Required steps

The blueprint SHOULD contain at least:

  1. standby contract resolution
  2. source fencing verification
  3. lag and health verification
  4. managed standby promotion
  5. post-promotion endpoint publication

4.2 Ordering and dependency rules

  • Fencing verification MUST occur before promotion.
  • Promotion MUST occur before any endpoint publication or backup reconfiguration.
  • If endpoint publication is included, it MUST be separately guarded.

5. State contracts

5.1 Consumed state

  • managed standby contract
  • source contract or source fencing evidence
  • repository/backup state if post-promotion backup enablement is included

5.2 Published state

  • active DR primary endpoint
  • promotion timestamp and mode
  • post-promotion readiness status

6. Safety and failure semantics

  • Promotion MUST fail if fencing confirmation is absent.
  • Promotion MUST fail if lag exceeds policy or target readiness is not proven.
  • The blueprint MUST surface partial-completion states clearly when promotion succeeds but endpoint publication or backup reconfiguration fails.

7. Evidence

Minimum evidence set:

  • fencing confirmation
  • standby lag/health evidence
  • promotion action evidence
  • published DR endpoint contract

8. Security

  • Promotion guards MUST be explicit and auditable.
  • Secrets MUST remain external to published state.
  • Any endpoint publication evidence MUST avoid leaking confidential connection material.

9. Change control

Breaking changes require an updated blueprint contract and compatibility notes.