Merge branch 'main' into feat/sso-auth-classes

Author: sbernauer

CHANGELOG.md

@@ -21,6 +21,14 @@ All notable changes to this project will be documented in this file.
 
 [#680]: https://github.com/stackabletech/operator-rs/pull/680
 
+## [0.56.2] - 2023-11-23
+
+### Added
+
+- More documentation for CRD structs ([#687]).
+
+[#687]: https://github.com/stackabletech/operator-rs/pull/687
+
 ## [0.56.1] - 2023-11-23
 
 ### Changed

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace.package]
-version = "0.56.1"
+version = "0.56.2"
 authors = ["Stackable GmbH <[email protected]>"]
 license = "Apache-2.0"
 edition = "2021"

src/commons/affinity.rs

@@ -18,6 +18,8 @@ use crate::{
 
 pub const TOPOLOGY_KEY_HOSTNAME: &str = "kubernetes.io/hostname";
 
+/// These configuration settings control
+/// [Pod placement](https://docs.stackable.tech/home/nightly/concepts/operations/pod_placement).
 #[derive(Clone, Debug, Default, Deserialize, Fragment, JsonSchema, PartialEq, Serialize)]
 #[fragment(path_overrides(fragment = "crate::config::fragment"))]
 #[fragment_attrs(

src/commons/cluster_operation.rs

@@ -1,6 +1,8 @@
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+/// [Cluster operations](https://docs.stackable.tech/home/nightly/concepts/operations/cluster_operations)
+/// properties, allow stopping the product instance as well as pausing reconciliation.
 #[derive(Clone, Debug, Default, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ClusterOperation {

src/commons/opa.rs

@@ -73,10 +73,17 @@ impl OpaApiVersion {
     }
 }
 
+/// 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.
 #[derive(Clone, Debug, Default, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct OpaConfig {
+    /// The [discovery ConfigMap](https://docs.stackable.tech/home/nightly/concepts/service_discovery)
+    /// for the OPA stacklet that should be used for authorization requests.
     pub config_map_name: String,
+    /// The name of the Rego package containing the Rego rules for the product.
     pub package: Option<String>,
 }
 

src/commons/pdb.rs

@@ -2,8 +2,12 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 /// This struct is used to configure:
-/// 1.) If PodDisruptionBudgets are created by the operator
-/// 2.) The allowed number of Pods to be unavailable (`maxUnavailable`)
+///
+/// 1. If PodDisruptionBudgets are created by the operator
+/// 2. The allowed number of Pods to be unavailable (`maxUnavailable`)
+///
+/// Learn more in the
+/// [allowed Pod disruptions documentation](https://docs.stackable.tech/home/nightly/concepts/operations/pod_disruptions).
 #[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PdbConfig {

src/commons/product_image_selection.rs

@@ -9,17 +9,23 @@ use crate::labels::get_recommended_labels;
 
 pub const STACKABLE_DOCKER_REPO: &str = "docker.stackable.tech/stackable";
 
+/// 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.
 #[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ProductImage {
     #[serde(flatten)]
     image_selection: ProductImageSelection,
 
     #[serde(default)]
-    /// [Pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy) used when pulling the Images
+    /// [Pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy) used when pulling the image.
     pull_policy: PullPolicy,
 
-    /// [Image pull secrets](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) to pull images from a private registry
+    /// [Image pull secrets](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) to pull images from a private registry.
     pull_secrets: Option<Vec<LocalObjectReference>>,
 }
 

src/commons/resources.rs

@@ -90,8 +90,8 @@ use strum::Display;
 pub const LIMIT_REQUEST_RATIO_CPU: f32 = 5.0;
 pub const LIMIT_REQUEST_RATIO_MEMORY: f32 = 1.0;
 
-// This struct allows specifying memory and cpu limits as well as generically adding storage
-// settings.
+/// Resource usage is configured here, this includes CPU usage, memory usage and disk storage
+/// usage, if this role needs any.
 #[derive(Clone, Debug, Default, Fragment, PartialEq, JsonSchema)]
 #[fragment(
     bound = "T: FromFragment, K: FromFragment",
@@ -158,10 +158,14 @@ pub struct Resources<T, K = NoRuntimeLimits> {
     schemars(bound = "T: JsonSchema, T::Fragment: JsonSchema + Default")
 )]
 pub struct MemoryLimits<T> {
-    // The maximum amount of memory that should be available
-    // Should in most cases be mapped to resources.limits.memory
+    /// The maximum amount of memory that should be available to the Pod.
+    /// Specified as a byte [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/),
+    /// which means these suffixes are supported: E, P, T, G, M, k.
+    /// You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.
+    /// For example, the following represent roughly the same value:
+    /// `128974848, 129e6, 129M,  128974848000m, 123Mi`
     pub limit: Option<Quantity>,
-    // Additional options that may be required
+    /// Additional options that can be specified.
     #[fragment_attrs(serde(default))]
     pub runtime_limits: T,
 }
