feat: allow overrides to env vars on session start

Author: ciyer

components/renku_data_services/notebooks/api.spec.yaml

@@ -419,6 +419,27 @@ components:
       - anonymous
       - registered
       type: object
+    EnvVariableOverrides:
+      description: Environment variable overrides for the session pod
+      type: array
+      items:
+        $ref: "#/components/schemas/EnvVarOverride"
+    EnvVarOverride:
+      description: Override an env variable defined in the session launcher
+      type: object
+      properties:
+        name:
+          type: string
+          maxLength: 256
+          # based on https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_235
+          pattern: "^[a-zA-Z_][a-zA-Z0-9_]*$"
+          example: MY_VAR
+        value:
+          type: string
+          maxLength: 500
+      required:
+        - name
+        - value
     ErrorResponse:
       type: object
       properties:
@@ -865,6 +886,8 @@ components:
           type: integer
         cloudstorage:
           $ref: "#/components/schemas/SessionCloudStoragePostList"
+        env_variable_overrides:
+          $ref: "#/components/schemas/EnvVariableOverrides"
       required:
         - launcher_id
       type: object

components/renku_data_services/notebooks/apispec.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  api.spec.yaml
-#   timestamp: 2025-03-19T10:21:13+00:00
+#   timestamp: 2025-04-17T14:26:28+00:00
 
 from __future__ import annotations
 
@@ -34,6 +34,13 @@ class DefaultCullingThresholds(BaseAPISpec):
     registered: CullingThreshold
 
 
+class EnvVarOverride(BaseAPISpec):
+    name: str = Field(
+        ..., examples=["MY_VAR"], max_length=256, pattern="^[a-zA-Z_][a-zA-Z0-9_]*$"
+    )
+    value: str = Field(..., max_length=500)
+
+
 class Error(BaseAPISpec):
     code: int = Field(..., examples=[1404], gt=0)
     detail: Optional[str] = Field(
@@ -384,6 +391,9 @@ class SessionPostRequest(BaseAPISpec):
     )
     resource_class_id: Optional[int] = None
     cloudstorage: Optional[List[SessionCloudStoragePost]] = None
+    env_variable_overrides: Optional[List[EnvVarOverride]] = Field(
+        None, description="Environment variable overrides for the session pod"
+    )
 
 
 class SessionResponse(BaseAPISpec):

components/renku_data_services/notebooks/blueprints.py

@@ -33,11 +33,13 @@
     get_extra_containers,
     get_extra_init_containers,
     get_gitlab_image_pull_secret,
+    get_launcher_env_variables,
     patch_session,
     request_dc_secret_creation,
     request_session_secret_creation,
     requires_image_pull_secret,
     resources_from_resource_class,
+    verify_launcher_env_variable_overrides,
 )
 from renku_data_services.notebooks.crs import (
     AmaltheaSessionSpec,
@@ -377,6 +379,8 @@ async def _handler(
 
             secrets_to_create.append(auth_secret)
 
+            # Raise an error if there are invalid environment variables in the request body
+            verify_launcher_env_variable_overrides(launcher, body)
             env = [
                 SessionEnvItem(name="RENKU_BASE_URL_PATH", value=base_server_path),
                 SessionEnvItem(name="RENKU_BASE_URL", value=base_server_url),
@@ -386,12 +390,9 @@ async def _handler(
                 SessionEnvItem(name="RENKU_SESSION_PORT", value=f"{environment.port}"),
                 SessionEnvItem(name="RENKU_WORKING_DIR", value=work_dir.as_posix()),
             ]
-            if launcher.env_variables:
-                env.extend(
-                    SessionEnvItem(name=env_var.name, value=env_var.value)
-                    for env_var in launcher.env_variables
-                    if env_var.value
-                )
+            launcher_env_variables = get_launcher_env_variables(launcher, body)
+            if launcher_env_variables:
+                env.extend(launcher_env_variables)
 
             manifest = AmaltheaSessionV1Alpha1(
                 metadata=Metadata(name=server_name, annotations=annotations),

components/renku_data_services/notebooks/core_sessions.py

@@ -44,6 +44,7 @@
     Resources,
     SecretAsVolume,
     SecretAsVolumeItem,
+    SessionEnvItem,
     State,
 )
 from renku_data_services.notebooks.models import ExtraSecret
@@ -53,6 +54,7 @@
 )
 from renku_data_services.project.db import ProjectRepository
 from renku_data_services.project.models import Project, SessionSecret
+from renku_data_services.session.models import SessionLauncher
 from renku_data_services.users.db import UserRepo
 from renku_data_services.utils.cryptography import get_encryption_key
 
@@ -311,6 +313,29 @@ async def request_dc_secret_creation(
                 )
 
 
+def get_launcher_env_variables(launcher: SessionLauncher, body: apispec.SessionPostRequest) -> list[SessionEnvItem]:
+    """Get the environment variables from the launcher, with overrides from the request."""
+    output: list[SessionEnvItem] = []
+    env_overrides = {i.name: i.value for i in body.env_variable_overrides or []}
+    for env in launcher.env_variables or []:
+        if env.name in env_overrides:
+            output.append(SessionEnvItem(name=env.name, value=env_overrides[env.name]))
+        else:
+            output.append(SessionEnvItem(name=env.name, value=env.value))
+    return output
+
+
+def verify_launcher_env_variable_overrides(launcher: SessionLauncher, body: apispec.SessionPostRequest) -> None:
+    """Raise an error if there are env variables that are not defined in the launcher."""
+    env_overrides = {i.name: i.value for i in body.env_variable_overrides or []}
+    known_env_names = {i.name for i in launcher.env_variables or []}
+    unknown_env_names = set(env_overrides.keys()) - known_env_names
+    if unknown_env_names:
+        message = f"""The following environment variables are not defined in the session launcher: {unknown_env_names}.
+            Please remove them from the launch request or add them to the session launcher."""
+        raise errors.ValidationError(message=message)
+
+
 async def request_session_secret_creation(
     user: AuthenticatedAPIUser | AnonymousAPIUser,
     nb_config: NotebooksConfig,

test/bases/renku_data_services/data_api/test_sessions.py

@@ -1108,6 +1108,9 @@ async def test_starting_session_anonymous(
             "name": "test",
             "port": 8888,
         },
+        env_variables=[
+            {"name": "TEST_ENV_VAR", "value": "some-random-value-1234"},
+        ],
     )
     launcher_id = launcher["id"]
     project_id = project["id"]