Skip to content

Module contract

Status: Draft
Version: 0.1

1. Identity

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

2. Purpose

  • outcome:
  • Provision a managed PostgreSQL instance or regional HA pair in GCP for HybridOps-managed DR or platform workloads.
  • non-goals:
  • MUST NOT configure on-prem replication sources by itself.
  • MUST NOT cut over application traffic.
  • MUST NOT manage database-level exports/imports as part of a normal deploy lifecycle.

3. Inputs

3.1 Required inputs

  • project_id or project_state_ref
  • region
  • instance_name
  • database_version
  • availability_type
  • network or network_state_ref

3.2 Optional inputs

  • sizing and storage policy
  • private IP enablement
  • maintenance window
  • backups/PITR settings
  • labels/tags

3.3 Input resolution

  • project_state_ref SHOULD be preferred when the GCP project is managed in the same env.
  • Explicit project_id MAY be used for external/pre-existing projects.
  • Network values SHOULD be resolved from upstream state where available.

4. Dependencies

4.1 Init targets

  • gcp

4.2 Drivers

  • iac/terragrunt
  • GCP profile compatible with provider-native Terraform resources

4.3 External dependencies

  • GCP APIs required for managed PostgreSQL provisioning
  • operator identity with sufficient rights in the selected project

5. Outputs

5.1 Produced outputs

  • managed database instance identifier
  • private endpoint / connection name
  • region
  • provider type
  • database engine/version metadata
  • normalized endpoint contract suitable for downstream DR promotion/failback modules

5.2 Evidence

Minimum evidence set:

  • run metadata
  • resolved identifiers
  • driver invocation metadata
  • normalized output inventory

6. Failure semantics

  • MUST fail fast when required project/network identifiers are missing
  • MUST fail clearly when provider APIs or permissions are insufficient
  • MUST surface whether failure occurred before or after instance creation

7. Security

  • MUST NOT emit generated database passwords or connection secrets into Terraform state outputs
  • MUST prefer private IP connectivity for DR posture
  • MUST redact provider invocation details where secrets may appear

8. Compatibility

  • MUST declare supported managed PostgreSQL modes explicitly
  • breaking changes to normalized outputs require contract revision

9. Change control

Breaking changes require an updated module contract and compatibility notes.