Skip to content

RFC-HYOPS-SETUP-1.0

Status: Stable (Public)
Version: 1.0

1. Abstract

This document defines the HybridOps Setup Protocol (hyops setup), covering prerequisite installation entrypoints, privilege model, and stable exit codes.

2. Normative language

The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as defined in RFC 2119.

3. Command surface

hyops setup <component>
  [--root <dir>]
  [--sudo]
  [--dry-run]
  [--verbose]
  [--collection <common|helper|app>]

Where <component> is one of:

  • check
  • base
  • cloud-azure
  • cloud-gcp
  • galaxy
  • gcp
  • azure
  • proxmox
  • all

gcp, azure and proxmox are complete target setup commands. The cloud-gcp and cloud-azure components remain available for granular use. ansible remains a compatibility alias for galaxy.

Norms:

  • Setup MUST be an explicit operator action.
  • Setup MUST NOT run implicitly from hyops init or module execution.
  • --dry-run MUST NOT install or modify system configuration.

4. Scope and responsibilities

Setup provides thin orchestration of prerequisite installers shipped with HybridOps.Core.

  • Setup installs system prerequisites required by init targets and drivers.
  • Setup does not manage application configuration or secrets.
  • Setup does not validate target readiness; use hyops preflight and hyops init.

5. Script contract

Each setup component maps to an installer shipped with the runtime. Installers are located under tools/setup/ within the HybridOps.Core distribution. The supported components and their behaviour are defined by this contract; the CLI is the primary interface.

Invocation rules:

  • Setup MUST invoke scripts via bash, independent of execute-bit state.
  • If --sudo is provided, setup MUST invoke system scripts via sudo -H -E bash.
  • System-level installers MUST require root and fail fast when not root.
  • Scripts MUST be idempotent where practical.
  • Linux system package setup MAY require --sudo.
  • macOS setup MUST run as the logged-in user and MUST NOT invoke Homebrew as root.

6. Component definitions

6.1 check

check MUST report the presence of expected tools and return 2 when required tools are missing.

6.2 base

base installs foundational tools:

  • Terraform
  • Terragrunt
  • Packer
  • kubectl
  • GitHub CLI (gh)
  • vault password provider dependencies (pass, gpg, pinentry)

6.3 cloud-azure

cloud-azure installs Azure CLI (az).

6.4 cloud-gcp

cloud-gcp installs Google Cloud SDK (gcloud).

6.5 galaxy

galaxy installs Ansible Galaxy dependencies defined by:

  • tools/setup/requirements/ansible.galaxy.yml

The default shared requirements file MUST explicitly pin the released hybridops.common, hybridops.helper, and hybridops.app collection versions. Core MUST advance those pins only after the corresponding Galaxy publish path has completed successfully.

--collection MAY be repeated with galaxy to install only the selected pinned HybridOps collections. Without this option, galaxy MUST retain the complete dependency installation behaviour.

Install locations under runtime root:

  • collections: <root>/state/ansible/galaxy_collections
  • roles: <root>/state/ansible/roles

6.6 Target setup

Target setup MUST compose existing components rather than duplicate installer logic:

  • gcp: base, cloud-gcp, galaxy
  • azure: base, cloud-azure, galaxy
  • proxmox: base, galaxy

System stages elevate automatically on Linux and Windows WSL2. Galaxy setup runs as the invoking user.

6.7 all

all MUST run, in order:

  1. base
  2. cloud-azure
  3. cloud-gcp
  4. galaxy

Privilege rule:

  • System installers run with root privileges.
  • galaxy MUST run as the invoking operator user so runtime state is written under that user’s <root>.

7. Output

Setup output MUST be non-secret. Where output is printed, it SHOULD be concise and line-oriented.

Each non-dry-run invocation MUST show concise stage progress and write full redacted output to the run record. --verbose MUST also stream that output to the terminal.

<root>/logs/setup/<scope>/<run_id>/output.log
<root>/logs/setup/<scope>/<run_id>/result.json

<root>/logs/setup/<target>/<stage>/<run_id>/output.log
<root>/logs/setup/<target>/<stage>/<run_id>/result.json

Individual setup MUST print its run-record directory. Target setup MUST print the root containing its stage records. Setup MUST preserve the installer exit code. See Evidence and redaction.

--dry-run output MUST indicate which script would be executed.

8. Exit codes

Stable exit codes:

  • 0 success
  • 2 operator error (invalid flags)
  • installer failures preserve the non-zero exit code returned by the script
  • 30 internal error, including a missing setup script

9. Change control

Breaking changes include modifications to:

  • component names
  • component-to-script mapping
  • privilege rules for all
  • exit codes

10. Sequence overview

Mermaid sequence diagram 
sequenceDiagram
    autonumber
    actor Operator
    participant Hyops as hyops setup
    participant Script as tools/setup script

    Operator->>Hyops: hyops setup <component> [flags]
    Hyops->>Hyops: resolve script
    alt script not found
        Hyops-->>Operator: exit 41
    else dry-run
        Hyops->>Operator: print planned script
        Hyops-->>Operator: exit 0
    else execute
        alt sudo
            Hyops->>Script: sudo -E bash script
        else no sudo
            Hyops->>Script: bash script
        end
        Script-->>Hyops: exit code
        alt script success
            Hyops-->>Operator: exit 0
        else script failure
            Hyops-->>Operator: exit 40
        end
    end