Skip to content

HyOps Cloud SQL External Replica Lifecycle

Purpose

org/gcp/cloudsql-external-replica is the live managed PostgreSQL DR module for the GCP lane.

It currently supports two operator phases:

  • assess
  • establish

assess validates upstream source posture and an existing Cloud SQL target.

establish creates Database Migration Service objects:

  • source PostgreSQL connection profile
  • destination Cloud SQL connection profile
  • migration job

Important:

  • the DMS establish path creates its own Cloud SQL replica through the destination connection profile
  • it does not reuse a standalone org/gcp/cloudsql-postgresql instance
  • it is the engine behind dr/postgresql-cloudsql-standby-gcp@v1

Prerequisites

  • hyops init gcp completed for the selected environment
  • platform/onprem/postgresql-dr-source state is ok
  • for assess, org/gcp/cloudsql-postgresql state is ok
  • the operator has working gcloud authentication on the control host

Validate

cd "$HOME/hybridops-core"

./.venv/bin/hyops validate --env dev --skip-preflight \
  --module org/gcp/cloudsql-external-replica \
  --inputs modules/org/gcp/cloudsql-external-replica/examples/inputs.min.yml

Apply

cd "$HOME/hybridops-core"

./.venv/bin/hyops apply --env dev \
  --module org/gcp/cloudsql-external-replica \
  --inputs modules/org/gcp/cloudsql-external-replica/examples/inputs.min.yml

Establish

Prepare an operator input file with at least:

  • apply_mode: establish
  • project_state_ref or project_id
  • network_state_ref or private_network
  • source_connection_profile_name
  • destination_connection_profile_name
  • migration_job_name
  • source_replication_user
  • source_replication_password_env
  • connectivity_mode

Then run:

cd "$HOME/hybridops-core"

./.venv/bin/hyops apply --env dev \
  --module org/gcp/cloudsql-external-replica \
  --inputs <operator-establish-inputs.yml>

Expected outputs

  • cap.db.managed_external_replica = assessed|established
  • managed_replication_mode = logical
  • managed_replication_prereqs_ready = true|false
  • managed_replication_established = true|false
  • target instance metadata and target private IP
  • target_db_host, target_db_port
  • endpoint_dns_name, endpoint_target, endpoint_target_type, endpoint_host, endpoint_port
  • endpoint_cutover_required
  • source leader and source replication candidate signal

Contract rule:

  • if endpoint_dns_name is set, clients should consume endpoint_target=<dns name>
  • if endpoint_dns_name is blank, endpoint_target falls back to the Cloud SQL private host and endpoint_cutover_required=true

This keeps the managed GCP standby lane aligned with the same endpoint contract used by platform/postgresql-ha and platform/network/dns-routing.

Notes

  • The module copies the operator's existing ~/.config/gcloud into the HyOps runtime cache on first use so packaged runs do not rely on write access to the default gcloud config directory.
  • The module keeps replication secrets out of Terraform state by using gcloud on the controller side.
  • static-ip connectivity requires the source database to accept DMS traffic from an allowlisted public IP.
  • reverse-ssh connectivity requires an explicit bastion VM and VPC input.
  • promotion and failback are intentionally handled by separate blueprints with explicit manual gates and DNS cutover, not by this module directly.