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='...'

  • Preflight

    hyops preflight --env dev --strict \
  --module platform/onprem/postgresql-core \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.typical.yml"

  • Deploy / converge

    hyops apply --env dev \
  --module platform/onprem/postgresql-core \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/postgresql-core/examples/inputs.typical.yml"

  • Verify outputs and run records

    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

  • the module log directory exists and, if published, the current state still exposes that path as evidence_dir

  • 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"

  • 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