stackabletech · fhennig · Dec 11, 2023 · Dec 11, 2023 · Dec 11, 2023 · Dec 11, 2023
diff --git a/CHANGELOG.md b/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 ([#510]).
+
+[#510]: https://github.com/stackabletech/trino-operator/pull/510
+
 ## [23.11.0] - 2023-11-24
 
 ### Added

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -23,7 +23,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" }
 product-config = { git = "https://github.com/stackabletech/product-config.git", tag = "0.6.0" }
 strum = { version = "0.25", features = ["derive"] }
 tokio = { version = "1.29", features = ["full"] }

diff --git a/deploy/helm/trino-operator/crds/crds.yaml b/deploy/helm/trino-operator/crds/crds.yaml
diff --git a/rust/crd/src/authentication.rs b/rust/crd/src/authentication.rs
@@ -21,10 +21,11 @@ type Result<T, E = Error> = std::result::Result<T, E>;
 #[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TrinoAuthenticationClassRef {
+    /// An [AuthenticationClass](DOCS_BASE_URL_PLACEHOLDER/concepts/authentication) to use.
     pub authentication_class: String,
 }
 
-/// Retrieve all provided `AuthenticationClass` references.
+/// Retrieve all provided AuthenticationClass references.
 pub async fn resolve_authentication_classes(
     client: &Client,
     authentication_class_refs: &Vec<TrinoAuthenticationClassRef>,

diff --git a/rust/crd/src/catalog/commons.rs b/rust/crd/src/catalog/commons.rs
@@ -4,13 +4,13 @@ use stackable_operator::schemars::{self, JsonSchema};
 #[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MetastoreConnection {
-    /// Name of the discovery-configmap providing information about the Hive metastore
+    /// Name of the [discovery ConfigMap](DOCS_BASE_URL_PLACEHOLDER/concepts/service_discovery) providing information about the Hive metastore.
     pub config_map: String,
 }
 
 #[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct HdfsConnection {
-    /// Name of the discovery-configmap providing information about the HDFS cluster
+    /// Name of the [discovery ConfigMap](DOCS_BASE_URL_PLACEHOLDER/concepts/service_discovery) providing information about the HDFS cluster.
     pub config_map: String,
 }
diff --git a/rust/crd/src/catalog/google_sheet.rs b/rust/crd/src/catalog/google_sheet.rs
@@ -4,10 +4,10 @@ use stackable_operator::schemars::{self, JsonSchema};
 #[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct GoogleSheetConnector {
-    /// Name of the secret containing the Google API JSON key file.
-    /// The key used from the Secret is `credentials`
+    /// The Secret containing the Google API JSON key file.
+    /// The key used from the Secret is `credentials`.
     pub credentials_secret: String,
-    /// Sheet ID of the spreadsheet, that contains the table mapping
+    /// Sheet ID of the spreadsheet, that contains the table mapping.
     pub metadata_sheet_id: String,
     /// Cache the contents of sheets.
     /// This is used to reduce Google Sheets API usage and latency.
@@ -17,8 +17,8 @@ pub struct GoogleSheetConnector {
 #[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct GoogleSheetConnectorCache {
-    /// Maximum number of spreadsheets to cache, defaults to `1000`
+    /// Maximum number of spreadsheets to cache, defaults to 1000.
     pub sheets_data_max_cache_size: Option<String>,
-    /// How long to cache spreadsheet data or metadata, defaults to `5m`
+    /// How long to cache spreadsheet data or metadata, defaults to `5m`.
     pub sheets_data_expire_after_write: Option<String>,
 }
diff --git a/rust/crd/src/catalog/hive.rs b/rust/crd/src/catalog/hive.rs
@@ -12,6 +12,7 @@ pub struct HiveConnector {
     pub metastore: MetastoreConnection,
     /// Connection to an S3 store.
     /// Please make sure that the underlying Hive metastore also has access to the S3 store.
+    /// Learn more about S3 configuration in the [S3 concept docs](DOCS_BASE_URL_PLACEHOLDER/concepts/s3).
     pub s3: Option<S3ConnectionDef>,
     /// Connection to an HDFS cluster.
     /// Please make sure that the underlying Hive metastore also has access to the HDFS.

diff --git a/rust/crd/src/catalog/iceberg.rs b/rust/crd/src/catalog/iceberg.rs
@@ -12,6 +12,7 @@ pub struct IcebergConnector {
     pub metastore: MetastoreConnection,
     /// Connection to an S3 store.
     /// Please make sure that the underlying Hive metastore also has access to the S3 store.
+    /// Learn more about S3 configuration in the [S3 concept docs](DOCS_BASE_URL_PLACEHOLDER/concepts/s3).
     pub s3: Option<S3ConnectionDef>,
     /// Connection to an HDFS cluster.
     /// Please make sure that the underlying Hive metastore also has access to the HDFS.

diff --git a/rust/crd/src/catalog/mod.rs b/rust/crd/src/catalog/mod.rs
@@ -22,6 +22,10 @@ use iceberg::IcebergConnector;
 use tpcds::TpcdsConnector;
 use tpch::TpchConnector;
 
+/// The TrinoCatalog resource can be used to define catalogs in Kubernetes objects.
+/// Read more about it in the [Trino operator concept docs](DOCS_BASE_URL_PLACEHOLDER/trino/concepts)
+/// and the [Trino operator usage guide](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/catalogs/).
+/// The documentation also contains a list of all the supported backends.
 #[derive(Clone, CustomResource, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
 #[kube(
     group = "trino.stackable.tech",
@@ -37,20 +41,36 @@ use tpch::TpchConnector;
 )]
 #[serde(rename_all = "camelCase")]
 pub struct TrinoCatalogSpec {
+    /// The `connector` defines which connector is used.
     pub connector: TrinoCatalogConnector,
     #[serde(default)]
+    /// The `configOverrides` allow overriding arbitrary Trino settings.
+    /// For example, for Hive you could add `hive.metastore.username: trino`.
     pub config_overrides: HashMap<String, String>,
 }
 
 #[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub enum TrinoCatalogConnector {
+    /// A [Black Hole](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/catalogs/black-hole) connector.
     BlackHole(BlackHoleConnector),
+
+    /// A [Google sheets](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/catalogs/google-sheets) connector.
     GoogleSheet(GoogleSheetConnector),
+
+    /// A [generic](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/catalogs/generic) connector.
     Generic(GenericConnector),
+
+    /// An [Apache Hive](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/catalogs/hive) connector.
     Hive(HiveConnector),
+
+    /// An [Apache Iceberg](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/catalogs/iceberg) connector.
     Iceberg(IcebergConnector),
+
+    /// A [TPC-DS](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/catalogs/tpcds) connector.
     Tpcds(TpcdsConnector),
+
+    /// A [TPC-H](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/catalogs/tpch) connector.
     Tpch(TpchConnector),
 }
 

