docs: comprehensive overhaul to match current code surface#60
Merged
Conversation
…ture The workload table only listed five workloads. Expand it to all nine grouped by purpose (core load generators, multi-VM benchmarks, chaos engineering) and call out the actual 11-VM default for a no-flag run. Update the architecture summary and project structure tree to include internal/logging, build/golden-image, the new docs files, and the MultiVMWorkload interface. Add pointers from the configuration, audit, and deployment sections to their respective deep-dive documents, and add a Makefile shortcut block since users land on the README and otherwise miss `make ci`/`make verify`. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
The mermaid layered architecture diagram only showed five workloads and omitted the internal/logging package added when structured logging replaced fmt.Fprintf calls. Redraw it to include: - All nine workloads grouped beneath the registry (cpu, memory, disk, database in core; network and tps as multi-VM via the new MultiVMWorkload interface; chaos-disk, chaos-network, chaos-process) - The MultiVMWorkload interface as its own node, since network and tps implement Roles() and UserdataForRole() on top of Workload - internal/logging in Layer 1, with edges from cmd/virtwork and from internal/wait (the two current consumers) Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
…chaos The class diagram covered only the original five workloads and did not show MultiVMWorkload at all, even though two workloads (network, tps) implement it. Expand the diagram to include: - MultiVMWorkload interface (Roles, UserdataForRole) sitting above Workload, with NetworkWorkload and TPSWorkload realizing it - TPSWorkload, ChaosDiskWorkload, ChaosNetworkWorkload, ChaosProcessWorkload with their concrete Name(), userdata characteristics, and any extra storage / service surface - Notes on virtio Serial fields for disk-backed workloads, since the in-VM disk discovery now goes through /dev/disk/by-id/virtio-<serial> NetworkWorkload was previously shown with invented ServerUserdata()/ ClientUserdata() methods; replace with the actual UserdataForRole entry point and accurate service port (5201). TPS service shows the three ports actually exposed: netperf-ctrl 12865, netperf-data 12866, http-data 8080. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
Update the Workload Comparison table to nine rows including tps and the three chaos workloads. Show actual service names and ports (network -> virtwork-iperf3-server :5201; tps -> virtwork-tps-server :12865/12866/8080), correct package lists per workload, and the tools each one runs. Add internal/logging to the Concurrency Model table — it is stateless and shared across goroutines that call it. Add four rows to Key Design Decisions: - In-VM disk discovery via virtio Serial. /dev/vdX ordering is not stable across reboots; the diskSetupScript helper handles wait/format/mount/fstab. - DataVolume per-VM name suffixing via namespaceDataVolumes, since DataVolume names are namespace-scoped and would collide across VMs. - Structured logging via internal/logging (slog), set by --verbose. - Chaos workload safety — opt-in by name with namespace isolation as the boundary, no kill switch. Cross-link chaos-workloads.md. Also cross-link audit-schema.md from the audit storage row. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
… tree The architecture.md project structure listed docs/engineering-journals/ but the directory does not exist, and the CLAUDE.md guideline explicitly forbids committing engineering journals. Remove the entry rather than recreate a confused state. Refresh the project tree to match reality: - Add internal/logging and the four newly-existing workload files (tps.go, chaos_disk.go, chaos-network.go, chaos_process.go) - Update internal/workloads/workload.go description to mention MultiVMWorkload and the diskSetupScript helper - Update registry.go description to "nine entries" - Add build/golden-image/, the new reference docs (configuration.md, deployment.md, audit-schema.md, chaos-workloads.md), docs/README.md, and docs/guide/ - Add Dockerfile.ci, Makefile, OWNERS for completeness Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
…sh layout The development guide referenced engineering-journals/ (now removed), described five workloads instead of nine, and missed three patterns that new contributors need: - Multi-VM workloads via the MultiVMWorkload interface (Roles, UserdataForRole, in-cluster DNS for client-server coordination). The canonical references are network.go (simple) and tps.go (configurable Params). - Storage-backed workloads via the virtio Serial field on Disk plus the shared diskSetupScript helper that waits for /dev/disk/by-id/virtio-*, formats, mounts, and writes /etc/fstab. References: disk.go, database.go, chaos_disk.go. - Structured logging via internal/logging.NewLogger — JSON output, --verbose flips INFO to DEBUG. Workload pure-data layer does not log. Update the registry example to all nine current entries, refresh the project layout tree (add internal/logging, build/golden-image/, deploy/, new docs), and add internal/logging to the architecture layers table. Add a Related Documentation section linking the new reference docs, and note the DCO Signed-off-by hook in the commit conventions section. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
…workloads The complexity table listed only five workloads. Expand to all nine, grouping by overrides-beyond-Name+CloudInit: - Simplest: cpu, memory, chaos-process, chaos-network - Medium (storage-backed): disk, database, chaos-disk — all using the virtio Serial + diskSetupScript pattern - Most complex (multi-VM): network and tps — both implementing MultiVMWorkload with Roles and UserdataForRole Update the "Finding Your Way Around the Code" table to include the new workload files, the diskSetupScript helper, the namespaceDataVolumes orchestration helper, the internal/logging package, the build/golden-image directory, and a pointer to audit-schema.md. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
Scenario 3 claimed the default run produces 8 VMs; with the three chaos workloads now in DefaultRegistry, the actual count is 11. Update the VM table to include chaos-disk, chaos-network, chaos-process, and add a warning callout that chaos workloads need an isolated namespace. Add two new scenarios: - Scenario 8: deploy chaos-network and verify the tc/netem qdisc inside the VM with `tc qdisc show` and a ping. - Scenario 9: deploy tps, watch the journalctl output for alternating TCP_RR and HTTP iterations, and show how to override file-size / iterations / duration via WorkloadConfig.Params in YAML. Update the troubleshooting workload list to all nine names and add a row for the chaos-network sch_netem kernel module dependency. Cross-link deployment.md from the cluster-deployment scenario. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
…tterns The tutorial's "Going Further" sections covered storage and multi-VM at a sketch level. Two patterns that contributors actually need: - For storage-backed workloads, always set the virtio Serial field on Disk and discover the device through /dev/disk/by-id/virtio-<serial> using the shared diskSetupScript helper. /dev/vdX ordering is not stable across reboots. Reference workloads: disk.go, database.go, chaos_disk.go. - For multi-VM workloads, implement MultiVMWorkload with Roles() and UserdataForRole(); the orchestrator dispatches per role. Clients reach servers via in-cluster DNS (<service>.<namespace>.svc.cluster.local). Reference workloads: network.go (simple), tps.go (configurable Params). Update the complexity spectrum diagram to show all nine workloads grouped into the three tiers, and extend the checklist with explicit multi-VM and storage-backed subsections. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
Both documents describe the project at an earlier point in time: - implementation-plan.md captures the original layered build through phase 12, before chaos workloads, tps, structured logging, and the golden image were added. - openshift-virtualization-workload-automation.md was written before any application code existed and describes initial design rationale. Neither should be updated piecemeal — they become inconsistent if treated as living docs. Prepend a banner to each pointing at the current source of truth (architecture.md, chaos-workloads.md, configuration.md, etc.) and leave the body unchanged. Preserves the historical record while making the freshness obvious to readers. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
The pre-installed-tools list mentioned iproute-tc and iptables-nft as "for future chaos workloads", but two of the three chaos workloads already exist (chaos-network uses tc/netem; chaos-disk uses fallocate/dd from the base image). Update the list to: - Map each tool to the specific workload(s) that need it - Add netperf + python3 for the tps workload (which were already in the Containerfile but unlisted) - Add procps-ng for chaos-process - Note that iptables-nft is still future-only (network partition tests) - Mention that storage-backed workloads rely only on base-image utilities (blkid, mkfs.xfs, mount) via the diskSetupScript helper Add a Related Docs section pointing back to the chaos-workloads guide, deployment guide, and configuration reference. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
Add four guidance items that came up while overhauling documentation: - DCO Signed-off-by is required by a commit-msg hook; do not add a Co-Authored-By trailer - internal/logging.NewLogger() is the canonical logger for I/O code; the pure data layer (workloads, cloudinit) does not log - docs/README.md is the index for the docs directory - Mermaid for diagrams; no bare issue numbers in published docs - The two historical snapshots (implementation-plan.md, openshift-virtualization-workload-automation.md) are intentionally frozen — new content goes into the live docs Also clarify that engineering journals being absent is the policy, not a missing directory. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
There are now twelve documents under docs/ plus the golden-image README and the top-level README. Add a TOC so readers can navigate without having to discover docs by guessing filenames or scrolling through git history. Group entries by purpose: Start Here (README + architecture), Guides (narrative walkthroughs), Reference (config / chaos / audit-schema / deployment / kube-burner comparison), Contributor (development guide + golden-image build), Historical (the two intentionally frozen snapshots). Note the directory-wide conventions at the bottom — mermaid for diagrams, no bare issue numbers, historical docs stay frozen — so future contributors don't reintroduce the patterns this overhaul removed. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
The three chaos engineering workloads (chaos-disk, chaos-network, chaos-process) had no operator-facing documentation. Add a single guide that covers all three, structured so an operator can land on it cold and decide whether/how to deploy. Contents: - Quick comparison table and a prominent destructive-behavior warning (impact confined to the VM; namespace isolation is the safety boundary). - Per-workload section with what it does, a mermaid flow diagram where helpful, configuration knobs (YAML params with defaults and effect), the in-VM dependencies (iproute-tc + sch_netem for chaos-network), end-to-end example with virtctl ssh commands, and what to observe in monitoring. - Operational guidance on running chaos alongside non-chaos workloads (cross-VM impact only happens via application reach), cleanup, and audit visibility. - Contributor section pointing at the source files and the shared patterns (BaseWorkload, BuildCloudConfig, diskSetupScript) so anyone adding a fourth chaos workload knows where to look. Configuration knobs are documented at the user-facing layer (WorkloadConfig.Params keys like fill-percent, latency-ms, signal) so this guide serves as the spec for how those parameters should be wired through. The plumbing matches what tps already does today. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
audit_log was partially documented in the README's audit section but the other four tables (workload_details, vm_details, resource_details, events) had no documentation. Anyone querying the database had to reverse-engineer the schema from `.schema` output. Cover the schema end-to-end: - A mermaid erDiagram showing all five tables, their PK/FK relationships, and the most useful columns at a glance - One subsection per table with every column (type, NOT NULL, FK target, description) — sourced from internal/audit/schema.go - Enumeration of the event_type values currently emitted by the orchestrator, with when each fires - A sequenceDiagram showing the lifecycle: StartExecution → per-workload → per-service → per-VM → readiness → CompleteExecution - Seven common queries covering the most useful operational questions (recent runs, VMs per run, events timeline, failed runs, cleanup linking, totals, average ready latency) - Contributor section explaining how to add a column or event type, with the PostgreSQL-compatibility constraints (TEXT for ISO 8601 timestamps and JSON-shaped data) called out Cross-link from configuration.md, deployment.md, and development.md. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
Configuration was documented in three places (README env-var table, development.md SSH/audit sections, deploy/configmap.yaml comments) and none of them was complete. Per-workload params (tps file-size / iterations / duration; chaos-disk fill-percent etc.) were not documented at all, and the per-workload YAML override surface was opaque. Consolidate everything into a single reference: - Three full flag tables (global persistent, run, cleanup) with flag / env var / YAML key / default / description per row - One alphabetical environment-variable table, including the two deployment-only entrypoint vars (VIRTWORK_COMMAND, VIRTWORK_ARGS) with a callout that those are read by entrypoint.sh, not by Viper - A full YAML config schema covering every key including per-workload overrides for all nine workloads, with comments showing default values - A per-workload params table (tps file-size/iterations/duration; chaos-disk mount/fill-percent/fill-sleep/release-sleep; chaos-network latency-ms/packet-loss-percent; chaos-process signal/interval/min-pid) — documented as the spec for user-tunable parameters, including the ones not yet wired through WorkloadConfig.Params - A ConfigMap-key reference matching the in-cluster defaults from deploy/configmap.yaml - A priority-chain mermaid + a step-by-step walkthrough of how internal/config/config.go LoadConfig applies the chain (including the --no-audit short-circuit handled outside the chain) - A contributor section explaining the mapstructure tag convention and where to wire new params Cross-link from chaos-workloads, deployment, development, audit-schema. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
The README's OpenShift Deployment section is a quick orientation; the full surface (ConfigMap keys, RBAC scope, entrypoint behavior, PVC ownership, image pinning policy, security context, DataVolume name observation) was not documented. Cover the full deployment story: - A mermaid topology diagram showing Namespace + ServiceAccount + RBAC + ConfigMap + Secret + PVC + Deployment + Pod relationships - A manifest-by-manifest table with file path and purpose - VIRTWORK_COMMAND and VIRTWORK_ARGS semantics: how entrypoint.sh dispatches between run / cleanup / sleep, including the unquoted-args constraint (no spaces inside argument values) - Interactive vs auto-execute deployment patterns - Image pinning policy (semver vs :latest, imagePullPolicy implications, podman build commands, multi-stage Dockerfile + Dockerfile.ci) - Using the golden image by setting VIRTWORK_CONTAINER_DISK_IMAGE in the ConfigMap - Full RBAC scope table explaining why each verb is needed (and why the role is cluster-scoped because Namespaces are cluster-scoped) - Sizing guidance and the note that VM resource sizing happens at the VirtualMachine spec, not the virtwork pod limits - Why DataVolume names look like virtwork-disk-data-virtwork-disk-0 (the namespaceDataVolumes suffix from cmd/virtwork/main.go that prevents collisions across multiple VMs of the same workload) - Audit DB persistence on a separate PVC so upgrades preserve history, with copy-out and in-place query patterns - Security context defaults (runAsNonRoot, RuntimeDefault seccomp, capabilities ALL dropped) so reviewers know what's in place - Uninstall commands distinguishing pod-only vs full removal Cross-link from README, configuration.md, audit-schema.md, chaos-workloads.md, and the golden-image README. Signed-off-by: Melvin Hillsman <mhillsma@redhat.com>
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: mrhillsman The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
exe-prow-github-app
Bot
added
the
approved
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
internal/loggingpackage, theMultiVMWorkloadinterface, virtio-serial disk discovery, DataVolume per-VM namespacing, and structured logging viaslog.docs/README.md(TOC),docs/chaos-workloads.md(operator guide with destructive-behavior warnings),docs/audit-schema.md(five-table ERD + lifecycle sequence + common queries),docs/configuration.md(every flag / env var / YAML key / ConfigMap key + per-workload params), anddocs/deployment.md(Kustomize topology, RBAC scope,VIRTWORK_COMMAND/VIRTWORK_ARGSsemantics, image pinning, sizing, audit-DB persistence).What this changes
README.mddocs/architecture.mddocs/development.mddiskSetupScript), and structured logging; DCO + Co-Authored-Bydocs/guide/01-overview.mddocs/guide/02-deploying-workloads.mdparams); troubleshooting workload list to 9docs/guide/03-adding-a-workload.mddocs/implementation-plan.mddocs/openshift-virtualization-workload-automation.mdbuild/golden-image/README.mdCLAUDE.mdinternal/loggingas canonical logger, DCO trailer requireddocs/README.mddocs/chaos-workloads.mddocs/audit-schema.mddocs/configuration.mddocs/deployment.md