doc: Add code comments

Author: siegfriedweber

rust/operator-binary/src/controller/apply.rs

@@ -1,3 +1,5 @@
+//! The apply step in the OpenSearchCluster controller
+
 use std::marker::PhantomData;
 
 use snafu::{ResultExt, Snafu};

rust/operator-binary/src/controller/build.rs

@@ -1,3 +1,5 @@
+//! The build step in the OpenSearchCluster controller
+
 use std::marker::PhantomData;
 
 use role_builder::RoleBuilder;

rust/operator-binary/src/controller/build/node_config.rs

@@ -1,3 +1,5 @@
+//! Configuration of an OpenSearch node
+
 use std::str::FromStr;
 
 use serde_json::{Value, json};
@@ -14,33 +16,49 @@ use crate::{
     },
 };
 
+/// The main configuration file of OpenSearch
 pub const CONFIGURATION_FILE_OPENSEARCH_YML: &str = "opensearch.yml";
 
-/// type: string
+/// The cluster name.
+/// Type: string
 pub const CONFIG_OPTION_CLUSTER_NAME: &str = "cluster.name";
 
-/// type: (comma-separated) list of strings
+/// The list of hosts that perform discovery when a node is started.
+/// Type: (comma-separated) list of strings
 pub const CONFIG_OPTION_DISCOVERY_SEED_HOSTS: &str = "discovery.seed_hosts";
 
-/// type: string
+/// By default, OpenSearch forms a multi-node cluster. Set `discovery.type` to `single-node` to
+/// form a single-node cluster.
+/// Type: string
 pub const CONFIG_OPTION_DISCOVERY_TYPE: &str = "discovery.type";
 
-/// type: (comma-separated) list of strings
+/// A list of cluster-manager-eligible nodes used to bootstrap the cluster.
+/// Type: (comma-separated) list of strings
 pub const CONFIG_OPTION_INITIAL_CLUSTER_MANAGER_NODES: &str =
     "cluster.initial_cluster_manager_nodes";
 
-/// type: string
+/// Binds an OpenSearch node to an address.
+/// Type: string
 pub const CONFIG_OPTION_NETWORK_HOST: &str = "network.host";
 
-/// type: string
+/// A descriptive name for the node.
+/// Type: string
 pub const CONFIG_OPTION_NODE_NAME: &str = "node.name";
 
-/// type: (comma-separated) list of strings
+/// Defines one or more roles for an OpenSearch node.
+/// Type: (comma-separated) list of strings
 pub const CONFIG_OPTION_NODE_ROLES: &str = "node.roles";
 
-/// type: (comma-separated) list of strings
+/// Specifies a list of distinguished names (DNs) that denote the other nodes in the cluster.
+/// Type: (comma-separated) list of strings
 pub const CONFIG_OPTION_PLUGINS_SECURITY_NODES_DN: &str = "plugins.security.nodes_dn";
 
+/// Whether to enable TLS on the REST layer. If enabled, only HTTPS is allowed.
+/// Type: boolean
+pub const CONFIG_OPTION_PLUGINS_SECURITY_SSL_HTTP_ENABLED: &str =
+    "plugins.security.ssl.http.enabled";
+
+/// Configuration of an OpenSearch node based on the cluster and role-group configuration
 pub struct NodeConfig {
     cluster: ValidatedCluster,
     role_group_config: OpenSearchRoleGroupConfig,
@@ -62,12 +80,15 @@ impl NodeConfig {
         }
     }
 
-    /// static for the cluster
+    /// Creates the main OpenSearch configuration file in YAML format
     pub fn static_opensearch_config_file(&self) -> String {
         Self::to_yaml(self.static_opensearch_config())
     }
 
