# redhat-openshift-partner-labs/virtwork architecture

> Architecture diagram of the GitHub repository redhat-openshift-partner-labs/virtwork, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redhat-openshift-partner-labs/virtwork
- Repository: https://github.com/redhat-openshift-partner-labs/virtwork

## Overview

1. **What this repo is**
   - `virtwork` is a Go CLI and containerized operator-like tool that creates OpenShift Virtualization VMs, injects workload configuration, and exits.
   - It is not a long-running controller; VM workload lifecycle is expected to continue inside each guest via systemd-managed services.

2. **Top-level execution paths**
   - The main user flows are `run` and `cleanup`.
   - `run` provisions namespaces/resources/VMs for selected workloads, optionally waits for readiness, and records an audit trail.
   - `cleanup` finds managed resources by label and removes them, optionally scoped to a specific run ID.

3. **CLI and orchestration boundary**
   - `cmd/virtwork/main.go` is the orchestration entry point, likely wiring Cobra commands, config loading, and high-level action sequencing.
   - This layer depends on lower-level packages for cluster access, VM/resource creation, workload definitions, waiting, cleanup, and audit logging.

4. **Configuration and runtime inputs**
   - `internal/config` merges the precedence chain described in the README: CLI flags, `VIRTWORK_*` environment variables, YAML config file, then defaults.
   - Runtime behavior is also influenced by pod-level env vars in `deploy/deployment.yaml` and `entrypoint.sh` via `VIRTWORK_COMMAND` and `VIRTWORK_ARGS`.
   - The tool supports both local kubeconfig execution and in-cluster execution.

5. **Cluster access and Kubernetes abstraction layer**
   - `internal/cluster` initializes the Kubernetes/OpenShift client, likely using controller-runtime.
   - `internal/resources`, `internal/vm`, and `internal/wait` form the main Kubernetes abstraction layer:
     - resources: namespace, service, secret creation
     - vm: VM/VMI spec construction and CRUD
     - wait: readiness polling and synchronization

6. **Workload modeling layer**
   - `internal/workloads` contains the workload registry plus five implementations: CPU, memory, database, network, and disk.
   - Each workload encapsulates its own VM count, sizing, and guest-side bootstrap data, allowing the orchestration layer to treat workloads uniformly.
   - The network workload is structurally different from the others because it creates paired server/client VMs rather than simple N-instance fleets.

7. **Guest bootstrap and VM payload**
   - `internal/cloudinit` builds cloud-init/user-data used to configure VMs at boot.
   - This is where SSH access, startup configuration, and workload installation/launch details are injected into the guest.
   - The guest-side workload execution itself is outside the Go process; the repo only provisions the bootstrapping inputs.

8. **Workload-to-infrastructure data flow**
   - The orchestration layer selects enabled workloads, expands them into VM/resource requests, and labels every created object with managed-by and run-id metadata.
   - Those requests flow into `resources` and `vm`, which create the Kubernetes/OpenShift Virtualization objects.
   - `wait` then watches for VMI readiness before the command returns, unless `--no-wait` is set.

9. **Cleanup and lifecycle management**
   - `internal/cleanup` is intentionally label-driven and error-tolerant.
   - It discovers resources created by virtwork using labels rather than storing a separate inventory, which makes cleanup resilient even if a deployment was interrupted or the process crashed mid-run.
   - The optional `--delete-namespace` flag extends teardown beyond the managed objects themselves.

10. **Audit subsystem**
    - `internal/audit` provides local SQLite-backed execution tracking.
    - It records run metadata, workload/VM/resource details, and event timelines, keyed by a generated UUID `run-id`.
    - Audit is a local operational concern, not a remote service; the README notes no SSH credentials are persisted, only whether SSH was configured.

11. **Infrastructure and deployment packaging**
    - `deploy/` contains the OpenShift deployment packaging: namespace, RBAC, service account, ConfigMap, Secret, PVC, and Deployment.
    - The container image is built with a multi-stage Dockerfile: a Debian/Golang build stage for CGO/SQLite and a UBI-minimal runtime stage.
    - This packaging implies the binary can run either as a local CLI or as an in-cluster job-like pod.

