Skip to content

Module contract

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

1. Identity

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

2. Purpose

  • outcome:
  • Create and validate a managed GCP PostgreSQL standby/replica relationship from an external self-managed source for DR readiness without persisting replication secrets in Terraform state.
  • 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

  • GCP project selection
  • GCP network selection
  • source contract from platform/onprem/postgresql-dr-source
  • explicit replication/DMS object names
  • source replication credentials

3.2 Optional inputs

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

3.3 Input resolution

  • GCP project and network SHOULD be consumed from upstream state where available.
  • Source contract MUST be consumable 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

  • current implementation uses config/ansible on the controller
  • provider-specific hooks MAY be expanded later for richer promotion or verification steps

4.3 External dependencies

  • reachable on-prem source
  • Google Database Migration Service prerequisites
  • private or explicitly approved source connectivity

5. Outputs

5.1 Produced outputs

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

At minimum, the managed endpoint contract MUST include:

  • target_db_host
  • target_db_port
  • endpoint_dns_name
  • endpoint_target
  • endpoint_target_type
  • endpoint_host
  • endpoint_port
  • endpoint_cutover_required

5.2 Evidence

Minimum evidence set:

  • source and target identifiers
  • resolved configuration summary (redacted)
  • replication establishment evidence
  • published endpoint evidence

6. Failure semantics

  • MUST fail clearly when source posture, GCP project/network inputs, or DMS object creation are invalid
  • MUST distinguish replication setup failure from later health degradation
  • MUST surface whether standby remains safe to cut over

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
  • MUST publish the same client-facing endpoint fields used by platform/postgresql-ha so downstream DNS cutover and application consumers do not need lane-specific logic

9. Change control

Breaking changes require an updated module contract and compatibility notes.