feat: Make spark-env.sh configurable

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Make spark-env.sh configurable via `configOverrides` ([#473]).
+
 ### Changed
 
 - Reduce CRD size from `1.2MB` to `103KB` by accepting arbitrary YAML input instead of the underlying schema for the following fields ([#450]):
@@ -28,6 +32,7 @@ All notable changes to this project will be documented in this file.
 [#459]: https://github.com/stackabletech/spark-k8s-operator/pull/459
 [#460]: https://github.com/stackabletech/spark-k8s-operator/pull/460
 [#472]: https://github.com/stackabletech/spark-k8s-operator/pull/472
+[#473]: https://github.com/stackabletech/spark-k8s-operator/pull/473
 
 ## [24.7.0] - 2024-07-24
 

docs/modules/spark-k8s/pages/usage-guide/configuration-environment-overrides.adoc

@@ -0,0 +1,150 @@
+= Configuration & Environment Overrides
+
+The cluster definition also supports overriding configuration properties and environment variables, either per role or per role group, where the more specific override (role group) has precedence over the less specific one (role).
+
+IMPORTANT: Overriding operator-set properties (such as the ports) can interfere with the operator and can lead to problems.
+
+
+== Configuration Properties
+
+For a role or role group, at the same level of `config`, you can specify `configOverrides` for the following files:
+
+* `spark-env.sh`
+* `security.properties`
+
+NOTE: `spark-defaults.conf` is not required here, because the properties defined in {crd-docs}/spark.stackable.tech/sparkhistoryserver/v1alpha1/#spec-sparkConf[`sparkConf` (SparkHistoryServer)] and {crd-docs}/spark.stackable.tech/sparkapplication/v1alpha1/#spec-sparkConf[`sparkConf` (SparkApplication)] are already added to this file.
+
+For example, if you want to set the `networkaddress.cache.ttl`, it can be configured in the SparkHistoryServer resource like so:
+
+[source,yaml]
+----
+nodes:
+  roleGroups:
+    default:
+      configOverrides:
+        security.properties:
+          networkaddress.cache.ttl: "30"
+      replicas: 1
+----
+
+Just as for the `config`, it is possible to specify this at the role level as well:
+
+[source,yaml]
+----
+nodes:
+  configOverrides:
+    security.properties:
+      networkaddress.cache.ttl: "30"
+  roleGroups:
+    default:
+      replicas: 1
+----
+
+All override property values must be strings.
+
+The same applies to the `job`, `driver` and `executor` roles of the SparkApplication.
+
+=== The spark-env.sh file
+
+The `spark-env.sh` file is used to set environment variables.
+Usually, environment variables are configured in `envOverrides` or {crd-docs}/spark.stackable.tech/sparkapplication/v1alpha1/#spec-env[`env` (SparkApplication)], but both options only allow static values to be set.
+The values in `spark-env.sh` are evaluated by the shell.
+For instance, if a SAS token is stored in a Secret and should be used for the Spark History Server, this token could be first stored in an environment variable via `podOverrides` and then added to the `SPARK_HISTORY_OPTS`:
+
+[source,yaml]
+----
+podOverrides:
+  spec:
+    containers:
+    - name: spark-history
+      env:
+      - name: SAS_TOKEN
+        valueFrom:
+          secretKeyRef:
+            name: adls-spark-credentials
+            key: sas-token
+configOverrides:
+  spark-env.sh:
+    SPARK_HISTORY_OPTS: >-
+      $SPARK_HISTORY_OPTS
+      -Dspark.hadoop.fs.azure.sas.fixed.token.mystorageaccount.dfs.core.windows.net=$SAS_TOKEN
+----
+
+NOTE: The given properties are written to `spark-env.sh` in the form `export KEY="VALUE"`.
+Make sure to escape the value already in the specification.
+Be aware that some environment variables may already be set, so prepend or append a reference to them in the value, as it is done in the example.
+
+=== The security.properties file
+
+The `security.properties` file is used to configure JVM security properties.
+It is very seldom that users need to tweak any of these, but there is one use-case that stands out, and that users need to be aware of: the JVM DNS cache.
+
+The JVM manages its own cache of successfully resolved host names as well as a cache of host names that cannot be resolved.
+Some products of the Stackable platform are very sensitive to the contents of these caches and their performance is heavily affected by them.
+As of version 3.4.0, Apache Spark may perform poorly if the positive cache is disabled.
+To cache resolved host names, and thus speed up queries, you can configure the TTL of entries in the positive cache like this:
+
+[source,yaml]
+----
+spec:
+  nodes:
+    configOverrides:
+      security.properties:
+        networkaddress.cache.ttl: "30"
+        networkaddress.cache.negative.ttl: "0"
+----
+
+NOTE: The operator configures DNS caching by default as shown in the example above.
+
+For details on the JVM security see https://docs.oracle.com/en/java/javase/11/security/java-security-overview1.html
+
+
+== Environment Variables
+
+Similarly, environment variables can be (over)written. For example per role group:
+
+[source,yaml]
+----
+nodes:
+  roleGroups:
+    default:
+      envOverrides:
+        MY_ENV_VAR: "MY_VALUE"
+      replicas: 1
+----
+
+or per role:
+
+[source,yaml]
+----
+nodes:
+  envOverrides:
+    MY_ENV_VAR: "MY_VALUE"
+  roleGroups:
+    default:
+      replicas: 1
+----
+
+In a SparkApplication, environment variables can also be defined with the {crd-docs}/spark.stackable.tech/sparkapplication/v1alpha1/#spec-env[`env`] property for the job, driver and executor pods at once.
+The result is basically the same as with `envOverrides`, but `env` also allows to reference Secrets and so on:
+
+[source,yaml]
+----
+---
+apiVersion: spark.stackable.tech/v1alpha1
+kind: SparkApplication
+spec:
+  env:
+  - name: SAS_TOKEN
+    valueFrom:
+      secretKeyRef:
+        name: adls-spark-credentials
+        key: sas-token
+  ...
+----
+
+
+== Pod overrides
+
+The Spark operator also supports Pod overrides, allowing you to override any property that you can set on a Kubernetes Pod.
+Read the xref:concepts:overrides.adoc#pod-overrides[Pod overrides documentation] to learn more about this feature.

docs/modules/spark-k8s/pages/usage-guide/history-server.adoc

@@ -74,32 +74,3 @@ spark-history-node-cleaner   NodePort    10.96.203.43    <none>        18080:325
 By setting up port forwarding on 18080 the UI can be opened by pointing your browser to `http://localhost:18080`:
 
 image::history-server-ui.png[History Server Console]
-
-== Configuration Properties
-
-For a role group of the Spark history server, you can specify: `configOverrides` for the following files:
-
-* `security.properties`
-
-=== The security.properties file
-
-The `security.properties` file is used to configure JVM security properties.
-It is very seldom that users need to tweak any of these, but there is one use-case that stands out, and that users need to be aware of: the JVM DNS cache.
-
-The JVM manages its own cache of successfully resolved host names as well as a cache of host names that cannot be resolved.
-Some products of the Stackable platform are very sensible to the contents of these caches and their performance is heavily affected by them.
-As of version 3.4.0, Apache Spark may perform poorly if the positive cache is disabled.
-To cache resolved host names, and thus speeding up queries you can configure the TTL of entries in the positive cache like this:
-
-[source,yaml]
-----
-  nodes:
-    configOverrides:
-      security.properties:
-        networkaddress.cache.ttl: "30"
-        networkaddress.cache.negative.ttl: "0"
-----
-
-NOTE: The operator configures DNS caching by default as shown in the example above.
-
-For details on the JVM security see https://docs.oracle.com/en/java/javase/11/security/java-security-overview1.html

docs/modules/spark-k8s/partials/nav.adoc

@@ -10,6 +10,7 @@
 ** xref:spark-k8s:usage-guide/logging.adoc[]
 ** xref:spark-k8s:usage-guide/history-server.adoc[]
 ** xref:spark-k8s:usage-guide/examples.adoc[]
+** xref:spark-k8s:usage-guide/configuration-environment-overrides.adoc[]
 ** xref:spark-k8s:usage-guide/operations/index.adoc[]
 *** xref:spark-k8s:usage-guide/operations/applications.adoc[]
 *** xref:spark-k8s:usage-guide/operations/pod-placement.adoc[]

rust/crd/src/constants.rs

@@ -74,6 +74,7 @@ pub const HISTORY_ROLE_NAME: &str = "node";
 pub const SPARK_IMAGE_BASE_NAME: &str = "spark-k8s";
 
 pub const SPARK_DEFAULTS_FILE_NAME: &str = "spark-defaults.conf";
+pub const SPARK_ENV_SH_FILE_NAME: &str = "spark-env.sh";
 
 pub const SPARK_CLUSTER_ROLE: &str = "spark-k8s-clusterrole";
 pub const SPARK_UID: i64 = 1000;

rust/crd/src/history.rs

@@ -212,6 +212,7 @@ impl SparkHistoryServer {
             (
                 vec![
                     PropertyNameKind::File(SPARK_DEFAULTS_FILE_NAME.to_string()),
+                    PropertyNameKind::File(SPARK_ENV_SH_FILE_NAME.to_string()),
                     PropertyNameKind::File(JVM_SECURITY_PROPERTIES_FILE.to_string()),
                 ],
                 self.spec.nodes.clone(),

rust/crd/src/lib.rs

@@ -819,6 +819,7 @@ impl SparkApplication {
             (
                 vec![
                     PropertyNameKind::Env,
+                    PropertyNameKind::File(SPARK_ENV_SH_FILE_NAME.to_string()),
                     PropertyNameKind::File(JVM_SECURITY_PROPERTIES_FILE.to_string()),
                 ],
                 Role {
@@ -841,6 +842,7 @@ impl SparkApplication {
             (
                 vec![
                     PropertyNameKind::Env,
+                    PropertyNameKind::File(SPARK_ENV_SH_FILE_NAME.to_string()),
                     PropertyNameKind::File(JVM_SECURITY_PROPERTIES_FILE.to_string()),
                 ],
                 Role {
@@ -863,6 +865,7 @@ impl SparkApplication {
             (
                 vec![
                     PropertyNameKind::Env,
+                    PropertyNameKind::File(SPARK_ENV_SH_FILE_NAME.to_string()),
                     PropertyNameKind::File(JVM_SECURITY_PROPERTIES_FILE.to_string()),
                 ],
                 Role {
@@ -1037,6 +1040,20 @@ fn resources_to_executor_props(
     Ok(())
 }
 
+/// Create the content of the file spark-env.sh.
+/// The properties are serialized in the form 'export {k}="{v}"',
+/// escaping neither the key nor the value. The user is responsible for
+/// providing escaped values.
+pub fn to_spark_env_sh_string<'a, T>(properties: T) -> String
+where
+    T: Iterator<Item = (&'a String, &'a String)>,
+{
+    properties
+        .map(|(k, v)| format!("export {k}=\"{v}\""))
+        .collect::<Vec<String>>()
+        .join("\n")
+}
+
 #[cfg(test)]
 mod tests {
 
@@ -1296,6 +1313,10 @@ mod tests {
             "default".into(),
             vec![
                 (PropertyNameKind::Env, BTreeMap::new()),
+                (
+                    PropertyNameKind::File("spark-env.sh".into()),
+                    BTreeMap::new(),
+                ),
                 (
                     PropertyNameKind::File("security.properties".into()),
                     vec![

rust/operator-binary/src/history/history_controller.rs

@@ -36,7 +36,7 @@ use stackable_operator::{
     role_utils::RoleGroupRef,
     time::Duration,
 };
-use stackable_spark_k8s_crd::constants::METRICS_PORT;
+use stackable_spark_k8s_crd::constants::{METRICS_PORT, SPARK_ENV_SH_FILE_NAME};
 use stackable_spark_k8s_crd::{
     constants::{
         ACCESS_KEY_ID, APP_NAME, HISTORY_CONTROLLER_NAME, HISTORY_ROLE_NAME,
@@ -49,7 +49,7 @@ use stackable_spark_k8s_crd::{
     history,
     history::{HistoryConfig, SparkHistoryServer, SparkHistoryServerContainer},
     s3logdir::S3LogDir,
-    tlscerts,
+    tlscerts, to_spark_env_sh_string,
 };
 use std::collections::HashMap;
 use std::{collections::BTreeMap, sync::Arc};
@@ -382,6 +382,16 @@ fn build_config_map(
                 .build(),
         )
         .add_data(SPARK_DEFAULTS_FILE_NAME, spark_defaults)
+        .add_data(
+            SPARK_ENV_SH_FILE_NAME,
+            to_spark_env_sh_string(
+                config
+                    .get(&PropertyNameKind::File(SPARK_ENV_SH_FILE_NAME.to_string()))
+                    .cloned()
+                    .unwrap_or_default()
+                    .iter(),
+            ),
+        )
         .add_data(
             JVM_SECURITY_PROPERTIES_FILE,
             to_java_properties_string(jvm_sec_props.iter()).with_context(|_| {