-    /// static for the cluster
+    /// Creates the main OpenSearch configuration file as JSON map
+    ///
+    /// The file should only contain cluster-wide configuration options. Node-specific options
+    /// should be defined as environment variables.
     pub fn static_opensearch_config(&self) -> serde_json::Map<String, Value> {
         let mut config = serde_json::Map::new();
 
@@ -107,13 +128,15 @@ impl NodeConfig {
         config
     }
 
+    /// Returns `true` if TLS is enabled on the HTTP port
     pub fn tls_on_http_port_enabled(&self) -> bool {
         self.static_opensearch_config()
-            .get("plugins.security.ssl.http.enabled")
+            .get(CONFIG_OPTION_PLUGINS_SECURITY_SSL_HTTP_ENABLED)
             .and_then(Self::value_as_bool)
             == Some(true)
     }
 
+    /// Converts the given JSON value to `bool` if possible
     pub fn value_as_bool(value: &Value) -> Option<bool> {
         value.as_bool().or(
             // OpenSearch parses the strings "true" and "false" as boolean, see
@@ -124,7 +147,10 @@ impl NodeConfig {
         )
     }
 
-    /// different for every node
+    /// Creates environment variables for the OpenSearch configurations
+    ///
+    /// The environment variables should only contain node-specific configuration options.
+    /// Cluster-wide options should be added to the configuration file.
     pub fn environment_variables(&self) -> EnvVarSet {
         EnvVarSet::new()
             // Set the OpenSearch node name to the Pod name.

rust/operator-binary/src/controller/build/role_builder.rs

@@ -1,3 +1,5 @@
+//! Builder for role resources
+
 use stackable_operator::{
     builder::meta::ObjectMetaBuilder,
     k8s_openapi::{
@@ -31,6 +33,7 @@ use crate::{
 
 const PDB_DEFAULT_MAX_UNAVAILABLE: u16 = 1;
 
+/// Builder for role resources
 pub struct RoleBuilder<'a> {
     cluster: ValidatedCluster,
     context_names: &'a ContextNames,
@@ -49,6 +52,7 @@ impl<'a> RoleBuilder<'a> {
         }
     }
 
+    /// Creates role-group builders which are initialized with the role-level context
     pub fn role_group_builders(&self) -> Vec<RoleGroupBuilder<'_>> {
         self.cluster
             .role_group_configs
@@ -66,6 +70,7 @@ impl<'a> RoleBuilder<'a> {
             .collect()
     }
 
+    /// Builds a ServiceAccount used by all role-groups
     pub fn build_service_account(&self) -> ServiceAccount {
         let metadata = self.common_metadata(self.resource_names.service_account_name());
 
@@ -75,6 +80,7 @@ impl<'a> RoleBuilder<'a> {
         }
     }
 
+    /// Builds a RoleBinding used by all role-groups
     pub fn build_role_binding(&self) -> RoleBinding {
         let metadata = self.common_metadata(self.resource_names.role_binding_name());
 
@@ -94,6 +100,14 @@ impl<'a> RoleBuilder<'a> {
         }
     }
 
+    /// Builds a Service that references all nodes with the cluster_manager node role
+    ///
+    /// Initially, this service was meant to be used by
+    /// `NodeConfig::initial_cluster_manager_nodes`, but the function uses now another approach.
+    /// Afterwards, it was meant to be used as an entry point to OpenSearch, but it could also make
+    /// sense to use coordinating only nodes as entry points and not cluster manager nodes.
+    /// Therefore, this service will bei either adapted or removed. There is already an according
+    /// task entry in <https://github.com/stackabletech/opensearch-operator/issues/1>.
     pub fn build_cluster_manager_service(&self) -> Service {
         let ports = vec![
             ServicePort {
@@ -130,6 +144,7 @@ impl<'a> RoleBuilder<'a> {
         }
     }
 
+    /// Builds a PodDisruptionBudget used by all role-groups
     pub fn build_pdb(&self) -> Option<PodDisruptionBudget> {
         let pdb_config = &self.cluster.role_config.pod_disruption_budget;
 
@@ -153,6 +168,7 @@ impl<'a> RoleBuilder<'a> {
         }
     }
 
+    /// Common metadata for role resources
     fn common_metadata(&self, resource_name: impl Into<String>) -> ObjectMeta {
         ObjectMetaBuilder::new()
             .name(resource_name)
@@ -166,7 +182,7 @@ impl<'a> RoleBuilder<'a> {
             .build()
     }
 
-    /// Labels on role resources
+    /// Common labels for role resources
     fn labels(&self) -> Labels {
         // Well-known Kubernetes labels
         let mut labels = Labels::role_selector(