12. **Testing and validation boundaries**
    - The repo separates unit tests, integration tests, and E2E tests.
    - `tests/e2e` exercises the full cluster lifecycle, while `internal/*_integration_test.go` validates Kubernetes-facing behavior against a real cluster.
    - `internal/testutil` and the per-package suite files suggest Ginkgo-style structured testing across layers.

13. **Architectural shape to draw**
    - A useful diagram should show a strict downward dependency chain: CLI/orchestration at the top, workload definitions in the middle, Kubernetes abstractions below that, then configuration/cluster/cloud-init support, with constants as shared definitions.
    - The external boundary is an OpenShift cluster with OpenShift Virtualization/KubeVirt, plus the local SQLite audit database and the optional container runtime environment around the CLI.

Main entry points: [`cmd/virtwork/main.go`](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/cmd/virtwork/main.go) (virtwork), [`internal/workloads/registry.go`](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/registry.go) (Registry), [`internal/cloudinit/cloudinit.go`](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/cloudinit/cloudinit.go) (Cloud-init), [`internal/cluster/cluster.go`](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/cluster/cluster.go) (Cluster)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_control["Control flow"]
  node_cmd_main["virtwork<br/>CLI entrypoint<br/>[main.go]"]
  node_config["Config<br/>[config.go]"]
  node_audit[("Audit<br/>run tracker<br/>[audit.go]")]
  node_cleanup["Cleanup<br/>label GC<br/>[cleanup.go]"]
end

subgraph group_grp_workloads["Workloads"]
  node_registry["Registry<br/>[registry.go]"]
  node_cpu["CPU<br/>workload impl<br/>[cpu.go]"]
  node_memory["Memory<br/>workload impl<br/>[memory.go]"]
  node_database["Database<br/>workload impl<br/>[database.go]"]
  node_network["Network<br/>paired workload<br/>[network.go]"]
  node_disk["Disk<br/>workload impl<br/>[disk.go]"]
  node_cloudinit["Cloud-init<br/>guest bootstrap<br/>[cloudinit.go]"]
  node_constants{{"Constants<br/>shared defs<br/>[constants.go]"}}
end

subgraph group_grp_platform["Cluster ops"]
  node_cluster["Cluster<br/>client init<br/>[cluster.go]"]
  node_resources["Resources<br/>namespace and svc<br/>[resources.go]"]
  node_vm["VM<br/>virt object ops<br/>[vm.go]"]
  node_wait(("Wait<br/>readiness sync<br/>[wait.go]"))
end

subgraph group_grp_packaging["Packaging"]
  node_deployment["Deploy<br/>runtime packaging<br/>[deployment.yaml]"]
  node_entrypoint["Entrypoint<br/>container start<br/>[entrypoint.sh]"]
  node_dockerfile["Image build<br/>container build"]
end

subgraph group_grp_external["External boundaries"]
  node_cluster_ext[("OpenShift cluster<br/>external platform")]
  node_vm_ext(("Guest VM<br/>external guest"))
  node_sqlite_ext[("SQLite DB<br/>external local state")]
end

node_cmd_main -->|"loads"| node_config
node_cmd_main -->|"selects"| node_registry
node_cmd_main -->|"connects"| node_cluster
node_cmd_main -->|"creates"| node_resources
node_cmd_main -->|"provisions"| node_vm
node_cmd_main -->|"waits"| node_wait
node_cmd_main -->|"tears down"| node_cleanup
node_cmd_main -->|"records"| node_audit
node_registry -->|"registers"| node_cpu
node_registry -->|"registers"| node_memory
node_registry -->|"registers"| node_database
node_registry -->|"registers"| node_network
node_registry -->|"registers"| node_disk
node_cpu -->|"boots"| node_cloudinit
node_memory -->|"boots"| node_cloudinit
node_database -->|"boots"| node_cloudinit
node_network -->|"boots"| node_cloudinit
node_disk -->|"boots"| node_cloudinit
node_cpu -->|"uses"| node_constants
node_memory -->|"uses"| node_constants
node_database -->|"uses"| node_constants
node_network -->|"uses"| node_constants
node_disk -->|"uses"| node_constants
node_cloudinit -->|"injects"| node_vm_ext
node_resources -->|"applies"| node_cluster
node_vm -->|"applies"| node_cluster
node_wait -->|"observes"| node_cluster
node_cleanup -->|"deletes"| node_cluster
node_cleanup -->|"filters"| node_constants
node_audit -->|"writes"| node_sqlite_ext
node_deployment -->|"starts"| node_entrypoint
node_entrypoint -->|"invokes"| node_cmd_main
node_deployment -->|"sets env"| node_config
node_dockerfile -->|"packages"| node_deployment
node_cluster -->|"targets"| node_cluster_ext

