feat(versioned)!: Require crd(doc = "...") to override the CRD root description (#1228)

lfrancke · sbernauer · web-flow · commit c1c2fff3b7e9 · 2026-06-22T12:18:36.000Z
* feat(versioned): support crd(doc = "...") to override the CRD root description * feat(versioned)!: Make the crd(doc = "...") argument required Following review feedback on #1228, the `doc` argument is now mandatory so that every CRD ships a meaningful root description instead of the generic "Auto-generated derived type ..." string. - StructCrdArguments.doc: Option<String> -> String (required via darling) - codegen always emits `doc = ...` in the generated #[kube(...)] - add doc to all CRDs defined in stackable-operator (AuthenticationClass, Listener, ListenerClass, PodListeners, S3Bucket, S3Connection, Scaler) - add doc to all macro test inputs / doc examples; regenerate snapshots - regenerate committed CRD YAMLs * Update crates/stackable-operator/src/crd/listener/listeners/mod.rs Co-authored-by: Sebastian Bernauer <sebastian.bernauer@stackable.de> * Update crates/stackable-operator/crds/Listener.yaml Co-authored-by: Sebastian Bernauer <sebastian.bernauer@stackable.de> --------- Co-authored-by: Sebastian Bernauer <sebastian.bernauer@stackable.de>
diff --git a/crates/stackable-operator/CHANGELOG.md b/crates/stackable-operator/CHANGELOG.md
@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Add root descriptions to all CRDs defined in this crate (`AuthenticationClass`, `Listener`,
+  `ListenerClass`, `PodListeners`, `S3Bucket`, `S3Connection`, `Scaler`), now that the `versioned`
+  macro requires a `doc` argument ([#1228]).
+
+[#1228]: https://github.com/stackabletech/operator-rs/pull/1228
+
 ## [0.112.0] - 2026-06-22
 
 ### Added
diff --git a/crates/stackable-operator/crds/AuthenticationClass.yaml b/crates/stackable-operator/crds/AuthenticationClass.yaml
@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for AuthenticationClassSpec via `CustomResource`
+        description: The Stackable Platform uses the AuthenticationClass as a central mechanism to handle user authentication across supported products.
         properties:
           spec:
             description: |-
diff --git a/crates/stackable-operator/crds/DummyCluster.yaml b/crates/stackable-operator/crds/DummyCluster.yaml
@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for DummyClusterSpec via `CustomResource`
+        description: A DummyCluster is a test-only resource used by operator-rs to exercise CRD generation. It is not backed by a real operator.
         properties:
           spec:
             properties:
diff --git a/crates/stackable-operator/crds/Listener.yaml b/crates/stackable-operator/crds/Listener.yaml
@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for ListenerSpec via `CustomResource`
+        description: Exposes a set of Pods to the outside world.
         properties:
           spec:
             description: |-
diff --git a/crates/stackable-operator/crds/ListenerClass.yaml b/crates/stackable-operator/crds/ListenerClass.yaml
@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for ListenerClassSpec via `CustomResource`
+        description: Defines a policy for how Listeners should be exposed.
         properties:
           spec:
             description: |-
diff --git a/crates/stackable-operator/crds/PodListeners.yaml b/crates/stackable-operator/crds/PodListeners.yaml
@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for PodListenersSpec via `CustomResource`
+        description: Informs users about Listeners that are bound by a given Pod.
         properties:
           spec:
             description: |-
diff --git a/crates/stackable-operator/crds/S3Bucket.yaml b/crates/stackable-operator/crds/S3Bucket.yaml
@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for BucketSpec via `CustomResource`
+        description: S3 bucket specification containing the bucket name and an inlined or referenced connection specification.
         properties:
           spec:
             description: |-
diff --git a/crates/stackable-operator/crds/S3Connection.yaml b/crates/stackable-operator/crds/S3Connection.yaml
@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for ConnectionSpec via `CustomResource`
+        description: A reusable definition of a connection to an S3 endpoint.
         properties:
           spec:
             description: |-
diff --git a/crates/stackable-operator/crds/Scaler.yaml b/crates/stackable-operator/crds/Scaler.yaml
@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for ScalerSpec via `CustomResource`
+        description: Controls the replica count of a Stackable component, integrating with the Kubernetes scale subresource to enable horizontal autoscaling.
         properties:
           spec:
             properties:
diff --git a/crates/stackable-operator/src/crd/authentication/core/mod.rs b/crates/stackable-operator/src/crd/authentication/core/mod.rs
@@ -36,6 +36,7 @@ pub mod versioned {
     #[versioned(crd(
         group = "authentication.stackable.tech",
         plural = "authenticationclasses",
+        doc = "The Stackable Platform uses the AuthenticationClass as a central mechanism to handle user authentication across supported products.",
     ))]
     #[derive(
         Clone,
diff --git a/crates/stackable-operator/src/crd/listener/class/mod.rs b/crates/stackable-operator/src/crd/listener/class/mod.rs
@@ -25,7 +25,10 @@ pub mod versioned {
     /// Defines a policy for how [Listeners](DOCS_BASE_URL_PLACEHOLDER/listener-operator/listener) should be exposed.
     /// Read the [ListenerClass documentation](DOCS_BASE_URL_PLACEHOLDER/listener-operator/listenerclass)
     /// for more information.
-    #[versioned(crd(group = "listeners.stackable.tech"))]
+    #[versioned(crd(
+        group = "listeners.stackable.tech",
+        doc = "Defines a policy for how Listeners should be exposed.",
+    ))]
     #[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema, PartialEq)]
     #[serde(rename_all = "camelCase")]
     pub struct ListenerClassSpec {
diff --git a/crates/stackable-operator/src/crd/listener/listeners/mod.rs b/crates/stackable-operator/src/crd/listener/listeners/mod.rs
@@ -52,6 +52,7 @@ pub mod versioned {
     #[versioned(crd(
         group = "listeners.stackable.tech",
         status = "v1alpha1::ListenerStatus",
+        doc = "Exposes a set of Pods to the outside world.",
         namespaced
     ))]
     #[derive(
