Skip to content

RFC-HYOPS-PREFLIGHT-1.1

Status: Stable (Public)
Version: 1.1

1. Abstract

This document defines the HybridOps Preflight Protocol (hyops preflight), covering prerequisite checks, target readiness checks, output formats, 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 preflight
  [--root <dir>]
  [--target <target>]
  [--vault-file <path>]
  [--vault-password-file <path> | --vault-password-command <cmd>]
  [--json]
  [--strict]

Norms:

  • --root MUST redefine runtime root for the invocation.
  • --target MAY be provided to check readiness for a specific init target.
  • --json MUST emit machine-readable output.
  • --strict MUST fail when any optional check is not satisfied.

4. Scope

Preflight is a read-only validation step.

  • Preflight MUST NOT install tools or modify system configuration.
  • Preflight MUST NOT create or modify vault content.
  • Preflight MAY create runtime directories under <root> when required to perform checks.

Installation and remediation actions belong to hyops setup and hyops init. See:

5. Checks

5.1 Command availability

Preflight MUST validate required local capabilities for supported operations. At minimum:

  • ssh
  • scp
  • vault encryption

Additional checks MAY be added over time. New checks MUST preserve backwards-compatible semantics under non-strict mode.

5.2 Runtime layout

Preflight MUST validate that the following directories exist or are creatable under <root>:

  • meta/
  • vault/

5.3 Vault decryptability (when applicable)

When a vault password source is provided and a vault file exists, preflight MUST validate that the vault can be decrypted.

Norms:

  • When both password sources are provided, --vault-password-file MUST take precedence.
  • Vault validation MUST NOT print secrets.
  • If --strict is not set, absence of a vault file MAY be treated as non-fatal.
  • vault:encryption MUST report whether local vault encryption support is available.
  • vault:data MUST report not initialized when no environment vault file exists.
  • vault:decrypt MUST be used when encrypted environment data exists and decryptability is tested.

5.4 Target readiness

When --target <target> is provided, preflight MUST check for the readiness marker:

<root>/meta/<target>.ready.json

Norms:

  • If the marker exists and indicates status=ready, the target readiness check MUST pass.
  • If the marker is missing or indicates not-ready, the target readiness check MUST fail.

Target annexes are published under architecture/contracts/init/.

6. Output

Each invocation MUST stream redacted output to the terminal and persist the same output under:

<root>/logs/preflight/<run_id>/output.log

The invocation MUST also write <root>/logs/preflight/<run_id>/result.json and print the run-record directory. Evidence capture MUST preserve the preflight exit code. See Evidence and redaction.

6.1 Text output

Text output MUST be line-oriented and stable:

<status>  <check_id> <detail>
...
exit_code=<n>

Where:

  • <status> is ok or fail
  • <check_id> is a stable identifier (for example cmd:ssh, runtime:meta, readiness:proxmox)
  • <detail> is non-secret diagnostic content

6.2 JSON output

When --json is provided, output MUST be a single JSON document.

Minimum schema:

{
  "root": "<root>",
  "target": "<target-or-null>",
  "strict": false,
  "checks": [
    {
      "id": "cmd:ssh",
      "status": "ok",
      "detail": "..."
    }
  ],
  "exit_code": 0
}

JSON output MUST NOT include secrets.

7. Exit codes

Stable exit codes:

  • 0 success
  • 2 operator error (invalid flags)
  • 11 configuration, readiness, runtime or strict capability failure
  • 12 missing required local dependency command
  • 21 vault decryptability failure (password missing or decrypt failed)

8. Change control

Breaking changes include modifications to:

  • output formats and schemas
  • exit codes
  • readiness marker semantics
  • strict-mode semantics

New checks MAY be added without a version bump when non-strict behaviour remains backwards compatible.

9. Sequence overview

Mermaid sequence diagram 
sequenceDiagram
    autonumber
    actor Operator
    participant Hyops as hyops preflight
    participant FS as Runtime FS
    participant Vault as Vault (ansible-vault)

    Operator->>Hyops: hyops preflight [flags]
    Hyops->>FS: validate runtime dirs
    Hyops->>Hyops: validate local commands

    alt vault file exists and password source provided
        Hyops->>Vault: attempt decrypt
        alt decrypt fails
            Hyops->>Operator: exit 21
        end
    end

    alt target provided
        Hyops->>FS: read readiness marker
        alt missing/not ready
            Hyops->>Operator: exit 22
        end
    end

    Hyops->>Operator: exit code + report