HOWTO: Run HyOps Preflight and Interpret the Report¶

Purpose: Invoke the HybridOps preflight check, interpret all sections of the output report, and resolve common preflight failures.

Difficulty: Intermediate

Track: Contract-Driven Automation

Overview¶

hyops preflight is a read-only validation command. It checks required local commands and runtime directories. It can also check vault decryptability and the readiness marker for a named init target. It does not install prerequisites or apply module changes.

1. Run preflight¶

hyops preflight

For a specific init target:

hyops preflight --target <target>

Use --strict when optional gaps must make the command fail. Use --json when another tool needs the check report.

2. Read the report¶

Text output uses one line per check:

<status>  <check_id> <detail>

Common check identifiers include cmd:ssh, cmd:scp, vault:encryption, vault:data, vault:decrypt, runtime:meta, runtime:vault, and readiness:<target>. vault:data reports not initialized when no encrypted environment data exists; this is non-fatal until a workload requires secrets. The final exit_code=<n> line is the preflight result.

3. Act on failures¶

Exit 11: correct the runtime, readiness or strict capability failure.
Exit 12: install the missing required command and run preflight again.
Exit 21: correct the vault password source or encrypted vault file.
Exit 2: correct the command arguments.

4. Locate the run record¶

Every invocation prints a directory under:

<root>/logs/preflight/<run_id>/

The directory contains:

output.log: redacted output shown during the command
result.json: command, redacted arguments, timestamps, platform, status, and exit code

This record is created for successful and failed checks. There is no need to pipe the command through tee; direct execution preserves both the record and the real exit code.

5. Confirm readiness¶

Proceed only when the reported exit code is acceptable for the intended target. When the run supports a change or incident record, retain the printed run-record path.

References¶

License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.