Skip to content

Module contract

Status: Draft (phase 1 assessment implemented)
Version: 0.1

1. Identity

  • module_id: org/gcp/cloudsql-external-replica
  • epoch: 2026E
  • lifecycle: deploy | destroy | status
  • maturity: planned

2. Purpose

  • outcome:
  • Phase 1: validate a managed GCP PostgreSQL DR target and source contract without persisting replication secrets in Terraform state.
  • Later phases: create and validate a managed GCP PostgreSQL standby/replica relationship from an external self-managed source for DR readiness.
  • non-goals:
  • MUST NOT provision the on-prem source by itself.
  • MUST NOT perform application cutover.
  • MUST NOT replace backup/restore DR as the baseline supported path.

3. Inputs

3.1 Required inputs

  • managed target contract from org/gcp/cloudsql-postgresql
  • source contract from platform/onprem/postgresql-dr-source
  • explicit replication mode selection
  • promotion guard policy inputs

3.2 Optional inputs

  • lag thresholds
  • observability/export settings
  • labels/tags

3.3 Input resolution

  • Managed target MUST be consumed from upstream state.
  • Source contract MUST be consumed from upstream state.
  • Provider-specific secrets MUST be resolved via vault/env, not Terraform state.

4. Dependencies

4.1 Init targets

  • gcp

4.2 Drivers

  • phase 1 implementation uses config/ansible on the controller
  • provider-specific config/ansible hooks MAY be expanded when managed replication establishment is implemented

4.3 External dependencies

  • reachable on-prem source
  • managed PostgreSQL service prerequisites for external replication

5. Outputs

5.1 Produced outputs

  • standby readiness status
  • target endpoint contract
  • replication status contract
  • promotion eligibility signals

5.2 Evidence

Minimum evidence set:

  • source and target identifiers
  • resolved configuration summary (redacted)
  • replication establishment evidence
  • promotion guard evidence

6. Failure semantics

  • MUST fail clearly when source and target contracts are incompatible
  • MUST distinguish replication setup failure from later health degradation
  • MUST surface whether standby remains safe to promote

7. Security

  • MUST NOT publish replication secrets
  • MUST keep provider/service credentials out of state outputs
  • MUST redact service-specific sensitive diagnostics

8. Compatibility

  • MUST version any change to normalized replication or promotion outputs
  • SHOULD remain compatible with the managed DR blueprint family contract

9. Change control

Breaking changes require an updated module contract and compatibility notes.