@@ -211,8 +215,6 @@ pub struct JvmHeapLimits {
     pub min: Option<Quantity>,
 }
 
-// Cpu limits
-// These should usually be forwarded to resources.limits.cpu
 #[derive(Clone, Debug, Default, Fragment, PartialEq, JsonSchema)]
 #[fragment(path_overrides(fragment = "crate::config::fragment"))]
 #[fragment_attrs(
@@ -230,7 +232,15 @@ pub struct JvmHeapLimits {
     serde(rename_all = "camelCase")
 )]
 pub struct CpuLimits {
+    /// The minimal amount of CPU cores that Pods need to run.
+    /// Equivalent to the `request` for Pod resource configuration.
+    /// Cores are specified either as a decimal point number or as milli units.
+    /// For example:`1.5` will be 1.5 cores, also written as `1500m`.
     pub min: Option<Quantity>,
+    /// The maximum amount of CPU cores that can be requested by Pods.
+    /// Equivalent to the `limit` for Pod resource configuration.
+    /// Cores are specified either as a decimal point number or as milli units.
+    /// For example:`1.5` will be 1.5 cores, also written as `1500m`.
     pub max: Option<Quantity>,
 }
 

src/commons/s3.rs

@@ -33,9 +33,12 @@ use crate::{
 )]
 #[serde(rename_all = "camelCase")]
 pub struct S3BucketSpec {
+    /// The name of the S3 bucket.
     // FIXME: Try to remove the Option<>, as this field should be mandatory
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub bucket_name: Option<String>,
+
+    /// The definition of an S3 connection, either inline or as a reference.
     // FIXME: Try to remove the Option<>, as this field should be mandatory
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub connection: Option<S3ConnectionDef>,
@@ -91,11 +94,17 @@ impl InlinedS3BucketSpec {
     }
 }
 
-/// Operators are expected to define fields for this type in order to work with S3 buckets.
+/// An S3 bucket definition, it can either be a reference to an explicit S3Bucket object,
+/// or it can be an inline defintion of a bucket. Read the
+/// [S3 resources concept documentation](https://docs.stackable.tech/home/nightly/concepts/s3)
+/// to learn more.
 #[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub enum S3BucketDef {
+    /// An inline definition, containing the S3 bucket properties.
     Inline(S3BucketSpec),
+    /// A reference to an S3 bucket object. This is simply the name of the `S3Bucket`
+    /// resource.
     Reference(String),
 }
 
@@ -122,7 +131,9 @@ impl S3BucketDef {
 #[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub enum S3ConnectionDef {
+    /// Inline definition of an S3 connection.
     Inline(S3ConnectionSpec),
+    /// A reference to an S3Connection resource.
     Reference(String),
 }
 