@@ -86,6 +87,7 @@ pub mod versioned {
     #[versioned(crd(
         group = "listeners.stackable.tech",
         plural = "podlisteners",
+        doc = "Informs users about Listeners that are bound by a given Pod.",
         namespaced,
     ))]
     #[derive(
diff --git a/crates/stackable-operator/src/crd/s3/bucket/mod.rs b/crates/stackable-operator/src/crd/s3/bucket/mod.rs
@@ -25,6 +25,7 @@ pub mod versioned {
         group = "s3.stackable.tech",
         kind = "S3Bucket",
         plural = "s3buckets",
+        doc = "S3 bucket specification containing the bucket name and an inlined or referenced connection specification.",
         namespaced
     ))]
     #[derive(Clone, CustomResource, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
diff --git a/crates/stackable-operator/src/crd/s3/connection/mod.rs b/crates/stackable-operator/src/crd/s3/connection/mod.rs
@@ -35,6 +35,7 @@ pub mod versioned {
         group = "s3.stackable.tech",
         kind = "S3Connection",
         plural = "s3connections",
+        doc = "A reusable definition of a connection to an S3 endpoint.",
         namespaced
     ))]
     #[derive(CustomResource, Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
diff --git a/crates/stackable-operator/src/crd/scaler/mod.rs b/crates/stackable-operator/src/crd/scaler/mod.rs
@@ -17,6 +17,7 @@ pub mod versioned {
             status_replicas_path = ".status.replicas",
             label_selector_path = ".status.selector"
         ),
+        doc = "Controls the replica count of a Stackable component, integrating with the Kubernetes scale subresource to enable horizontal autoscaling.",
         namespaced
     ))]
     #[derive(Clone, Debug, PartialEq, Eq, CustomResource, Deserialize, Serialize, JsonSchema)]