diff --git a/rust/crd/src/lib.rs b/rust/crd/src/lib.rs
@@ -159,6 +159,9 @@ pub enum Error {
     FragmentValidationFailure { source: ValidationError },
 }
 
+/// A Trino cluster stacklet. This resource is managed by the Stackable operator for Trino.
+/// Find more information on how to use it and the resources that the operator generates in the
+/// [operator documentation](DOCS_BASE_URL_PLACEHOLDER/trino/).
 #[derive(Clone, CustomResource, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
 #[kube(
     group = "trino.stackable.tech",
@@ -176,17 +179,22 @@ pub enum Error {
 #[kube(status = "TrinoClusterStatus")]
 #[serde(rename_all = "camelCase")]
 pub struct TrinoClusterSpec {
-    /// Trino product image to use.
+    // no doc - it's in the struct.
     pub image: ProductImage,
-    /// Trino cluster configuration options.
+
+    /// 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: TrinoClusterConfig,
-    /// Cluster operations like pause reconciliation or cluster stop.
+
+    // no doc - it's in the struct.
     #[serde(default)]
     pub cluster_operation: ClusterOperation,
-    /// Settings for the Coordinator Role/Process.
+
+    // no doc - it's in the struct.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub coordinators: Option<Role<TrinoConfigFragment>>,
-    /// Settings for the Worker Role/Process.
+
+    // no doc - it's in the struct.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub workers: Option<Role<TrinoConfigFragment>>,
 }
@@ -195,21 +203,30 @@ pub struct TrinoClusterSpec {
 #[serde(rename_all = "camelCase")]
 pub struct TrinoClusterConfig {
     /// Authentication options for Trino.
+    /// Learn more in the [Trino authentication usage guide](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/security#authentication).
     #[serde(default)]
     pub authentication: Vec<TrinoAuthenticationClassRef>,
+
     /// Authorization options for Trino.
+    /// Learn more in the [Trino authorization usage guide](DOCS_BASE_URL_PLACEHOLDER/trino/usage-guide/security#authorization).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub authorization: Option<TrinoAuthorization>,
+
     /// [LabelSelector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors) selecting the Catalogs
     /// to include in the Trino instance.
     pub catalog_label_selector: LabelSelector,
+
     /// TLS configuration options for server and internal communication.
     #[serde(default)]
     pub tls: TrinoTls,
-    /// 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>,
+
     /// This field controls which type of Service the Operator creates for this TrinoCluster:
     ///
     /// * cluster-internal: Use a ClusterIP service
@@ -219,7 +236,7 @@ pub struct TrinoClusterConfig {
     /// * external-stable: Use a LoadBalancer service
     ///
     /// This is a temporary solution with the goal to keep yaml manifests forward compatible.
-    /// In the future, this setting will control which ListenerClass <https://docs.stackable.tech/home/stable/listener-operator/listenerclass.html>
+    /// In the future, this setting will control which [ListenerClass](DOCS_BASE_URL_PLACEHOLDER/listener-operator/listenerclass.html)
     /// will be used to expose the service, and ListenerClass names will stay the same, allowing for a non-breaking change.
     #[serde(default)]
     pub listener_class: CurrentlySupportedListenerClasses,
@@ -251,7 +268,7 @@ impl CurrentlySupportedListenerClasses {
 #[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TrinoAuthorization {
-    /// The discovery ConfigMap name of the OPA cluster (usually the same as the OPA cluster name).
+    // no doc - it's in the struct.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub opa: Option<OpaConfig>,
 }

diff --git a/rust/operator-binary/src/main.rs b/rust/operator-binary/src/main.rs
@@ -45,8 +45,8 @@ async fn main() -> anyhow::Result<()> {
     let opts = Opts::parse();
     match opts.cmd {
         Command::Crd => {
-            TrinoCluster::print_yaml_schema()?;
-            TrinoCatalog::print_yaml_schema()?;
+            TrinoCluster::print_yaml_schema(built_info::CARGO_PKG_VERSION)?;
+            TrinoCatalog::print_yaml_schema(built_info::CARGO_PKG_VERSION)?;
         }
         Command::Run(ProductOperatorRun {
             product_config,