Skip to content

Operate PostgreSQL Core Service (HyOps)

Purpose: Configure PostgreSQL for dependent services using platform/onprem/postgresql-core.
Owner: Platform engineering
Trigger: New platform service rollout, DB baseline refresh, or controlled environment rebuild
Impact: Creates or updates PostgreSQL configuration, databases, users, and allowlists on the target host
Severity: P2
Pre-reqs: A reachable target host (typically a VM created by platform/onprem/platform-vm), runtime vault decrypt working, Ansible deps installed.
Rollback strategy: Run hyops destroy with the same module and input overlay.

Context

This runbook covers module-level operations for:

  • Module: platform/onprem/postgresql-core
  • Driver: config/ansible
  • Scope: configure PostgreSQL on an existing Linux host (no VM provisioning)

The module publishes DB connection outputs into HyOps state for downstream modules (for example platform/onprem/netbox) to consume.

Preconditions and safety checks

  • Installed hyops (via install.sh) can be run from any working directory.
  • If you want to use the shipped example overlays, set:
export HYOPS_CORE_ROOT="${HYOPS_CORE_ROOT:-$HOME/.hybridops/core/app}"

For source checkout usage, set HYOPS_CORE_ROOT to your hybridops-core checkout root instead. - Correct environment selected (--env dev|staging|prod). - Target host is reachable via SSH from the runner. - Ansible deps installed into the runtime root for the environment: - hybridops-core/tools/setup/setup-ansible.sh - Secret env var is available via shell env or runtime vault: - NETBOX_DB_PASSWORD (used as the initial DB user password by default)

Install/update Ansible runtime deps for the env:

# If you installed via install.sh (default runs setup-all), this is already done.
# To (re)install Ansible Galaxy deps for an env:
hyops setup ansible --env dev

Steps

  1. Select an overlay

Use one of:

  • $HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.min.yml
  • $HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.typical.yml

  • $HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.enterprise.yml

  • Seed secrets (recommended: runtime vault)

hyops secrets set --env dev \
  NETBOX_DB_PASSWORD='...'
  1. Preflight
hyops preflight --env dev --strict \
  --module platform/onprem/postgresql-core \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.typical.yml"
  1. Deploy / converge
hyops apply --env dev \
  --module platform/onprem/postgresql-core \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.typical.yml"
  1. Verify outputs and evidence
cat $HOME/.hybridops/envs/dev/state/modules/platform__onprem__postgresql-core/latest.json

Check:

  • status is ok
  • outputs.db_host, outputs.db_port, outputs.db_name, outputs.db_user are present

  • evidence_dir exists

  • Destroy (best-effort cleanup)

hyops destroy --env dev \
  --module platform/onprem/postgresql-core \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.typical.yml"
  1. Rebuild (destroy then apply)
hyops rebuild --env dev --yes \
  --confirm-module platform/onprem/postgresql-core \
  --module platform/onprem/postgresql-core \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.typical.yml"

Verification

Primary state:

  • $HOME/.hybridops/envs/<env>/state/modules/platform__onprem__postgresql-core/latest.json

Primary logs:

  • $HOME/.hybridops/envs/<env>/logs/module/platform__onprem__postgresql-core/<run_id>/

Common issues

missing required env vars: NETBOX_DB_PASSWORD

Cause: secret not set in shell env and not present in runtime vault env file.

Fix: seed it:

hyops secrets set --env dev NETBOX_DB_PASSWORD='...'

PostgreSQL listens on a non-local address but allowed_clients is empty

Cause: listen_addresses includes a non-local address but no allowlist was provided.

Fix: define explicit allowed_clients /32 entries for consumers (recommended).

References