docs(ops/terraform/deploy-nixos): document inputs and outputs r/7760

This documents the input and output format, and also removes some
references to Terraform and evaluating NixOS system configurations.

It can be used to evaluate anything.

Change-Id: I8492cc3e386f89b299469c78e586644ee82a708f
Reviewed-on: https://cl.tvl.fyi/c/depot/+/11213
Reviewed-by: tazjin <tazjin@tvl.su>
Autosubmit: flokli <flokli@flokli.de>
Tested-by: BuildkiteCI

3 files changed, 35 insertions, 22 deletions

diff --git a/ops/terraform/deploy-nixos/main.tf b/ops/terraform/deploy-nixos/main.tf
index 00023fba69b2..50278b248ed1 100644
--- a/ops/terraform/deploy-nixos/main.tf
+++ b/ops/terraform/deploy-nixos/main.tf
@@ -53,7 +53,7 @@ variable "triggers" {
 
 # Fetch the derivation hash for the NixOS system.
 data "external" "nixos_system" {
-  program = ["${path.module}/nixos-eval.sh"]
+  program = ["${path.module}/nix-eval.sh"]
 
   query = {
     attrpath   = var.attrpath
diff --git a/ops/terraform/deploy-nixos/nix-eval.sh b/ops/terraform/deploy-nixos/nix-eval.sh
new file mode 100755
index 000000000000..2591da28ae0f
--- /dev/null
+++ b/ops/terraform/deploy-nixos/nix-eval.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+# SPDX-FileCopyrightText: 2023 The TVL Authors
+#
+# SPDX-License-Identifier: MIT
+set -ueo pipefail
+
+# Evaluates a Nix expression.
+#
+# Receives input parameters as JSON from stdin.
+# It expects a dict with the following keys:
+#
+#  - `attrpath`: the attribute.path pointing to the expression to instantiate.
+#    Required.
+#  - `entrypoint`: the path to the Nix file to invoke.
+#    Optional. If omitted, will shell out to git to determine the repo root,
+#    and Nix will use `default.nix` in there.
+#  - `argstr`: A map containing string keys and values
+#    which are passed to Nix as `--argstr $key $value`
+#    command line args. Optional.
+#
+# jq's @sh format takes care of escaping.
+eval "$(jq -r '@sh "attrpath=\(.attrpath) && entrypoint=\(.entrypoint) && argstr=\((.argstr // {}) | to_entries | map ("--argstr", .key, .value) | join(" "))"')"
+
+# Evaluate the expression.
+[[ -z "$entrypoint" ]] && entrypoint=$(git rev-parse --show-toplevel)
+# shellcheck disable=SC2086,SC2154
+drv=$(nix-instantiate -A "${attrpath}" "${entrypoint}" ${argstr})
+
+# Return a JSON back to stdout.
+# It contains the following keys:
+#
+# - `drv`: the store path of the Derivation that has been instantiated.
+jq -n --arg drv "$drv" '{"drv":$drv}'
diff --git a/ops/terraform/deploy-nixos/nixos-eval.sh b/ops/terraform/deploy-nixos/nixos-eval.sh
deleted file mode 100755
index f206fe7f6875..000000000000
--- a/ops/terraform/deploy-nixos/nixos-eval.sh
+++ /dev/null
@@ -1,21 +0,0 @@
-#!/usr/bin/env bash
-
-# SPDX-FileCopyrightText: 2023 The TVL Authors
-#
-# SPDX-License-Identifier: MIT
-
-#
-# Builds a NixOS system configuration at the given attribute path.
-set -ueo pipefail
-
-# Load input variables from Terraform. jq's @sh format takes care of
-# escaping.
-eval "$(jq -r '@sh "attrpath=\(.attrpath) && entrypoint=\(.entrypoint) && argstr=\((.argstr // {}) | to_entries | map ("--argstr", .key, .value) | join(" "))"')"
-
-# Evaluate the system derivation.
-[[ -z "$entrypoint" ]] && entrypoint=$(git rev-parse --show-toplevel)
-# shellcheck disable=SC2086,SC2154
-system_drv=$(nix-instantiate -A "${attrpath}" "${entrypoint}" ${argstr})
-
-# Return system derivation back to Terraform.
-jq -n --arg drv "$system_drv" '{"drv":$drv}'