Operate Cloud Object Repository Modules (HyOps)

Purpose

Provision reusable object storage infrastructure with a normalized state contract.

Modules

• org/aws/object-repo
• org/gcp/object-repo
• org/azure/object-repo

Execution model

• Driver: iac/terragrunt
• Engine: Terraform providers (AWS/GCP/Azure)
• Credentials: runtime tfvars + profile credential contracts
• For GCP, prefer project_state_ref: org/gcp/project-factory when HyOps already manages the target project in the same env.
• Use explicit project_id only when targeting an external/pre-existing project not managed by HyOps state.

GCP naming guidance

• Recommended bucket pattern: hyops-<env>-objectrepo-<suffix>
• Example: hyops-dev-objectrepo-a1
• Keep bucket names lowercase and globally unique within GCS.

Steps

1. Preflight

   HYOPS_INPUT_project_state_ref=org/gcp/project-factory \
   HYOPS_INPUT_bucket_name=hyops-dev-objectrepo-a1 \
   hyops preflight --env <env> --strict \
     --module org/gcp/object-repo \
     --inputs "$HYOPS_CORE_ROOT/modules/org/gcp/object-repo/examples/inputs.min.yml"
   

2. Apply

   HYOPS_INPUT_project_state_ref=org/gcp/project-factory \
   HYOPS_INPUT_bucket_name=hyops-dev-objectrepo-a1 \
   hyops apply --env <env> \
     --module org/gcp/object-repo \
     --inputs "$HYOPS_CORE_ROOT/modules/org/gcp/object-repo/examples/inputs.min.yml"
   

3. Verify outputs

   cat "$HOME/.hybridops/envs/<env>/state/modules/org__gcp__object-repo/latest.json"
   

Check normalized outputs: - repo_backend - repo_bucket_name - repo_principal_name - repo_credential_create_hint

1. Consume from workload module

   HYOPS_INPUT_repo_state_ref=org/gcp/object-repo \
   hyops apply --env <env> \
     --module platform/postgresql-ha-backup \
     --inputs "$HYOPS_CORE_ROOT/modules/platform/postgresql-ha-backup/examples/inputs.gcs.yml"
   

Security model

• Credential material is generated out-of-band.
• Credentials are stored in HyOps vault using hyops secrets set.
• Workload modules consume vault env keys, not inline secrets.

Credential rotation after repo replacement

When a recovered GCP repo instance publishes a different service account than the retired slot, rotate the consumer secret before rerunning backup or restore modules. Example:

gcloud iam service-accounts keys create ./object-repo-sa.json \
  --iam-account objectrepo@hybridops-dev-gcp-03.iam.gserviceaccount.com

hyops secrets set --env dev --from-file PG_BACKUP_GCS_SA_JSON=./object-repo-sa.json

Then rerun the workload module that consumes repo_state_ref.

Notes

• org/*/pgbackrest-repo modules remain available as workload-specific wrappers.
• Prefer org/*/object-repo for new designs and multi-workload reuse.
• hyops init gcp remains required for runtime credentials and impersonation defaults, but it is not the preferred source of project intent for reusable module composition.
• Bucket name is immutable within a given HyOps state slot. To create a second repo instead of pivoting the first one, use --state-instance <name>.
• During GCP account or project recovery, keep the old slot as historical state and create a new instance for the recovered bucket lineage. Then update downstream repo_state_ref values to org/gcp/object-repo#<instance> before rerunning backup or restore modules.