feat: better CRD docs

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Various documentation of the CRD ([#645]).
+
+[#645]: https://github.com/stackabletech/kafka-operator/pull/645
+
 ## [23.11.0] - 2023-11-24
 
 ### Added

Cargo.toml

@@ -20,7 +20,7 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 serde_yaml = "0.9"
 snafu = "0.7"
-stackable-operator = { git = "https://github.com/stackabletech/operator-rs.git", tag = "0.56.1" }
+stackable-operator = { git = "https://github.com/stackabletech/operator-rs.git", tag = "0.57.0" }
 strum = { version = "0.25", features = ["derive"] }
 tokio = { version = "1.29", features = ["full"] }
 tracing = "0.1"

rust/crd/src/authorization.rs

@@ -7,5 +7,6 @@ use stackable_operator::{
 #[derive(Clone, Deserialize, Debug, Default, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct KafkaAuthorization {
+    // no doc - docs in the OpaConfig struct.
     pub opa: Option<OpaConfig>,
 }

rust/crd/src/lib.rs

@@ -94,6 +94,9 @@ pub enum Error {
     FragmentValidationFailure { source: ValidationError },
 }
 
+/// A Kafka cluster stacklet. This resource is managed by the Stackable operator for Apache Kafka.
+/// Find more information on how to use it and the resources that the operator generates in the
+/// [operator documentation](DOCS_BASE_URL_PLACEHOLDER/kafka/).
 #[derive(Clone, CustomResource, Debug, Deserialize, JsonSchema, Serialize)]
 #[kube(
     group = "kafka.stackable.tech",
@@ -111,10 +114,17 @@ pub enum Error {
 )]
 #[serde(rename_all = "camelCase")]
 pub struct KafkaClusterSpec {
+    // no doc - docs in ProductImage struct.
     pub image: ProductImage,
+
+    // no doc - docs in Role struct.
     pub brokers: Option<Role<KafkaConfigFragment>>,
+
+    /// Kafka settings that affect all roles and role groups.
+    /// The settings in the `clusterConfig` are cluster wide settings that do not need to be configurable at role or role group level.
     pub cluster_config: KafkaClusterConfig,
-    /// Cluster operations like pause reconciliation or cluster stop.
+
+    // no doc - docs in ClusterOperation struct.
     #[serde(default)]
     pub cluster_operation: ClusterOperation,
 }
@@ -125,20 +135,29 @@ pub struct KafkaClusterConfig {
     /// Authentication class settings for Kafka like mTLS authentication.
     #[serde(default)]
     pub authentication: Vec<KafkaAuthentication>,
+
     /// Authorization settings for Kafka like OPA.
     #[serde(default)]
     pub authorization: KafkaAuthorization,
+
     /// TLS encryption settings for Kafka (server, internal).
     #[serde(
         default = "tls::default_kafka_tls",
         skip_serializing_if = "Option::is_none"
     )]
     pub tls: Option<KafkaTls>,
-    /// Name of the Vector aggregator discovery ConfigMap.
+
+    /// Name of the Vector aggregator [discovery ConfigMap](DOCS_BASE_URL_PLACEHOLDER/concepts/service_discovery).
     /// It must contain the key `ADDRESS` with the address of the Vector aggregator.
+    /// Follow the [logging tutorial](DOCS_BASE_URL_PLACEHOLDER/tutorials/logging-vector-aggregator)
+    /// to learn how to configure log aggregation with Vector.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub vector_aggregator_config_map_name: Option<String>,
-    /// ZooKeeper discovery config map name.
+
+    /// Kafka requires a ZooKeeper cluster connection to run.
+    /// Provide the name of the ZooKeeper [discovery ConfigMap](DOCS_BASE_URL_PLACEHOLDER/concepts/service_discovery)
+    /// here. When using the [Stackable operator for Apache ZooKeeper](DOCS_BASE_URL_PLACEHOLDER/zookeeper/)
+    /// to deploy a ZooKeeper cluster, this will simply be the name of your ZookeeperCluster resource.
     pub zookeeper_config_map_name: String,
 }
 

rust/crd/src/tls.rs

@@ -6,15 +6,15 @@ const TLS_DEFAULT_SECRET_CLASS: &str = "tls";
 #[derive(Clone, Deserialize, Debug, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct KafkaTls {
-    /// The <https://docs.stackable.tech/secret-operator/stable/secretclass.html> to use for
+    /// The [SecretClass](DOCS_BASE_URL_PLACEHOLDER/secret-operator/secretclass.html) to use for
     /// internal broker communication. Use mutual verification between brokers (mandatory).
     /// This setting controls:
     /// - Which cert the brokers should use to authenticate themselves against other brokers
     /// - Which ca.crt to use when validating the other brokers
     /// Defaults to `tls`
     #[serde(default = "internal_tls_default")]
     pub internal_secret_class: String,
-    /// The <https://docs.stackable.tech/secret-operator/stable/secretclass.html> to use for
+    /// The [SecretClass](DOCS_BASE_URL_PLACEHOLDER/secret-operator/secretclass.html) to use for
     /// client connections. This setting controls:
     /// - If TLS encryption is used at all
     /// - Which cert the servers should use to authenticate themselves against the client
@@ -26,7 +26,8 @@ pub struct KafkaTls {
     pub server_secret_class: Option<String>,
 }
 
-/// Default TLS settings. Internal and server communication default to "tls" secret class.
+/// Default TLS settings.
+/// Internal and server communication default to `tls` secret class.
 pub fn default_kafka_tls() -> Option<KafkaTls> {
     Some(KafkaTls {
         internal_secret_class: internal_tls_default(),

rust/operator-binary/src/main.rs

@@ -56,7 +56,7 @@ struct KafkaRun {
 async fn main() -> Result<(), error::Error> {
     let opts = Opts::parse();
     match opts.cmd {
-        Command::Crd => KafkaCluster::print_yaml_schema()?,
+        Command::Crd => KafkaCluster::print_yaml_schema(built_info::CARGO_PKG_VERSION)?,
         Command::Run(KafkaRun {
             kafka_broker_clusterrole,
             common: