Skip to content

Install prerequisites with hyops setup

  • Purpose: Install workstation prerequisites required for HybridOps.Core execution. Owner: Platform operations

  • Trigger: First-time install, new workstation, CI runner bootstrap, or dependency drift.

  • Impact: Missing tools prevent init targets and modules from executing.

  • Severity: P3 Pre-reqs: Ubuntu/Debian host with sudo access and internet connectivity.

  • Rollback strategy: Package removal follows OS package manager procedures; no platform state is modified.

Context

HybridOps.Core requires a small set of system tools for target initialisation and module execution. Installation is an explicit operator action and is not performed automatically by hyops preflight or hyops init.

Preconditions and safety checks

  • Confirm correct host and intended scope (workstation vs CI runner).
  • Confirm sudo is available and permitted for package installation.
  • Confirm outbound internet connectivity to OS repositories and vendor repositories.

Steps

1) Install base prerequisites - Command:

     hyops setup base --sudo
  • Expected result: Base tools are installed or reported as already present.

2) Install cloud CLIs (optional) - Azure:

     hyops setup azure --sudo

  • GCP:

     hyops setup gcp --sudo

  • Expected result: az and/or gcloud are available on PATH where installed.

3) Install Ansible Galaxy dependencies (runtime state) - Command:

     hyops setup ansible
  • Expected result: Collections are installed under <root>/state/ansible/collections for the active runtime root.

4) Validate prerequisites - Command:

     hyops preflight --strict
  • Expected result: Required checks pass; failures include remediation guidance.

Verification

  • hyops preflight --strict returns exit code 0.
  • hyops setup <scope> --report reflects expected versions and paths.

Troubleshooting

hyops setup base --sudo prompts repeatedly

  • Cause: sudo timestamp expired or multiple shells are invoking setup.

  • Remediation:

    sudo -v hyops setup base --sudo

hyops setup azure --sudo or hyops setup gcp --sudo succeeds but CLI not found

  • Cause: shell cache or PATH not refreshed.

  • Remediation:

    hash -r command -v az || true command -v gcloud || true

hyops setup ansible installs collections but Ansible cannot find them

  • Cause: collections installed into runtime-managed directories but environment not configured.

  • Remediation:

    export ANSIBLE_COLLECTIONS_PATH="$HOME/.hybridops/state/ansible/collections:${ANSIBLE_COLLECTIONS_PATH:-$HOME/.ansible/collections:/usr/share/ansible/collections}" export ANSIBLE_ROLES_PATH="$HOME/.hybridops/state/ansible/roles:${ANSIBLE_ROLES_PATH:-$HOME/.ansible/roles:/etc/ansible/roles}"

  • Note: HybridOps runtime commands also derive collection roles/ directories from ANSIBLE_COLLECTIONS_PATH and add them to ANSIBLE_ROLES_PATH as a fallback. This protects remote include_role execution when ansible-core resolves collection roles inconsistently across SSH-backed plays.

  • Note: HybridOps runtime commands prefer the bundled core collection payload ahead of cached Galaxy copies under runtime state. This keeps shipped runtime content authoritative when local collection caches still contain older releases.

Post-actions and clean-up

  • Standardise environment variables for configuration tooling execution where runtime-managed dependencies are used.
  • Record a baseline in change control where required.

References