HybridOps Documentation Portal¶
HybridOps is a contract-driven automation runtime for hybrid infrastructure. It separates intent, execution, governance, and implementation so the same modules run consistently across on-prem, cloud, and edge targets. This portal is the canonical reference for architecture, operations, and verification.
Start here¶
| Audience | Start here | What to expect |
|---|---|---|
| Engineer | Quickstart | Install, configure, run first module. |
| Reviewer | Review guide | Review path, verification anchors. |
| Learner | How-To index | Task-oriented procedures by category. |
Architecture model¶
HybridOps is built around four abstractions:
- Module — Declarative intent contract defining what outcome must be achieved. Modules specify inputs, constraints, probes, outputs, and credential requirements. They never contain tool wiring.
- Driver — Execution engine that renders isolated workdirs, invokes tools (Terraform, Packer, Ansible), captures redacted evidence, and normalises outputs.
- Profile — Governance layer defining backend strategy, naming rules, timeouts, tool version constraints, and logging policy. Profiles allow the same module to run in lab, enterprise, or strict compliance mode.
- Pack — Replaceable implementation bundle executed by a driver (Terragrunt stack, Terraform entrypoint, Packer template, GitOps manifest). Packs can be swapped without changing the module contract.
See Contracts and Standards for normative specifications.
What is documented here¶
| Area | Description | Entry point |
|---|---|---|
| Quickstart | Install HybridOps.Core and run the reference chain. | Quickstart |
| How-To guides | Task-oriented procedures grouped by domain. | How-To index |
| Runbooks | Reproducible operational procedures by category and severity. | Runbooks index |
| Showcases | End-to-end flows: CI/CD, DR, autoscaling, network automation. | Showcases |
| ADRs | Architecture decisions and trade-offs. | ADR index |
| Contracts | Normative behaviour specifications. | Contracts |
| Standards | Shared conventions and naming rules. | Standards |
| Evidence | Verification map linking claims to current procedures, runtime logs, and state. | Evidence map |
| Module index | All platform modules with specs and status. | Module index |
Product model¶
HybridOps is delivered as repositories with clear responsibilities:
| Repository | Role |
|---|---|
| HybridOps.Core | Runtime: hyops CLI, modules, drivers, probes, and operator utilities. Delivered as a versioned release tarball. |
| HybridOps.Workloads | GitOps-ready workload definitions consumed by Argo CD, organised by domain and environment. |
| HybridOps.Docs | This portal. Standards, contracts, ADRs, runbooks, HOWTOs, and evidence maps. |
| HybridOps.Workbench | Internal staging for hardening candidate modules, drivers, and workloads before promotion. |
Platform overview¶
HybridOps.Core targets hybrid infrastructure across:
- On-prem: Proxmox as first-class target with SDN, storage, and compute modules.
- Cloud: Azure and GCP landing zones with hybrid connectivity (including NCC hub-and-spoke).
- Edge: Hetzner for cost-efficient control surfaces and burst targets.
- Images: Packer pipelines for Linux (Ubuntu, Rocky) and Windows templates, consistent across control and workload planes.
- Provisioning: Terraform (via Terragrunt) for infrastructure, Ansible for configuration and verification, NetBox as source of truth.
- Delivery: Jenkins and GitHub Actions for CI/CD, Argo CD for GitOps reconciliation.
- Observability: Prometheus federation and decision service for autoscale, burst, failover, and failback.
- Networking: Explicit route governance validated through repeatable drills and recorded evidence.
Evidence-first operation¶
HybridOps is designed to be verifiable. The standard verification chain is:
ADR (why) → Contract/Standard (what must remain stable) → Runbook/HOWTO (how) → runtime logs and state (what was observed)
Every operation produces structured evidence, redacted tool output, deterministic paths, and normalised outputs.
Start with:
Guardrails¶
Cost is treated as a first-class design driver, alongside security and maintainability.
Contributing¶
See CONTRIBUTING.md.
License¶
- Code: MIT-0
- Documentation and diagrams: CC BY 4.0