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]

Where <component> is one of:

• check
• base
• cloud-azure
• cloud-gcp
• ansible
• all

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 scripts via sudo -E bash.
• System-level installers MUST require root and fail fast when not root.
• Scripts MUST be idempotent where practical.

6. Component definitions

6.1 check

check MUST report presence of expected tools and return success regardless of missing tools.

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 ansible

ansible installs Ansible Galaxy dependencies defined by:

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

Install locations under runtime root:

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

6.6 all

all MUST run, in order:

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

Privilege rule:

• System installers run with root privileges.
• ansible 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.

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

8. Exit codes

Stable exit codes:

• 0 success
• 2 operator error (invalid flags)
• 40 installer failure (script returned non-zero)
• 41 script not found for the requested component

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