simple-private-codecollection/docs/01-overview.md

01 — Overview

What you'll do in this guide

By the end of this guide you will have a private RunWhen CodeCollection that:

1. Is hosted in your Gitea instance (already the case for this workspace — see https://gitea.airgap.shared.runwhen.com/gitea-admin/simple-private-codecollection).
2. Contains no Robot Framework code of its own. It only ships two things:
   • Generation rules — YAML that tells RunWhen's workspace-builder which resources to discover in the cluster and how many SLXs to generate for each match.
   • Templates — Jinja files that render the ServiceLevelX, ServiceLevelIndicator, and Runbook resources for each match.
3. Reuses an existing generic codebundle — k8s-kubectl-cmd from rw-generic-codecollection — as the runtime for every generated SLI and TaskSet.
4. Discovers Crossplane GCP Bucket custom resources (buckets.storage.gcp.upbound.io/v1beta1) and produces one SLX per Bucket with a fractional health SLI and a detailed condition-based TaskSet.

Vocabulary primer

Term	Meaning
CodeCollection	A Git repository, cloned by RunWhen, that contains one or more codebundles. This repo is a CodeCollection.
CodeBundle	A subdirectory of a CodeCollection (codebundles/<name>/). Traditionally contains Robot Framework code plus discovery rules. Ours contains only discovery rules and templates.
Generation rule	YAML under .runwhen/generation-rules/. Declares which resource types to scan and how to build SLXs from matches.
Template	Jinja YAML under .runwhen/templates/. Rendered per matching resource by workspace-builder to produce the final SLX / SLI / Runbook artifacts.
SLX	A "Service Level X" — the top-level unit of monitoring in RunWhen. Bundles together an SLI, an optional SLO, and one or more Runbooks.
SLI	Service Level Indicator — a numeric health signal (here 0.0 to 1.0) pushed on an interval.
Runbook / TaskSet	The interactive troubleshooting sequence. Called a "Runbook" in kind, "TaskSet" in the UI.
workspace-builder	The pod (image runwhen-local) that clones code collections, indexes resources, matches generation rules, renders templates, and uploads the resulting workspace to the platform.

The pattern in one diagram

(Placeholder — replace with a screenshot exported from your diagramming tool once the flow is verified end-to-end.)

flowchart LR
  Private["Gitea<br/>simple-private-codecollection<br/>(rules + templates)"]
  WB["workspace-builder<br/>(clones + indexes + renders)"]
  Cluster[("GKE cluster<br/>Crossplane Bucket CRDs")]
  Generic["rw-generic-codecollection<br/>k8s-kubectl-cmd<br/>(sli.robot + runbook.robot)"]

  Private --> WB
  Cluster --> WB
  WB -->|"one SLX per Bucket"| Platform["RunWhen Platform"]
  Platform -->|"Runner pulls robots from"| Generic
  Generic -->|kubectl + jq| Cluster

When to use this pattern

Choose the "generation-rule only" pattern when:

• You want to discover organization-specific resources (CRDs, tags, labels) without maintaining a fork of the shared code collections.
• The runtime already exists as a generic bundle (k8s-kubectl-cmd, curl-cmd, gcloud-cmd, aws-cmd, etc.) and you just need to point it at the right target.
• You want changes to your discovery rules to land without a codebundle runner image rebuild — workspace-builder re-clones on each reconcile.

Do NOT use it when you need custom Robot keywords, a task that can't be expressed as a single kubectl/gcloud/curl command, or a runtime that isn't already available in a generic bundle.

Next

Continue to 02 — Generation-rule-only pattern.