feat(operator)!: Introduce v1alpha2 Role and RoleGroup

crates/stackable-operator/crds/DummyCluster.yaml

@@ -418,13 +418,16 @@ spec:
                 type: string
               nodes:
                 description: |-
-                  This struct represents a role - e.g. HDFS datanodes or Trino workers. It has a key-value-map containing
-                  all the roleGroups that are part of this role. Additionally, there is a `config`, which is configurable
-                  at the role *and* roleGroup level. Everything at roleGroup level is merged on top of what is configured
-                  on role level. There is also a second form of config, which can only be configured
-                  at role level, the `roleConfig`.
-                  You can learn more about this in the
-                  [Roles and role group concept documentation](https://docs.stackable.tech/home/nightly/concepts/roles-and-role-groups).
+                  This struct represents a role - e.g. HDFS datanodes or Trino workers.
+
+                  It has a key-value-map containing all the roleGroups that are part of this role. Additionally, there is a
+                  `config`, which is configurable at the role **and** roleGroup level. Everything at roleGroup level is merged on
+                  top of what is configured on role level.
+
+                  There is also a second form of config, which can only be configured at role level, the `roleConfig`. You can
+                  learn more about this in the [Roles and role group concept documentation][1].
+
+                  [1]: https://docs.stackable.tech/home/nightly/concepts/roles-and-role-groups
                 nullable: true
                 properties:
                   cliOverrides:
@@ -1744,11 +1747,29 @@ spec:
                           type: object
                           x-kubernetes-preserve-unknown-fields: true
                         replicas:
-                          format: uint16
-                          maximum: 65535.0
-                          minimum: 0.0
-                          nullable: true
-                          type: integer
+                          oneOf:
+                          - required:
+                            - fixed
+                          - required:
+                            - custom
+                          properties:
+                            custom:
+                              description: Use a auto-scaled number of replicas managed by external/custom mechanisms, e.g. HPA.
+                              type: object
+                            fixed:
+                              description: Use a fixed number of replicas.
+                              properties:
+                                count:
+                                  format: uint16
+                                  maximum: 65535.0
+                                  minimum: 0.0
+                                  type: integer
+                              required:
+                              - count
+                              type: object
+                          type: object
+                      required:
+                      - replicas
                       type: object
                     description: |-
                       The set of role groups for this role, keyed by their name.

crates/stackable-operator/src/cluster_resources.rs

@@ -338,7 +338,6 @@ impl ClusterResource for Deployment {
 ///     client::Client,
 ///     cluster_resources::{self, ClusterResourceApplyStrategy, ClusterResources},
 ///     deep_merger::ObjectOverrides,
-///     role_utils::Role,
 /// };
 ///
 /// const APP_NAME: &str = "app";

crates/stackable-operator/src/commons/resources.rs

@@ -21,13 +21,15 @@
 //! # Example
 //!
 //! ```
+//! # #[cfg(feature = "crds")]
+//! # mod wrapper {
 //! use kube::CustomResource;
 //! use schemars::JsonSchema;
 //! use serde::{Deserialize, Serialize};
 //! use stackable_operator::{
 //!     commons::resources::{JvmHeapLimits, PvcConfig, Resources},
 //!     config::fragment::Fragment,
-//!     role_utils::Role,
+//!     crd::role::v1alpha2::Role,
 //! };
 //!
 //! #[derive(Clone, Debug, Default, Deserialize, JsonSchema, PartialEq, Serialize)]
@@ -71,6 +73,7 @@
 //!     metadata_storage: PvcConfig,
 //!     shared_storage: PvcConfig,
 //! }
+//! # }
 //! ```
 
 use std::{collections::BTreeMap, fmt::Debug};

crates/stackable-operator/src/config/fragment.rs

@@ -16,8 +16,8 @@ pub use stackable_operator_derive::Fragment;
 use super::merge::Atomic;
 #[cfg(doc)]
 use super::merge::Merge;
-#[cfg(doc)]
-use crate::role_utils::{Role, RoleGroup};
+#[cfg(all(doc, feature = "crds"))]
+use crate::crd::role::v1alpha2::{Role, RoleGroup};
 
 /// Contains context used for generating validation errors
 ///
@@ -93,13 +93,15 @@ enum ValidationProblem {
 /// A type that can be constructed by validating a "fragment" type.
 ///
 /// This is intended to be used together with [`Merge`], such that fragments are deserialized from multiple sources
-/// (for example: the [`RoleGroup`] and [`Role`] levels of a ProductCluster object), and then validated into the type implementing
+/// (for example: the [role group][role] and [role] levels of a ProductCluster object), and then validated into the type implementing
 /// `FromFragment`.
 ///
-/// It is recommended to use [`RoleGroup::validate_config`] to both merge and validate product [`RoleGroup`] configurations. For other use cases,
+/// It is recommended to use `RoleGroup::validate_config` to both merge and validate product [role group][role] configurations. For other use cases,
 /// [`validate`] can be used on the already-merged configuration.
 ///
 /// This will typically be derived using the [`Fragment`] macro, rather than implemented manually.
+///
+/// [role]: crate::crd::role
 pub trait FromFragment: Sized {
     /// The fragment type of `Self`.
     ///
@@ -206,7 +208,9 @@ impl FromFragment for PodTemplateSpec {
 
 /// Validates a [`Fragment`](`FromFragment::Fragment`), and turns it into its corresponding [`FromFragment`] type if successful.
 ///
-/// When validating a [`RoleGroup`]'s configuration, consider using [`RoleGroup::validate_config`] instead.
+/// When validating a [`RoleGroup`][role]'s configuration, consider using `RoleGroup::validate_config` instead.
+///
+/// [role]: crate::crd::role
 pub fn validate<T: FromFragment>(fragment: T::Fragment) -> Result<T, ValidationError> {
     T::from_fragment(
         fragment,

crates/stackable-operator/src/config/mod.rs

@@ -3,8 +3,8 @@
 //! # But oh god why is this monstrosity a thing?
 //!
 //! Products are complicated. They need to be supplied many kinds of configuration.
-//! Some of it applies to the whole installation (Stacklet). Some of it applies only to one [role](`Role`).
-//! Some of it applies only to a subset of the instances of that role (we call this a [`RoleGroup`]).
+//! Some of it applies to the whole installation (Stacklet). Some of it applies only to one [role].
+//! Some of it applies only to a subset of the instances of that role (we call this a [role group][role]).
 //!
 //! We (usually) don't know at what level it makes sense to apply a given piece of configuration, but we also
 //! don't want to force users to repeat themselves constantly! Instead, we model the configuration as a tree:
@@ -145,6 +145,7 @@
 //! # Fine, how do I actually use it, then?
 //!
 //! For declarations (in CRDs):
+//!
 //! - Apply `#[derive(Fragment)] #[fragment_attrs(derive(Merge))]` for your product configuration (and any of its nested types).
 //!   - DON'T: `#[derive(Fragment, Merge)]`
 //! - Pretty much always derive deserialization and defaulting on the `Fragment`, not the validated type:
@@ -155,12 +156,14 @@
 //! - Define the "validated form" of your configuration: only make fields [`Option`]al if [`None`] is actually a legal value.
 //!
 //! For runtime code:
-//! - Validate and merge with [`RoleGroup::validate_config`] for CRDs, otherwise [`merge`] manually and then validate with [`validate`].
+//!
+//! - Validate and merge with `RoleGroup::validate_config` for CRDs, otherwise [`merge`] manually and then validate with [`validate`].
 //! - Validate as soon as possible, user code should never read the contents of `Fragment`s.
 //! - Defaults are just another layer to be [`merge`]d.
 //!
 //! [parsing]: https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/
 //! [`merge`]: Merge::merge
+//! [role]: crate::crd::role
 
 pub mod fragment;
 pub mod merge;
@@ -169,6 +172,3 @@ pub mod merge;
 use fragment::{Fragment, FromFragment, validate};
 #[cfg(doc)]
 use merge::{Atomic, Merge};
-
-#[cfg(doc)]
-use crate::role_utils::{Role, RoleGroup};

crates/stackable-operator/src/crd/mod.rs

@@ -4,12 +4,22 @@ use educe::Educe;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
-pub mod authentication;
-pub mod git_sync;
-pub mod listener;
-pub mod openlineage;
-pub mod s3;
-pub mod scaler;
+use crate::cfg_block;
+
+cfg_block! {
+    "crds";
+
+    pub mod authentication;
+    pub mod git_sync;
+    pub mod listener;
+    pub mod openlineage;
+    pub mod s3;
+    pub mod scaler;
+}
+
+// Not gated as a whole as there are other items which should not be gated, but are still related to
+// role and role group.
+pub mod role;
 
 /// A reference to a product cluster (for example, a `ZookeeperCluster`)
 ///