terraform: document special_args and nixos-vars.json

terraform/all-in-one.md

@@ -33,6 +33,17 @@ module "deploy" {
     # script is below
     script = "${path.module}/decrypt-zfs-key.sh"
   }]
+  # Optional, arguments passed to special_args here will be available from a NixOS module in this example the `terraform` argument:
+  # { terraform, ... }: {
+  #    networking.interfaces.enp0s3.ipv4.addresses = [{ address = terraform.ip;  prefixLength = 24; }];
+  # }
+  # Note that this will means that your NixOS configuration will always depend on terraform!
+  # Skip to `Pass data persistently to the NixOS` for an alternative approach
+  #special_args = {
+  #  terraform = {
+  #    ip = "192.0.2.0"
+  #  }
+  #}
 }
 ```
 
@@ -80,6 +91,87 @@ sops --extract '["zfs-key"]' --decrypt "$SCRIPT_DIR/secrets.yaml"
 - [nixos-wiki setup](https://github.com/NixOS/nixos-wiki-infra/blob/main/terraform/nixos-wiki/main.tf)
   for hetzner-cloud
 
+## Pass data persistently to the NixOS
+
+This guide outlines how to pass data from Terraform to NixOS by generating a
+file during Terraform execution and including it in your NixOS configuration.
+This approach works well if your Terraform and NixOS configurations are stored
+in the same Git repository.
+
+### Why Use This Method?
+
+This method provides a straightforward way to transfer values from Terraform to
+NixOS without relying on special_args.
+
+- **Advantages**:
+  - You can continue to use nix build or nixos-rebuild to evaluate your
+    configuration without interruption. Simplifies configuration management by
+    centralizing state in a single repository.
+- **Disadvantages**:
+  - Deploying new machines requires tracking additional state. Every time
+    Terraform updates the JSON file, you’ll need to commit these changes to your
+    repository.
+
+### Implementation
+
+Add the following snippet to your Terraform configuration to create and manage a
+JSON file containing the necessary variables for NixOS. This file will be
+automatically added to your Git repository, ensuring the data persists.
+
+Assuming you have your terraform and nixos configuration in the same git
+repository. You can use the following snippet to `git add` a file generated by
+`terraform` during execution to pass data from terraform to NixOS. These changes
+should be committed afterwards. This is an alternative over using
+`special_args`. Advantage: you can still use nix build or nixos-rebuild on your
+flake to evaluate your configuration. Disadvantage: Deploying new machines also
+means you need to track additional state and make additional commits whenever
+terraform updates the json file.
+
+```hcl
+locals {
+  nixos_vars_file = "nixos-vars.json" # Path to the JSON file containing NixOS variables
+  nixos_vars = {
+    ip = "192.0.2.0" # Replace with actual variables
+  }
+}
+resource "local_file" "nixos_vars" {
+  content         = jsonencode(local.nixos_vars) # Converts variables to JSON
+  filename        = local.nixos_vars_file        # Specifies the output file path
+  file_permission = "600"                        
+
+  # Automatically adds the generated file to Git
+  provisioner "local-exec" {
+    interpreter = ["bash", "-c"]
+    command     = "git add -f '${local.nixos_vars_file}'"
+  }
+}
+```
+
+After applying the Terraform changes, ensure you commit the updated
+`nixos-vars.json` file to your Git repository:
+
+```bash
+git commit -m "Update NixOS variables from Terraform"
+```
+
+You can import this json file into your configuration like this:
+
+```nix
+let
+  nixosVars = builtins.fromJSON (builtins.readFile ./nixos-vars.json);
+in
+{
+  # Example usage of imported variables
+  networking.hostName = "example-machine";
+  networking.interfaces.eth0.ipv4.addresses = [
+    {
+      address = nixosVars.ip;  # Use the IP from nixos-vars.json
+      prefixLength = 24;
+    }
+  ];
+}
+```
+
 <!-- BEGIN_TF_DOCS -->
 
 ## Requirements