more docs

stackabletech · Dec 11, 2023 · 5397952 · 5397952
1 parent b3b79ce
commit 5397952
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 15 deletions.
diff --git a/deploy/helm/trino-operator/crds/crds.yaml b/deploy/helm/trino-operator/crds/crds.yaml
@@ -26,25 +26,26 @@ spec:
               description: 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](https://docs.stackable.tech/home/nightly/trino/).
               properties:
                 clusterConfig:
-                  description: Trino cluster configuration options.
+                  description: 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.
                   properties:
                     authentication:
                       default: []
-                      description: Authentication options for Trino.
+                      description: Authentication options for Trino. Learn more in the [Trino authentication usage guide](https://docs.stackable.tech/home/nightly/trino/usage-guide/security#authentication).
                       items:
                         properties:
                           authenticationClass:
+                            description: An [AuthenticationClass](https://docs.stackable.tech/home/nightly/concepts/authentication) to use.
                             type: string
                         required:
                           - authenticationClass
                         type: object
                       type: array
                     authorization:
-                      description: Authorization options for Trino.
+                      description: Authorization options for Trino. Learn more in the [Trino authorization usage guide](https://docs.stackable.tech/home/nightly/trino/usage-guide/security#authorization).
                       nullable: true
                       properties:
                         opa:
-                          description: The discovery ConfigMap name of the OPA cluster (usually the same as the OPA cluster name).
+                          description: Configure the OPA stacklet [discovery ConfigMap](https://docs.stackable.tech/home/nightly/concepts/service_discovery) and the name of the Rego package containing your authorization rules. Consult the [OPA authorization documentation](https://docs.stackable.tech/home/nightly/concepts/opa) to learn how to deploy Rego authorization rules with OPA.
                           nullable: true
                           properties:
                             configMapName:
@@ -133,7 +134,7 @@ spec:
                   default:
                     stopped: false
                     reconciliationPaused: false
-                  description: Cluster operations like pause reconciliation or cluster stop.
+                  description: '[Cluster operations](https://docs.stackable.tech/home/nightly/concepts/operations/cluster_operations) properties, allow stopping the product instance as well as pausing reconciliation.'
                   properties:
                     reconciliationPaused:
                       default: false
@@ -145,7 +146,7 @@ spec:
                       type: boolean
                   type: object
                 coordinators:
-                  description: Settings for the Coordinator Role/Process.
+                  description: This struct represents a role - e.g. HDFS datanodes or Trino workers. It has a [`HashMap`] 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 using the [`Merge`] trait. There is also a second form of config, which can only be configured at role level, the `roleConfig`.
                   nullable: true
                   properties:
                     cliOverrides:
@@ -7171,7 +7172,10 @@ spec:
                         - productVersion
                     - required:
                         - productVersion
-                  description: Trino product image to use.
+                  description: |-
+                    Specify which image to use, the easiest way is to only configure the `productVersion`. You can also configure a custom image registry to pull from, as well as completely custom images.
+
+                    Consult the [Product image selection documentation](https://docs.stackable.tech/home/nightly/concepts/product_image_selection) for details.
                   properties:
                     custom:
                       description: Overwrite the docker image. Specify the full docker image name, e.g. `docker.stackable.tech/stackable/superset:1.4.1-stackable2.1.0`
@@ -7208,7 +7212,7 @@ spec:
                       type: string
                   type: object
                 workers:
-                  description: Settings for the Worker Role/Process.
+                  description: This struct represents a role - e.g. HDFS datanodes or Trino workers. It has a [`HashMap`] 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 using the [`Merge`] trait. There is also a second form of config, which can only be configured at role level, the `roleConfig`.
                   nullable: true
                   properties:
                     cliOverrides:

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/lib.rs b/rust/crd/src/lib.rs
@@ -179,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>>,
 }
@@ -198,14 +203,19 @@ 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,
@@ -258,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>,
 }