Update documentation WRT to recent $platform changes (#2531)

Co-authored-by: Thomas Anderson <127358482+zc-devs@users.noreply.github.com>

docs/docs/20-usage/30-matrix-workflows.md

@@ -120,7 +120,8 @@ matrix:
     - linux/amd64
     - linux/arm64
 
-platform: ${platform}
+labels:
+  platform: ${platform}
 
 steps:
   test:
@@ -136,3 +137,7 @@ steps:
     when:
       platform: linux/arm*
 ```
+
+:::note
+If you want to control the architecture of a pipeline on a Kubernetes runner, see [the nodeSelector documentation of the Kubernetes backend](../30-administration/22-backends/40-kubernetes.md#nodeSelector).
+:::

docs/docs/30-administration/22-backends/40-kubernetes.md

@@ -80,9 +80,32 @@ See the [kubernetes documentation](https://kubernetes.io/docs/concepts/security/
 
 ### nodeSelector
 
-Specify the label which is used to select the node where the job should be executed. Labels defined here will be appended to a list already containing "kubernetes.io/arch".
+Specifies the label which is used to select the node on which the job will be executed.
-By default the pod will use "kubernetes.io/arch" inferred from top-level "platform" setting which is deducted from the agents' environment variable CI_SYSTEM_PLATFORM. To overwrite this, you need to specify this label in the nodeSelector section.
+
-See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more information on using nodeSelector.
+Labels defined here will be appended to a list which already contains `"kubernetes.io/arch"`.
+By default `"kubernetes.io/arch"` is inferred from the agents' platform. One can override it by setting that label in the `nodeSelector` section of the `backend_options`.
+Without a manual overwrite, builds will be randomly assigned to the runners and inherit their respective architectures.
+
+To overwrite this, one needs to set the label in the `nodeSelector` section of the `backend_options`.
+A practical example for this is when running a matrix-build and delegating specific elements of the matrix to run on a specific architecture.
+In this case, one must define an arbitrary key in the matrix section of the respective matrix element:
+
+```yml
+matrix:
+  include:
+    - NAME: runner1
+      ARCH: arm64
+```
+
+And then overwrite the `nodeSelector` in the `backend_options` section of the step(s) using the name of the respective env var:
+
+```yml
+[...]
+    backend_options:
+      kubernetes:
+        nodeSelector:
+          kubernetes.io/arch: "${ARCH}"
+```
 
 ### tolerations