docs: add doc about env vars scenarios

docs/env-vars.md

@@ -0,0 +1,83 @@
+# Environment variables
+
+There are some tricky scenarios that can come up when trying to pass environment variables to k6-operator tests, esp. when archives are involved. Let's describe them.
+
+Assuming I have a `test.js` with the following options:
+
+```js
+const VUS = __ENV.TEST_VUS || 10000;
+
+export const options = {
+    vus: VUS,
+    duration: '300s',
+    setupTimeout: '600s'
+};
+```
+
+There are several ways this `test.js` can be configured by k6-operator. Let's look into some of them.
+
+## ConfigMap with `test.js`
+
+ConfigMap `env-test` contains a `test.js` file. TestRun definition:
+
+```yaml
+apiVersion: k6.io/v1alpha1
+kind: TestRun
+metadata:
+  name: k6-sample
+spec:
+  parallelism: 2
+  script:
+    configMap:
+      name: "env-test"
+      file: "test.js"
+  runner:
+    env:
+      - name: TEST_VUS
+        value: "42"
+```
+
+In this case, there will be 42 VUs in total, equally split between 2 runners. This can be confirmed with [k6 execution API](https://grafana.com/docs/k6/latest/javascript-api/k6-execution/).
+
+## ConfigMap has `archive.tar` with system env vars
+
+`archive.tar` was created with the following command:
+
+```bash
+TEST_VUS=4 k6 archive --include-system-env-vars test.js
+```
+
+ConfigMap `env-test` contains `archive.tar`. TestRun definition:
+
+```yaml
+apiVersion: k6.io/v1alpha1
+kind: TestRun
+metadata:
+  name: k6-sample
+spec:
+  parallelism: 2
+  script:
+    configMap:
+      name: "env-test"
+      file: "archive.tar"
+  runner:
+    env:
+      - name: TEST_VUS
+        value: "42"
+```
+
+In this case, there will be 4 VUs in total, split between 2 runners, and at the same time `TEST_VUS` env variable inside the script will be equal to 42.
+
+## `ConfigMap` has `archive.tar` without system env vars
+
+`archive.tar` was created with the following command:
+
+```bash
+TEST_VUS=4 k6 archive test.js
+```
+
+ConfigMap `env-test` and TestRun `k6-sample` are as in previous case. Then there will be 10000 VUs in total, split between 2 runners. And `TEST_VUS` inside the script will be 42 again.
+
+# Conclusion
+
+This is not fully k6-operator defined behaviour: the operator only passes the env vars to the pods. But if one uses `k6 archive` to create a script, the VUs will be defined at that step. This difference between configuration for `k6 archive` and `k6 run` is described in the docs [here](https://grafana.com/docs/k6/latest/misc/archive/#contents-of-an-archive-file) and [here](https://grafana.com/docs/k6/latest/using-k6/environment-variables/).

docs/troublehooting.md

@@ -98,7 +98,7 @@ Status:
 
 If `Stage` is equal to `error` then it definitely makes sense to check the logs of k6-operator.
 
-Conditions can be used as a source of info as well, but it is a more advanced troubleshooting option that should be used if previous suggestions are insufficient.Note, that conditions that start with `Cloud` prefix matter only in the setting of k6 Cloud test runs, i.e. cloud output and PLZ test runs.
+Conditions can be used as a source of info as well, but it is a more advanced troubleshooting option that should be used if previous suggestions are insufficient. Note, that conditions that start with `Cloud` prefix matter only in the setting of k6 Cloud test runs, i.e. cloud output and PLZ test runs.
 
 ### `PrivateLoadZone` deployment
 
@@ -119,7 +119,7 @@ Each time a user runs a test in a PLZ, for example with `k6 cloud script.js`, th
 
 ### Where are my env vars...
 
-TODO
+Some tricky cases with environment variables are described in [this doc](./env-vars.md).
 
 ### Tags are not working?!