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: candidate

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 manual gate confirmation
  • source fencing confirmation
  • DNS cutover intent

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. explicit manual gate
  3. post-promotion endpoint publication

4.2 Ordering and dependency rules

  • Manual gate confirmation MUST occur before endpoint publication.
  • Provider-native promotion MUST already be complete before endpoint publication.
  • Endpoint publication MUST be separately guarded from provider-native promotion.

5. State contracts

5.1 Consumed state

  • managed standby contract
  • source fencing evidence
  • DNS authority contract

5.2 Published state

  • active DR primary endpoint
  • promotion gate evidence
  • post-promotion endpoint publication status

6. Safety and failure semantics

  • Promotion cutover MUST fail if fencing confirmation is absent.
  • Promotion cutover MUST fail if provider-native promotion is not already proven.
  • The blueprint MUST surface partial-completion states clearly when the gate succeeds but endpoint publication fails.

7. Evidence

Minimum evidence set:

  • fencing confirmation
  • manual gate evidence
  • provider-native promotion 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.