Skip to content

HOWTO: Author a Module Spec

Purpose: Write a compliant HybridOps module spec that passes preflight and produces structured run records.

Difficulty: Advanced

Track: Contract-Driven Automation

Overview

Validate early with hyops module validate. Required sections are inputs, contract, steps, and run_record. Missing or invalid keys cause hyops preflight to reject the module before any execution begins.

1. Module Spec File Layout

  • File location and naming conventions.
  • Required top-level keys: id, version, contract, inputs, steps, the run-record contract.
  • Schema validation with hyops module validate.

2. Declaring Inputs

  • Required vs optional inputs.
  • Supported types: string, integer, boolean, secret, list, map.
  • Constraints: min/max, allowed values, regex patterns.
  • Secret references and how HybridOps resolves them at runtime.

3. Writing the Contract Block

  • description, side_effects, and rollback_intent.
  • Idempotency declaration.
  • Dependency references to other module IDs.

4. Defining Steps

  • Step schema: name, action, inputs, on_fail.
  • Built-in action types and custom action hooks.
  • Conditional steps and environment guards.
  • Rollback step registration.

5. Declaring Run Records

  • Record types: config snapshot, probe result, diff, log extract.
  • Path patterns and timestamp interpolation.
  • Linking run records to specific steps.

6. Validating and Testing the Spec

  • Running hyops module validate locally.
  • Preflight dry-run against a test environment.
  • Unit testing input constraints.

References

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