diff --git a/crates/stackable-versioned-macros/src/attrs/container.rs b/crates/stackable-versioned-macros/src/attrs/container.rs
@@ -53,6 +53,9 @@ pub struct ContainerSkipArguments {
 /// - `scale`: Configure the scale subresource for horizontal pod autoscaling integration.
 /// - `shortname`: Set a shortname for the CR object. This can be specified multiple
 ///   times.
+/// - `doc`: Set the root description of the generated CRD. This argument is required, so
+///   that every CRD has a meaningful description instead of the generic one that kube
+///   generates by default.
 /// - `skip`: Controls skipping parts of the generation.
 #[derive(Clone, Debug, FromMeta)]
 pub struct StructCrdArguments {
@@ -71,7 +74,7 @@ pub struct StructCrdArguments {
     pub shortnames: Vec<String>,
     // category
     // selectable
-    // doc
+    pub doc: String,
     // annotation
     // label
 }
diff --git a/crates/stackable-versioned-macros/src/codegen/container/struct/mod.rs b/crates/stackable-versioned-macros/src/codegen/container/struct/mod.rs
@@ -302,12 +302,14 @@ impl Struct {
             .map(|s| quote! { , shortname = #s })
             .collect();
 
+        let doc = &spec_gen_ctx.kubernetes_arguments.doc;
+
         quote! {
             // The end-developer needs to derive CustomResource and JsonSchema.
             // This is because we don't know if they want to use a re-exported or renamed import.
             #[kube(
                 // These must be comma separated (except the last) as they always exist:
-                group = #group, version = #version, kind = #kind
+                group = #group, version = #version, kind = #kind, doc = #doc
                 // These fields are optional, and therefore the token stream must prefix each with a comma:
                 #singular #plural #namespaced #crates #status #scale #shortnames
             )]
diff --git a/crates/stackable-versioned-macros/src/lib.rs b/crates/stackable-versioned-macros/src/lib.rs
@@ -329,6 +329,8 @@ mod utils;
 ///         // **Required.** Set the group of the CRD, usually the domain of the
 ///         // company, like `example.com`.
 ///         group = "example.com",
+///         // **Required.** Set the root description of the generated CRD.
+///         doc = "My custom resource.",
 ///         // Override the kind field of the CRD. This defaults to the struct
 ///         // name (without the `Spec` suffix). Overriding this value will also
 ///         // influence the names of other generated items, like the status
@@ -683,7 +685,7 @@ mod utils;
 /// # use serde::{Deserialize, Serialize};
 /// #[versioned(version(name = "v1alpha1"), version(name = "v1beta1"))]
 /// mod versioned {
-///     #[versioned(crd(group = "example.com"))]
+///     #[versioned(crd(group = "example.com", doc = "My custom resource."))]
 ///     #[derive(Clone, Debug, Deserialize, Serialize, CustomResource, JsonSchema)]
 ///     pub struct FooSpec {
 ///         #[versioned(added(since = "v1beta1"))]
@@ -727,7 +729,7 @@ mod utils;
 /// mod versioned {
 ///     #[versioned(skip(merged_crd))] // Skip generation for specific specs
 ///
-/// #   #[versioned(crd(group = "example.com"))]
+/// #   #[versioned(crd(group = "example.com", doc = "My custom resource."))]
 /// #   #[derive(Clone, Debug, CustomResource, Deserialize, Serialize, JsonSchema)]
 ///     pub struct FooSpec {}
 /// }
@@ -754,7 +756,7 @@ mod utils;
 ///     version(name = "v1")
 /// )]
 /// mod versioned {
-///     #[versioned(crd(group = "example.com"))]
+///     #[versioned(crd(group = "example.com", doc = "My custom resource."))]
 ///     #[derive(Clone, Debug, Deserialize, Serialize, CustomResource, JsonSchema)]
 ///     pub struct FooSpec {
 ///         #[versioned(added(since = "v1beta1"))]
@@ -787,7 +789,7 @@ mod utils;
 /// mod versioned {
 ///     #[versioned(skip(try_convert))] // Skip generation for specific specs
 ///
-/// #   #[versioned(crd(group = "example.com"))]
+/// #   #[versioned(crd(group = "example.com", doc = "My custom resource."))]
 /// #   #[derive(Clone, Debug, CustomResource, Deserialize, Serialize, JsonSchema)]
 ///     pub struct FooSpec {}
 /// }
@@ -889,7 +891,7 @@ mod utils;
 ///     options(k8s(experimental_conversion_tracking))
 /// )]
 /// mod versioned {
-///     #[versioned(crd(group = "example.com"))]
+///     #[versioned(crd(group = "example.com", doc = "My custom resource."))]
 ///     #[derive(Clone, Debug, Deserialize, Serialize, CustomResource, JsonSchema)]
 ///     struct FooSpec {
 ///         bar: usize,
diff --git a/crates/stackable-versioned-macros/tests/inputs/fail/spec_suffix.rs b/crates/stackable-versioned-macros/tests/inputs/fail/spec_suffix.rs
@@ -9,7 +9,7 @@ use stackable_versioned_macros::versioned;
 )]
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 mod versioned {
-    #[versioned(crd(group = "stackable.tech"))]
+    #[versioned(crd(group = "stackable.tech", doc = "Test"))]
     pub struct Foo {
         #[versioned(
             added(since = "v1beta1"),
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/basic.rs b/crates/stackable-versioned-macros/tests/inputs/pass/basic.rs
@@ -9,6 +9,7 @@ use stackable_versioned::versioned;
 pub(crate) mod versioned {
     #[versioned(crd(
         group = "stackable.tech",
+        doc = "Test",
         singular = "foo",
         plural = "foos",
         status = FooStatus,
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/conversion_tracking.rs b/crates/stackable-versioned-macros/tests/inputs/pass/conversion_tracking.rs
@@ -14,6 +14,7 @@ pub(crate) mod versioned {
     #[versioned(crd(
         group = "stackable.tech",
         status = FooStatus,
+        doc = "Test",
     ))]
     #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema, CustomResource)]
     pub(crate) struct FooSpec {
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/crate_overrides.rs b/crates/stackable-versioned-macros/tests/inputs/pass/crate_overrides.rs
@@ -11,7 +11,7 @@ use stackable_versioned::versioned;
 )]
 // ---
 pub mod versioned {
-    #[versioned(crd(group = "foo.example.org"))]
+    #[versioned(crd(group = "foo.example.org", doc = "Test"))]
     #[derive(
         Clone,
         Debug,
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/crate_overrides_only_kube.rs b/crates/stackable-versioned-macros/tests/inputs/pass/crate_overrides_only_kube.rs
@@ -11,7 +11,7 @@ use stackable_versioned::versioned;
 )]
 // ---
 pub mod versioned {
-    #[versioned(crd(group = "foo.example.org"))]
+    #[versioned(crd(group = "foo.example.org", doc = "Test"))]
     #[derive(
         Clone,
         Debug,
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/crd_doc.rs b/crates/stackable-versioned-macros/tests/inputs/pass/crd_doc.rs
@@ -0,0 +1,21 @@
+use stackable_versioned::versioned;
+// ---
+#[versioned(version(name = "v1alpha1"))]
+// ---
+pub(crate) mod versioned {
+    #[versioned(crd(
+        group = "stackable.tech",
+        doc = "A FooCluster, deployed and managed by the example operator."
+    ))]
+    #[derive(
+        Clone,
+        Debug,
+        serde::Deserialize,
+        serde::Serialize,
+        schemars::JsonSchema,
+        kube::CustomResource,
+    )]
+    pub(crate) struct FooSpec {}
+}
+// ---
+fn main() {}
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/module.rs b/crates/stackable-versioned-macros/tests/inputs/pass/module.rs
@@ -13,7 +13,7 @@ pub(crate) mod versioned {
         boom: Option<u16>,
     }
 