@@ -160,24 +171,28 @@ impl S3ConnectionDef {
 )]
 #[serde(rename_all = "camelCase")]
 pub struct S3ConnectionSpec {
+    /// Hostname of the S3 server without any protocol or port. For example: `west1.my-cloud.com`.
     // FIXME: Try to remove the Option<>, as this field should be mandatory
-    /// Hostname of the S3 server without any protocol or port
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub host: Option<String>,
+
     /// Port the S3 server listens on.
-    /// If not specified the products will determine the port to use.
+    /// If not specified the product will determine the port to use.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub port: Option<u16>,
+
     // FIXME: Try to remove the Option<>, as this field should be mandatory
     /// Which access style to use.
     /// Defaults to virtual hosted-style as most of the data products out there.
-    /// Have a look at the official documentation on <https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html>
+    /// Have a look at the [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub access_style: Option<S3AccessStyle>,
+
     /// If the S3 uses authentication you have to specify you S3 credentials.
     /// In the most cases a SecretClass providing `accessKey` and `secretKey` is sufficient.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub credentials: Option<SecretClassVolume>,
+
     /// If you want to use TLS when talking to S3 you can enable TLS encrypted communication with this setting.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub tls: Option<Tls>,

src/product_logging/spec.rs

@@ -68,15 +68,15 @@ use serde::{Deserialize, Serialize};
         rename_all = "camelCase",
     ),
     // We don't want Rust code in public API descriptions
-    schemars(description = "Logging configuration")
+    schemars(description = "Logging configuration, learn more in the [logging concept documentation](https://docs.stackable.tech/home/nightly/concepts/logging).")
 )]
 pub struct Logging<T>
 where
     T: Clone + Display + Ord,
 {
-    /// Wether or not to deploy a container with the Vector log agent
+    /// Wether or not to deploy a container with the Vector log agent.
     pub enable_vector_agent: bool,
-    /// Log configuration per container
+    /// Log configuration per container.
     #[fragment_attrs(serde(default))]
     pub containers: BTreeMap<T, ContainerLogConfig>,
 }

src/role_utils.rs

@@ -113,13 +113,39 @@ pub struct CommonConfiguration<T> {
     // does not support specifying custom bounds.
     #[schemars(default = "config_schema_default")]
     pub config: T,
+    /// The `configOverrides` can be used to configure properties in product config files
+    /// that are not exposed in the CRD. For example, for a HdfsCluster:
+    ///
+    /// ```yaml
+    ///   configOverrides: # on role level
+    ///     core-site.xml: # the name of the configuration file
+    ///       fs.trash.interval: "5"  # the name of the property and the value to set
+    /// ```
+    ///
+    /// Read the
+    /// [config overrides documentation](https://docs.stackable.tech/home/nightly/concepts/overrides#config-overrides)
+    /// and consult the operator specific usage guide documentation for details on the
+    /// available config files and settings for the specific product.
     #[serde(default)]
     pub config_overrides: HashMap<String, HashMap<String, String>>,
+    /// `envOverrides` configure environment variables to be set in the Pods.
+    /// It is a map from strings to strings - environment variables and the value to set.
+    /// Read the
+    /// [environment variable overrides documentation](https://docs.stackable.tech/home/nightly/concepts/overrides#env-overrides)
+    /// for more information and consult the operator specific usage guide to find out about
+    /// the product specific environment variables that are available.
     #[serde(default)]
     pub env_overrides: HashMap<String, String>,
     // BTreeMap to keep some order with the cli arguments.
+    // TODO add documentation.
     #[serde(default)]
     pub cli_overrides: BTreeMap<String, String>,
+    /// In the `podOverrides` property you can define a
+    /// [PodTemplateSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)
+    /// to override any property that can be set on a Kubernetes Pod.
+    /// Read the
+    /// [Pod overrides documentation](https://docs.stackable.tech/home/nightly/concepts/overrides#pod-overrides)
+    /// for more information.
     #[serde(default)]
     #[schemars(schema_with = "pod_overrides_schema")]
     pub pod_overrides: PodTemplateSpec,