Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Documentation roadmap

Aperta
  • Qualcosa non va?
#19 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
go, kubernetes
Ambito
documentation

Direzione di ricerca

La roadmap cita README.md, docs/reference/crd-api.md, docs/, config/samples/ e go.mod; inizia leggendo questi file e gli argomenti suggeriti per la prima fase. Crea le sottodirectory Diataxis, suddividi il README in una pagina di ingresso concisa con collegamenti e documenta i workflow e i requisiti selezionati. Mantieni allineati gli esempi e i riferimenti alla versione di Go ed esegui make api-docs quando cambiano i tipi API.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
Go
Stelle
1
Fork
0
Merge medio
16h 21m
PR unite (30g)
28

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

  • Include un Dockerfile o un file Docker Compose
  • Nessun modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di opdev/guestcluster

Tutte le issue di opdev/guestcluster

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.