click node_cmd_main "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/cmd/virtwork/main.go"
click node_config "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/config/config.go"
click node_audit "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/audit/audit.go"
click node_cleanup "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/cleanup/cleanup.go"
click node_registry "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/registry.go"
click node_cpu "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/cpu.go"
click node_memory "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/memory.go"
click node_database "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/database.go"
click node_network "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/network.go"
click node_disk "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/disk.go"
click node_cloudinit "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/cloudinit/cloudinit.go"
click node_constants "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/constants/constants.go"
click node_cluster "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/cluster/cluster.go"
click node_resources "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/resources/resources.go"
click node_vm "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/vm/vm.go"
click node_wait "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/wait/wait.go"
click node_deployment "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/deploy/deployment.yaml"
click node_entrypoint "https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/entrypoint.sh"
click node_dockerfile "https://github.com/redhat-openshift-partner-labs/virtwork/tree/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_main,node_config,node_audit,node_cleanup toneBlue
class node_registry,node_cpu,node_memory,node_database,node_network,node_disk,node_cloudinit,node_constants toneAmber
class node_cluster,node_resources,node_vm,node_wait toneMint
class node_deployment,node_entrypoint,node_dockerfile toneRose
class node_cluster_ext,node_vm_ext,node_sqlite_ext toneIndigo
```

## Components

### Control flow

CLI entrypoint, configuration, orchestration, cleanup, and audit tracking.

- [virtwork](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/cmd/virtwork/main.go): CLI entrypoint · Main command wiring and top-level run/cleanup sequencing. · `cmd/virtwork/main.go`
- [Config](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/config/config.go): runtime config · Merges flags, env, config file, and defaults. · `internal/config/config.go`
- [Audit](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/audit/audit.go): run tracker · SQLite-backed run metadata and event timeline storage. · `internal/audit/audit.go`
- [Cleanup](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/cleanup/cleanup.go): label GC · Discovers and deletes managed resources by labels and run ID. · `internal/cleanup/cleanup.go`

### Workloads

Workload registry and per-workload sizing/bootstrap definitions.

- [Registry](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/registry.go): workload registry · Selects enabled workload implementations and expands them into actions. · `internal/workloads/registry.go`
- [CPU](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/cpu.go): workload impl · CPU stress workload sizing and payload definition. · `internal/workloads/cpu.go`
- [Memory](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/memory.go): workload impl · Memory pressure workload sizing and payload definition. · `internal/workloads/memory.go`
- [Database](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/database.go): workload impl · Database workload sizing and guest bootstrap definition. · `internal/workloads/database.go`
- [Network](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/network.go): paired workload · Server/client workload that provisions paired VMs. · `internal/workloads/network.go`
- [Disk](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/workloads/disk.go): workload impl · Disk I/O workload sizing and guest bootstrap definition. · `internal/workloads/disk.go`
- [Cloud-init](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/cloudinit/cloudinit.go): guest bootstrap · Builds user-data and startup configuration injected into VMs. · `internal/cloudinit/cloudinit.go`
- [Constants](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/constants/constants.go): shared defs · Common labels, names, and fixed values shared across packages. · `internal/constants/constants.go`

### Cluster ops

Kubernetes/OpenShift access, resource creation, VM management, and readiness waits.

- [Cluster](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/cluster/cluster.go): client init · Initializes Kubernetes/OpenShift client access. · `internal/cluster/cluster.go`
- [Resources](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/resources/resources.go): namespace and svc · Creates namespaces, services, secrets, and related managed objects. · `internal/resources/resources.go`
- [VM](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/vm/vm.go): virt object ops · Constructs and manages VM/VMI specs and lifecycle operations. · `internal/vm/vm.go`
- [Wait](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/internal/wait/wait.go): readiness sync · Polls and synchronizes on VM/VMI readiness. · `internal/wait/wait.go`

### Packaging

Container and deployment assets that shape runtime behavior.

- [Deploy](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/deploy/deployment.yaml): runtime packaging · Deployment manifests that define in-cluster execution and env wiring. · `deploy/deployment.yaml`
- [Entrypoint](https://github.com/redhat-openshift-partner-labs/virtwork/blob/main/entrypoint.sh): container start · Container startup script that passes command and args into the binary. · `entrypoint.sh`
- [Image build](https://github.com/redhat-openshift-partner-labs/virtwork/tree/main/Dockerfile): container build · Multi-stage image build for the CLI and runtime container. · `Dockerfile`

### External boundaries

Cluster, guest VMs, and local audit storage outside the Go codebase.

- **OpenShift cluster**: external platform · Target cluster providing Kubernetes and OpenShift Virtualization APIs.
- **Guest VM**: external guest · Provisioned virtual machine where workload services run after boot.
- **SQLite DB**: external local state · Local on-disk audit database used for execution tracking.

## Connections

- virtwork → Config: loads · CLI startup resolves configuration precedence and runtime mode.
- virtwork → Registry: selects · Top-level commands choose which workloads to run.
- virtwork → Cluster: connects · Commands initialize cluster access before resource operations.
- virtwork → Resources: creates · Run flow provisions namespaces and supporting objects.
- virtwork → VM: provisions · Run flow creates and manages VMs for selected workloads.
- virtwork → Wait: waits · Optional readiness synchronization before exit.
- virtwork → Cleanup: tears down · Cleanup command removes managed resources by label.
- virtwork → Audit: records · Execution metadata and event timeline are persisted locally.
- Registry → CPU: registers · Registry includes CPU workload implementation.
- Registry → Memory: registers · Registry includes memory workload implementation.
- Registry → Database: registers · Registry includes database workload implementation.
- Registry → Network: registers · Registry includes network workload implementation.
- Registry → Disk: registers · Registry includes disk workload implementation.
- CPU → Cloud-init: boots · Workload definitions feed guest bootstrap payloads.
- Memory → Cloud-init: boots · Workload definitions feed guest bootstrap payloads.
- Database → Cloud-init: boots · Workload definitions feed guest bootstrap payloads.
- Network → Cloud-init: boots · Paired network workload injects server/client bootstrap data.
- Disk → Cloud-init: boots · Workload definitions feed guest bootstrap payloads.
- CPU → Constants: uses · Workload sizing and labels reuse shared constants.
- Memory → Constants: uses · Workload sizing and labels reuse shared constants.
- Database → Constants: uses · Workload sizing and labels reuse shared constants.
- Network → Constants: uses · Workload sizing and labels reuse shared constants.
- Disk → Constants: uses · Workload sizing and labels reuse shared constants.
- Cloud-init → Guest VM: injects · Cloud-init content is consumed by guest VMs at boot.
- Resources → Cluster: applies · Resource creation uses cluster client access.
- VM → Cluster: applies · VM CRUD operations target the cluster APIs.
- Wait → Cluster: observes · Readiness polling watches cluster resources.
- Cleanup → Cluster: deletes · Cleanup removes managed resources from the cluster.
- Cleanup → Constants: filters · Cleanup uses shared labels and run metadata conventions.
- Audit → SQLite DB: writes · Audit records are stored in local SQLite.
- Deploy → Entrypoint: starts · Pod spec launches the container through the entrypoint script.
- Entrypoint → virtwork: invokes · Container environment forwards command and arguments to the binary.
- Deploy → Config: sets env · Deployment manifest provides runtime environment variables.
- Image build → Deploy: packages · Image build and deployment manifest define in-cluster execution.
- Cluster → OpenShift cluster: targets · Client initialization connects to the external cluster boundary.