# 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`](https://github.com/runwhen-contrib/rw-generic-codecollection/tree/main/codebundles/k8s-kubectl-cmd) —
   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

![overview diagram](images/01-overview-diagram.png)

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

```mermaid
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](02-generation-rules-only-pattern.md).