Add terms section, add clarifier in front of each use of runtime, and note on Spin app env vars

kate-goldenring · kate-goldenring · commit a1a930eb0a83 · 2024-07-10T15:17:45.000-05:00
Signed-off-by: Kate Goldenring &lt;kate.goldenring@fermyon.com&gt;
diff --git a/containerd-shim-spin-config.md b/containerd-shim-spin-config.md
@@ -1,6 +1,6 @@
 # SKIP 00X - Configuring Runtime Options in the `containerd-shim-spin`
 
-Summary: Configuring runtime options in the `containerd-shim-spin`
+Summary: Configuring Spin runtime options in the `containerd-shim-spin`
 
 Owner: Kate Goldenring <kate.goldenring@fermyon.com> 
 
@@ -17,7 +17,7 @@ Created: 30/05/2024
 
 ## Overview
 
-The `containerd-shim-spin` SpinKube executor currently lackd the ability to configure runtime flags for Spin applications. This proposal aims to address this by enabling three types of configurations: Spin execution settings, shim execution settings, and shim execution environment variables. These configurations will be set via Custom Resource Definitions (CRDs) in Kubernetes, specifically extending the SpinExecutor and SpinApp CRDs. This approach will allow operators to easily configure both the application and the platform execution environments.
+The `containerd-shim-spin` SpinKube executor currently lack the ability to configure Spin runtime flags for Spin applications. This proposal aims to address this by enabling three types of configurations: Spin execution settings, shim execution settings, and shim execution environment variables. These configurations will be set via Custom Resource Definitions (CRDs) in Kubernetes, specifically extending the SpinExecutor and SpinApp CRDs. This approach will allow operators to easily configure both the application and the platform execution environments.
 
 ## Background
 
@@ -42,22 +42,41 @@ A Runwasi containerd shim does more than execute a Wasm runtime such as Spin or
 
 In summary, the following are types of configuration that should be supported:
 
-- Wasm runtime specific options (oftentimes in the form of CLI flags: `spin up --listen "127.0.0.1:3000"`)
-- Wasm runtime environment variables (such as `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 spin up` )
-- Shim execution options (such as disabling pre-compilation)
-- Shim execution environment variables (such as `RUST LOG`)
+- Spin runtime specific options (oftentimes in the form of CLI flags: `spin up --listen "127.0.0.1:3000"`)
+- Spin runtime environment variables (such as `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 spin up` )
+- Spin shim execution options (such as disabling pre-compilation)
+- Spin shim execution environment variables (such as `RUST LOG`)
 
-Combining the first two categories and focusing on the Spin runtime, the list can be simplified:
+The list can be simplified to abstract how configuration is set (flag, file, or environment variable):
 
 - Spin execution configuration
 - Shim execution configuration
