Documentation roadmap

Documentation Roadmap

Background

This project is a Kubernetes operator that brokers disposable guest OpenShift
clusters for CI. It supports CRC single-node clusters and HyperShift hosted
control planes with KubeVirt workers. It has three audiences: CI engineers
(lease and use clusters), cluster operators (install and configure), and
contributors (Go/Kubebuilder development).

The repository has a roughly 750-line README.md and generated CRD API reference at
docs/reference/crd-api.md. The Diataxis framework
suggests splitting content by the user's need, along two axes: action versus
cognition and study versus work.

	Serves study (acquisition)	Serves work (application)
Action	Tutorials	How-to guides
Cognition	Explanation	Reference

---

Status

• R1: CRD API reference at docs/reference/crd-api.md.
• Split the README into focused documents while keeping it as a concise
  landing page.
• Resolve the documentation tasks below.

Planned Topics

Tutorials

• T1 - "Lease your first guest cluster": A CI engineer applies a
  ClusterLease, waits for Bound, reads its kubeconfig Secret, runs
  oc get nodes against the guest, then deletes the lease. The tutorial uses
  a ready, unclaimed instance in a preconfigured pool.
• T2 - "Deploy the operator on a prepared management cluster": An operator
  verifies the OpenShift Virtualization, storage, networking, and HyperShift
  prerequisites that apply; builds and publishes the manager and crc-agent
  images; runs make install and make deploy; configures CRC_AGENT_IMAGE;
  creates a first ClusterPool; and watches an instance reach Ready.
• T3 - "Set up local development and testing": A contributor clones the
  repository, runs make test with envtest, uses make test-e2e with Kind,
  and runs make run against a configured OpenShift management cluster.

How-to Guides

• H1 - Configure a CRC pool (turnkey template.crcVersion and manual
  releaseImage / bundleSSHKeyRef paths)
• H2 - Configure a HyperShift pool (KubeVirt NodePool sizing and control
  plane availability)
• H3 - Pre-warm a CRCBundle to speed up first provisioning
• H4 - Configure pull secrets (management cluster default or a custom
  pullSecretRef)
• H5 - Size pools to hypervisor capacity (minSize / warmSpares / maxSize)
• H6 - Consume a lease from a CI pipeline (scripted poll + kubeconfig extraction)
• H7 - Access a CRC guest API externally (Service + passthrough Route)
• H8 - Troubleshoot a stuck lease, instance, or bundle (capacity, failed
  provisioning, crc-agent/CSR failures, and bundle-prep failures)
• H9 - Build and push the crc-agent image
• H10 - Upgrade or uninstall the operator (make undeploy then
  make uninstall)

Reference

• R2 - Runtime configuration reference: manager environment variables
  (OPERATOR_NAMESPACE, CRC_AGENT_IMAGE, and service-account overrides)
  and flags (--metrics-bind-address, --leader-elect, and related TLS and
  probe flags).
• R3 - Makefile targets reference: every make target and its variables
  (IMG, CRC_AGENT_IMG).
• R4 - Resource lifecycle reference: CRCBundle, ClusterInstance, and
  ClusterLease phases, plus ClusterPool capacity and resource conditions.
• R5 - Prerequisites and deployment requirements: supported management
  OpenShift baseline, OpenShift Virtualization/CDI, HyperShift, OVNKubernetes,
  ingress, storage, LoadBalancer, registry access, and required images.

Explanation

• E1 - Architecture overview: the broker model, four controllers, four
  CRDs, crc-agent, and how supply (pool) meets demand (lease).
• E2 - The binding model: why the lease↔instance binding lives in exactly
  one place (ClusterLease.Status.InstanceRef), modeled on the Kube
  scheduler; why LeaseRef is a derived read-only projection.
• E3 - Recycle semantics & the disposable-cluster philosophy: why clusters
  are ephemeral and how clean-slate recycling works.
• E4 - CRC vs. HyperShift topologies: the tradeoffs, and which CI suites each is
  meant for.
• E5 - Why crc-agent exists: the post-boot fixup problem for CRC VMs and
  why it's a separate SSH-based Go binary reusing the bundle-prep image.

---

Structure And Priorities

Create docs/ subdirectories for
(tutorials/, how-to/, reference/, explanation/), keeping the README as
a concise landing page that links out. This addresses the current dense,
monolithic README.

Suggested first wave:

1. R5 Prerequisites and deployment requirements + T2 Deploy the operator
   (make installation requirements and the first deployment reliable)
2. T1 Lease your first cluster + H6 CI pipeline consumption (unblock the main
   consumer workflow)
3. H1/H2 pool configuration + H8 troubleshooting
4. E1 Architecture overview + E2 Binding model (move the established
   conceptual material out of the README)

Maintenance

• Keep examples aligned with the files in config/samples/.
• Keep the required Go version aligned with go.mod.
• Run make api-docs and commit docs/reference/crd-api.md after API type
  changes.

The roadmap names README.md, docs/reference/crd-api.md, docs/, config/samples/, and go.mod; start by reading those files and the suggested first-wave topics. Create the Diataxis subdirectories, split the README into a concise linked landing page, and document the selected workflows and requirements. Keep examples and Go-version references aligned, and run make api-docs when API types change.