-    #[versioned(crd(group = "foo.example.org", plural = "foos", namespaced))]
+    #[versioned(crd(group = "foo.example.org", plural = "foos", doc = "Test", namespaced))]
     #[derive(
         Clone,
         Debug,
@@ -32,7 +32,7 @@ pub(crate) mod versioned {
         deprecated_foo: String,
     }
 
-    #[versioned(crd(group = "bar.example.org", plural = "bars"))]
+    #[versioned(crd(group = "bar.example.org", plural = "bars", doc = "Test"))]
     #[derive(
         Clone,
         Debug,
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/module_preserve.rs b/crates/stackable-versioned-macros/tests/inputs/pass/module_preserve.rs
@@ -14,7 +14,7 @@ pub(crate) mod versioned {
         boom: Option<u16>,
     }
 
-    #[versioned(crd(group = "foo.example.org", plural = "foos", namespaced))]
+    #[versioned(crd(group = "foo.example.org", plural = "foos", doc = "Test", namespaced))]
     #[derive(
         Clone,
         Debug,
@@ -33,7 +33,7 @@ pub(crate) mod versioned {
         deprecated_foo: String,
     }
 
-    #[versioned(crd(group = "bar.example.org", plural = "bars"))]
+    #[versioned(crd(group = "bar.example.org", plural = "bars", doc = "Test"))]
     #[derive(
         Clone,
         Debug,
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/renamed_kind.rs b/crates/stackable-versioned-macros/tests/inputs/pass/renamed_kind.rs
@@ -7,7 +7,7 @@ use stackable_versioned::versioned;
 )]
 // ---
 pub mod versioned {
-    #[versioned(crd(group = "stackable.tech", kind = "FooBar", namespaced))]
+    #[versioned(crd(group = "stackable.tech", kind = "FooBar", doc = "Test", namespaced))]
     #[derive(
         Clone,
         Debug,
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/scale.rs b/crates/stackable-versioned-macros/tests/inputs/pass/scale.rs
@@ -5,6 +5,7 @@ use stackable_versioned::versioned;
 pub(crate) mod versioned {
     #[versioned(crd(
         group = "stackable.tech",
+        doc = "Test",
         scale(
             spec_replicas_path = ".spec.replicas",
             status_replicas_path = ".status.replicas",
diff --git a/crates/stackable-versioned-macros/tests/inputs/pass/shortnames.rs b/crates/stackable-versioned-macros/tests/inputs/pass/shortnames.rs
@@ -3,7 +3,7 @@ use stackable_versioned::versioned;
 #[versioned(version(name = "v1alpha1"))]
 // ---
 pub(crate) mod versioned {
-    #[versioned(crd(group = "stackable.tech", shortname = "f", shortname = "fo"))]
+    #[versioned(crd(group = "stackable.tech", shortname = "f", shortname = "fo", doc = "Test"))]
     #[derive(
         Clone,
         Debug,
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@basic.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@basic.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@conversion_tracking.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@conversion_tracking.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@crate_overrides.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@crate_overrides.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@crate_overrides_only_kube.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@crate_overrides_only_kube.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@crd_doc.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@crd_doc.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@module.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@module.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@module_preserve.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@module_preserve.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@renamed_kind.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@renamed_kind.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@scale.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@scale.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@shortnames.rs.snap b/crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@shortnames.rs.snap
diff --git a/crates/stackable-versioned-macros/tests/trybuild.rs b/crates/stackable-versioned-macros/tests/trybuild.rs
diff --git a/crates/stackable-versioned/CHANGELOG.md b/crates/stackable-versioned/CHANGELOG.md
diff --git a/crates/stackable-versioned/tests/person.rs b/crates/stackable-versioned/tests/person.rs
diff --git a/crates/xtask/src/crd/dummy.rs b/crates/xtask/src/crd/dummy.rs