-- Shim execution environment variables
+
+Note, that this list does not include Wasm instance environment variables. This document is focused on configuring the Wasm engine, namely Spin. The proposed approach does conclude that Wasm instance environment variables should not be configurable from the PodSpec; rather, Spin users should use configuration variables instead. See the ["Configuring Spin Execution in Container Environment Variables" section](#configuring-spin-execution-in-container-environment-variables) for more context.
+
+## Terminology
+
+| Term | Definition |
+| ---- | ---------- |
+| Container runtime | A program that runs and manages the lifecycle of containers, or in this case Spin apps, i.e. Youki. |
+| CRD | Custom Resource Definition, a Kubernetes extension mechanism for defining custom resources |
+| Environment Variables | Variables that are part of the environment in which a process runs |
+| PodSpec | A Kubernetes object that describes the specification of a pod, including its containers, volumes, and other properties |
+| Shim | A containerd shim, a lightweight process that acts as an intermediary between a container and the container runtime |
+| Spin | A CLI tool for scaffolding, building and running serverless Wasm components |
+| SpinApp | A custom resource definition (CRD) in Kubernetes that represents a Spin application |
+| SpinExecutor | A custom resource definition (CRD) in Kubernetes that represents a Spin executor (such as the Spin containerd shim) |
+| SpinKube | A Kubernetes operator for managing Spin applications |
+| Spin runtime | A Wasm execution engine that executes Wasm components using Wasmtime |
+| Wasm execution engine | An engine that execute Wasm components using a Wasm runtime, i.e. Spin which uses Wasmtime |
+| Wasm runtime | A WebAssembly runtime, i.e. Wasmtime |
+| Wasmtime | The WebAssembly runtime that Spin uses to execute WebAssembly components |
 
 ### Current Workarounds
 
-#### Wasm Runtime Specific Options Workaround
+#### Spin Runtime Specific Options Workaround
 
-None, unless an environment variable is also exposed for the flag and can be configured with the [Wasm runtime environment variables workaround](#Wasm-runtime-environment-variables-workaround).
+None, unless an environment variable is also exposed for the flag and can be configured with the [Spin runtime environment variables workaround](#spin-runtime-environment-variables-workaround).
 
 These flags could be set in the runtime arguments for the container, such as the following in a Kubernetes PodSpec:
 
@@ -71,9 +90,9 @@ These flags could be set in the runtime arguments for the container, such as the
 
 While the shim currently has access to these arguments from the [`RuntimeContext` args](https://github.com/containerd/runwasi/blob/f5f497c4b21a5d55613095a3ae878c4ef4b83b91/crates/containerd-shim-wasm/src/container/context.rs#L14), the shim does not parse these arguments and would need to be enlightened in a similar manner as the Spin CLI to discern which are for which trigger.
 
-#### Wasm Runtime Environment Variables Workaround
+#### Spin Runtime Environment Variables Workaround
 
-There is no SpinKube native way to configure environment variables on the runtime process. Working around the Spin operator, these environment variables can be configured by setting them in the container spec of a Spin app deployment:
+There is no SpinKube native way to configure environment variables on the Spin. Working around the Spin operator, these environment variables can be configured by setting them in the container spec of a Spin app deployment:
 
 ```yaml
 containers:
@@ -140,7 +159,7 @@ All Spin execution configuration will be defined as known environment variables
 | Key | Spin CLI |  Example Value|
 | ---- | ---- | ---- |
 | SPIN_HTTP_LISTEN_ADDR | `spin up --listen` | "0.0.0.0:3000" |
-| OTEL_EXPORTER_OTLP_ENDPOINT | `OTEL_EXPORTER_OTLP_ENDPOINT=http://123.4.5.6:4318" spin up` | "http://123.4.5.6:4318" |
+| OTEL_EXPORTER_OTLP_ENDPOINT | `OTEL_EXPORTER_OTLP_ENDPOINT=http://123.4.5.6:4318 spin up` | "http://123.4.5.6:4318" |
 | SPIN_LOG_DIR | `spin up --log-dir /tmp/log` | "/tmp/log" |
 | RUNTIME_CONFIG_FILE | `spin up --runtime-config-file /var/config.toml` | "/var/config.toml" |
 
@@ -179,7 +198,7 @@ spec
     ...
 ```
 
-The `containerd-shim-spin` instance will look for all supported runtime environment variables and configure execution accordingly.
+The `containerd-shim-spin` instance will look for all supported Spin runtime environment variables and configure execution accordingly.
 
 ### Configuring Shim Execution in Containerd Config Options
 
@@ -226,9 +245,9 @@ The following are alternate strategies for configuring the Spin runtime in the `
 
 1. Spin execution options could be configured in in Pod annotations; however, it is not granular enough for the case of two Spin apps in a Pod, for example, [listen ports could still conflict](https://github.com/spinkube/containerd-shim-spin/issues/52).
 
-2. As shown in the [runtime configuration workaround](#wasm-runtime-specific-options-workaround), options could be set as container arguments, but setting flags in CRDs is less ergonomic than environment variables, and parsing logic would need to be added to the shim. However, taking this path would potentially enable reusing Spin's reconciling of the mutual exclusiveness of flags.
+2. As shown in the [Spin runtime configuration workaround](#wasm-runtime-specific-options-workaround), options could be set as container arguments, but setting flags in CRDs is less ergonomic than environment variables, and parsing logic would need to be added to the shim. However, taking this path would potentially enable reusing Spin's reconciling of the mutual exclusiveness of flags.
 
-3. Spin Runtime config (`runtime-config.toml`) could be enhanced to support configuring triggers. Right now, runtime config is used to configure host components. So far, it has been used the describe how to configure the host environment for the guest. That could encompass considering how the host should be triggered to invoke the guest. This may be the better long term solution; however, it will take design to consider the scope of Spin runtime config.
+3. Spin Runtime config (`runtime-config.toml`) could be enhanced to support configuring triggers. Right now, the Spin runtime config file is used to configure host components. So far, it has been used the describe how to configure the host environment for the guest. That could encompass considering how the host should be triggered to invoke the guest. This may be the better long term solution; however, it will take design to consider the scope of Spin runtime config.
 
 4. Alternatively, there may be places each of these configuration options fit outside of CLI flags. For example, the port for HTTP triggered apps could be configured in the trigger specification in the `spin.toml`. Log directory is already a part of [runtime config](https://github.com/fermyon/spin/blob/b3db535c9edb72278d4db3a201f0ed214e561354/crates/trigger/src/runtime_config.rs#L203-L204) despite the fact that users are more comfortable configuring it through the Spin CLI.
 
