From 31ac475c97576cfd30a49ba1970776f98bdff277 Mon Sep 17 00:00:00 2001
From: stewartshea <shea.stewart@runwhen.com>
Date: Tue, 30 Jun 2026 21:55:36 -0400
Subject: [PATCH] Update Crossplane GCP Bucket generation rules to use
 preferred API version

Modified the generation rules for Crossplane GCP Buckets to omit the version in resource type definitions, allowing the use of the API server's preferred version (currently v1beta2). Updated documentation to reflect this change and clarify version pinning for schema stability.

Changes include:
- Updated YAML generation rules to remove explicit versioning.
- Revised documentation to explain the implications of omitting versioning and the preferred version usage.

This enhances resilience across CRD upgrades and simplifies the configuration for users.
---
 .../generation-rules/gcp-bucket-crossplane-health.yaml |  9 ++++++---
 docs/03-crossplane-crd-discovery.md                    | 10 ++++++++--
 docs/04-generation-rule-walkthrough.md                 |  8 ++++++--
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/codebundles/gcp-bucket-crossplane-health/.runwhen/generation-rules/gcp-bucket-crossplane-health.yaml b/codebundles/gcp-bucket-crossplane-health/.runwhen/generation-rules/gcp-bucket-crossplane-health.yaml
index efb135a..4b4b1e0 100644
--- a/codebundles/gcp-bucket-crossplane-health/.runwhen/generation-rules/gcp-bucket-crossplane-health.yaml
+++ b/codebundles/gcp-bucket-crossplane-health/.runwhen/generation-rules/gcp-bucket-crossplane-health.yaml
@@ -4,12 +4,15 @@ spec:
   platform: kubernetes
   generationRules:
     # Discover every Crossplane GCP Bucket in the cluster.
-    # Resource type syntax: plural.group/version
+    # Resource type syntax: plural.group[/version]
     #   plural  = buckets            (from `kubectl api-resources | grep storage.gcp.upbound.io`)
     #   group   = storage.gcp.upbound.io
-    #   version = v1beta1            (omit /version to use the API server's preferred version)
+    #   version = omitted            (use the API server's preferred version — currently v1beta2)
+    #
+    # Pin an explicit version like `buckets.storage.gcp.upbound.io/v1beta1`
+    # if you need schema stability across CRD upgrades.
     - resourceTypes:
-        - buckets.storage.gcp.upbound.io/v1beta1
+        - buckets.storage.gcp.upbound.io
       matchRules:
         # Match every Bucket by name. Swap this regex to scope by naming
         # convention (for example `^prod-.*` to only cover prod buckets) or
diff --git a/docs/03-crossplane-crd-discovery.md b/docs/03-crossplane-crd-discovery.md
index 80be1ed..0fab275 100644
--- a/docs/03-crossplane-crd-discovery.md
+++ b/docs/03-crossplane-crd-discovery.md
@@ -24,12 +24,18 @@ Three things to note:
 
 1. **`buckets`** — this is the *plural resource name*. It is what you
    put in the generation rule, not the singular `Bucket`.
-2. **`storage.gcp.upbound.io/v1beta1`** — the API group and preferred
-   version.
+2. **`storage.gcp.upbound.io/v1beta2`** — the API group and preferred
+   version (older `v1beta1` may also be served for compatibility).
 3. **`false` in the "NAMESPACED" column** — Crossplane managed resources
    are **cluster-scoped**. This is why our generation rule uses
    `qualifiers: ["resource", "cluster"]` and not `namespace`.
 
+> **Version pinning:** our rule uses just `buckets.storage.gcp.upbound.io`
+> (no `/version`), which tells the indexer to use whatever the API server
+> reports as preferred. That's the most resilient choice across CRD
+> upgrades. Pin `/v1beta1` or `/v1beta2` only when you deliberately need
+> a specific schema.
+
 Screenshot placeholder: `images/03-kubectl-api-resources.png` — output of
 the above command.
 
diff --git a/docs/04-generation-rule-walkthrough.md b/docs/04-generation-rule-walkthrough.md
index f673e7e..689cd9b 100644
--- a/docs/04-generation-rule-walkthrough.md
+++ b/docs/04-generation-rule-walkthrough.md
@@ -14,7 +14,7 @@ spec:
   platform: kubernetes
   generationRules:
     - resourceTypes:
-        - buckets.storage.gcp.upbound.io/v1beta1
+        - buckets.storage.gcp.upbound.io
       matchRules:
         - type: pattern
           pattern: ".+"
@@ -53,9 +53,13 @@ spec:
 
 ```yaml
 resourceTypes:
-  - buckets.storage.gcp.upbound.io/v1beta1
+  - buckets.storage.gcp.upbound.io
 ```
 
+Omitting `/v1beta2` (or `/v1beta1`) tells the indexer to use the API
+server's preferred version, which survives CRD schema upgrades. Pin the
+version only when you rely on a specific schema shape.
+
 This is the *selective discovery* signal. Because this string appears in
 a loaded rule, the Kubernetes indexer knows to enumerate that CRD.
 Without any rule mentioning a CRD, it would not be listed.