fix(docs-447): clarify the use of shared app values from Score worklo…

…ads (#98) Co-authored-by: Tobias Babin <[email protected]> Co-authored-by: Tobias Babin <[email protected]>
humanitec-architecture · Nov 7, 2024 · 796c85f · 796c85f
1 parent 1cdab17
commit 796c85f
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 6 deletions.
diff --git a/score/environment-variables/README.md b/score/environment-variables/README.md
@@ -2,8 +2,36 @@ Define environment variables for a container. There are two ways to configure th
 
 1. Via the Score file
 
-    This definition supports [placeholders](https://developer.humanitec.com/platform-orchestrator/reference/placeholders/). By default, variables will be visible in the Platform Orchestrator UI. Variables will be mapped into the container through a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) or [Secret](https://kubernetes.io/docs/concepts/configuration/secret/).
+    The Score specification supports [placeholder references](https://docs.score.dev/docs/score-specification/score-spec-reference/#placeholder-references) to the Workload metadata or Resources named in the Score file. The syntax and supported values are different in Score compared to the Platform Orchestrator, and the Platform Orchestrator will automatically convert Score references to native [placeholders](https://developer.humanitec.com/platform-orchestrator/reference/placeholders/) when deploying a Score file. Variables will be mapped into the container through a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) or [Secret](https://kubernetes.io/docs/concepts/configuration/secret/).
 
-2. Via the Score extension file
+    The Platform Orchestrator supports an `environment` resource for accessing the shared values in the application environment:
+
+    ```yaml
+    apiVersion: score.dev/v1b1
+    metadata:
+      name: example
+    containers:
+      main:
+        image: example
+        variables:
+          KEY_ONE: hello-world
+          KEY_TWO: ${resources.env.VALUE}
+    resources:
+      env:
+        type: environment
+    ```
+
+2. Via the Score extensions file
+
+    Score extensions files contain Platform Orchestrator specific content allowing the workload profile or deployment options to be configured along with overrides to the resulting workloads. The Score extensions file supports the use of Score [placeholder references](https://docs.score.dev/docs/score-specification/score-spec-reference/#placeholder-references) and native [placeholders](https://developer.humanitec.com/platform-orchestrator/reference/placeholders/) when escaped with a `$`.
+
+    ```yaml
+    apiVersion: humanitec.org/v1b1
+    spec:
+      containers:
+        main:
+          variables:
+            KEY_THREE: $${values.VALUE}
+            KEY_FOUR: goodbye
+    ```
 
-    This definition does not support [placeholders](https://developer.humanitec.com/platform-orchestrator/reference/placeholders/). By default, variables will not be visible in the Platform Orchestrator UI. Variables will be mapped into the container as part of the container specification.
diff --git a/score/environment-variables/humanitec.score.yaml b/score/environment-variables/humanitec.score.yaml
@@ -3,6 +3,6 @@ apiVersion: humanitec.org/v1b1
 spec:
   containers:
     demo:
-      env:
-      - name: "SOME"
-        value: "VARIABLE"
+      variables:
+        SOME: VARIABLE
+        SHARED_VALUE: $${values.SOMETHING}