add tf

Reviewed-on: fricklerhandwerk/Fediversity#6
Reviewed-by: Valentin Gagarin <valentin.gagarin@tweag.io>

.forgejo/workflows/ci.yaml

@@ -56,3 +56,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: nix build .#checks.x86_64-linux.deployment-panel -L
+
+  check-deployment-model:
+    runs-on: native
+    steps:
+      - uses: actions/checkout@v4
+      - run: nix build .#checks.x86_64-linux.deployment-model -L

default.nix

@@ -11,7 +11,8 @@ let
     ;
   inherit (pkgs) lib;
   inherit (import sources.flake-inputs) import-flake;
-  inherit ((import-flake { src = ./.; }).inputs) nixops4;
+  inputs = (import-flake { src = ./.; }).inputs;
+  inherit (inputs) nixops4;
   panel = import ./panel { inherit sources system; };
   pre-commit-check =
     (import "${git-hooks}/nix" {
@@ -78,6 +79,7 @@ in
   # re-export inputs so they can be overridden granularly
   # (they can't be accessed from the outside any other way)
   inherit
+    inputs
     sources
     system
     pkgs

deployment/check/common/deployerNode.nix

@@ -54,11 +54,8 @@ in
 
     system.extraDependencies =
       [
-        inputs.nixops4
-        inputs.nixops4-nixos
-        inputs.nixpkgs
+        sources.nixpkgs
 
-        sources.flake-parts
         sources.flake-inputs
         sources.git-hooks
 

deployment/check/data-model/common-nixosTest.nix

@@ -0,0 +1,168 @@
+{
+  inputs,
+  lib,
+  config,
+  hostPkgs,
+  sources,
+  ...
+}:
+
+let
+  inherit (builtins)
+    concatStringsSep
+    toJSON
+    ;
+  inherit (lib)
+    types
+    fileset
+    mkOption
+    genAttrs
+    attrNames
+    optionalString
+    ;
+  inherit (hostPkgs)
+    writeText
+    ;
+
+  forConcat = xs: f: concatStringsSep "\n" (map f xs);
+
+in
+{
+  _class = "nixosTest";
+
+  imports = [
+    ../common/sharedOptions.nix
+  ];
+
+  options = {
+    ## FIXME: I wish I could just use `testScript` but with something like
+    ## `mkOrder` to put this module's string before something else.
+    extraTestScript = mkOption { };
+
+    sourceFileset = mkOption {
+      ## REVIEW: Upstream to nixpkgs?
+      type = types.mkOptionType {
+        name = "fileset";
+        description = "fileset";
+        descriptionClass = "noun";
+        check = (x: (builtins.tryEval (fileset.unions [ x ])).success);
+        merge = (_: defs: fileset.unions (map (x: x.value) defs));
+      };
+      description = ''
+        A fileset that will be copied to the deployer node in the current
+        working directory. This should contain all the files that are
+        necessary to run that particular test, such as the NixOS
+        modules necessary to evaluate a deployment.
+      '';
+    };
+  };
+
+  config = {
+    sourceFileset = fileset.unions [
+      ../../../mkFlake.nix
+      ../../../flake.lock
+      ../../../npins
+      ../../data-model.nix
+      ../../function.nix
+
+      ../common/sharedOptions.nix
+      ../common/targetNode.nix
+      ../common/targetResource.nix
+    ];
+
+    acmeNodeIP = config.nodes.acme.networking.primaryIPAddress;
+
+    nodes =
+      {
+        deployer = {
+          imports = [ ../common/deployerNode.nix ];
+          _module.args = { inherit inputs sources; };
+          enableAcme = config.enableAcme;
+          acmeNodeIP = config.nodes.acme.networking.primaryIPAddress;
+        };
+      }
+
+      //
+
+        (
+          if config.enableAcme then
+            {
+              acme = {
+                ## FIXME: This makes `nodes.acme` into a local resolver. Maybe this will
+                ## break things once we play with DNS?
+                imports = [ "${inputs.nixpkgs}/nixos/tests/common/acme/server" ];
+                ## We aren't testing ACME - we just want certificates.
+                systemd.services.pebble.environment.PEBBLE_VA_ALWAYS_VALID = "1";
+              };
+            }
+          else
+            { }
+        )
+
+      //
+
+        genAttrs config.targetMachines (_: {
+          imports = [ ../common/targetNode.nix ];
+          _module.args = { inherit inputs sources; };
+          enableAcme = config.enableAcme;
+          acmeNodeIP = if config.enableAcme then config.nodes.acme.networking.primaryIPAddress else null;
+        });
+
+    testScript = ''
+      ${forConcat (attrNames config.nodes) (n: ''
+        ${n}.start()
+      '')}
+
+      ${forConcat (attrNames config.nodes) (n: ''
+        ${n}.wait_for_unit("multi-user.target")
+      '')}
+
+      ## A subset of the repository that is necessary for this test. It will be
+      ## copied inside the test. The smaller this set, the faster our CI, because we
+      ## won't need to re-run when things change outside of it.
+      with subtest("Unpacking"):
+        deployer.succeed("cp -r --no-preserve=mode ${
+          fileset.toSource {
+            root = ../../..;
+            fileset = config.sourceFileset;
+          }
+        }/* .")
+
+      with subtest("Configure the network"):
+        ${forConcat config.targetMachines (
+          tm:
+          let
+            targetNetworkJSON = writeText "target-network.json" (
+              toJSON config.nodes.${tm}.system.build.networkConfig
+            );
+          in
+          ''
+            deployer.copy_from_host("${targetNetworkJSON}", "${config.pathFromRoot}/${tm}-network.json")
+          ''
+        )}
+
+      with subtest("Configure the deployer key"):
+        deployer.succeed("""mkdir -p ~/.ssh && ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa""")
+        deployer_key = deployer.succeed("cat ~/.ssh/id_rsa.pub").strip()
+        ${forConcat config.targetMachines (tm: ''
+          ${tm}.succeed(f"mkdir -p /root/.ssh && echo '{deployer_key}' >> /root/.ssh/authorized_keys")
+        '')}
+
+      with subtest("Configure the target host key"):
+        ${forConcat config.targetMachines (tm: ''
+          host_key = ${tm}.succeed("ssh-keyscan ${tm} | grep -v '^#' | cut -f 2- -d ' ' | head -n 1")
+          deployer.succeed(f"echo '{host_key}' > ${config.pathFromRoot}/${tm}_host_key.pub")
+        '')}
+
+      # with subtest("Override the flake and its lock"):
+      #   deployer.succeed("cp ${config.pathFromRoot}/flake-under-test.nix flake.nix")
+
+      ${optionalString config.enableAcme ''
+        with subtest("Set up handmade DNS"):
+          deployer.succeed("echo '${config.nodes.acme.networking.primaryIPAddress}' > ${config.pathFromRoot}/acme_server_ip")
+      ''}
+
+      ${config.extraTestScript}
+    '';
+  };
+}

deployment/check/data-model/constants.nix

@@ -0,0 +1,8 @@
+{
+  targetMachines = [
+    "hello"
+    "cowsay"
+  ];
+  pathToRoot = ../../..;
+  pathFromRoot = ./.;
+}

deployment/check/data-model/default.nix

@@ -0,0 +1,16 @@
+{
+  runNixOSTest,
+  inputs,
+  sources,
+}:
+
+runNixOSTest {
+  imports = [
+    ../../data-model.nix
+    ../../function.nix
+    ./common-nixosTest.nix
+    ./nixosTest.nix
+  ];
+  _module.args = { inherit inputs sources; };
+  inherit (import ./constants.nix) targetMachines pathToRoot pathFromRoot;
+}

deployment/check/data-model/deployment.nix

@@ -0,0 +1,39 @@
+{
+  inputs,
+  # sources,
+  lib,
+  ...
+}:
+
+let
+  # inherit (import ./constants.nix) targetMachines pathToRoot pathFromRoot;
+  eval =
+    module:
+    (lib.evalModules {
+      specialArgs = {
+        inherit inputs;
+      };
+      modules = [
+        module
+        ../../data-model.nix
+      ];
+    }).config;
+  fediversity = eval (
+    { ... }:
+    {
+      config = {
+        environments.single-nixos-vm =
+          { ... }:
+          {
+            implementation = requests: {
+              input = requests;
+              output = { };
+            };
+          };
+      };
+    }
+  );
+in
+fediversity.environments.single-nixos-vm.deployment {
+  enable = true;
+}

deployment/check/data-model/nixosTest.nix

@@ -0,0 +1,62 @@
+{
+  lib,
+  ...
+}:
+
+{
+  _class = "nixosTest";
+
+  name = "deployment-model";
+
+  sourceFileset = lib.fileset.unions [
+    ../../data-model.nix
+    ../../function.nix
+    ./constants.nix
+    ./deployment.nix
+  ];
+
+  nodes.deployer =
+    { pkgs, ... }:
+    {
+      # FIXME: sad times
+      system.extraDependencies = with pkgs; [
+        jq
+        jq.inputDerivation
+      ];
+
+      system.extraDependenciesFromModule =
+        { pkgs, ... }:
+        {
+          environment.systemPackages = with pkgs; [
+            hello
+            cowsay
+          ];
+        };
+    };
+
+  extraTestScript = ''
+    with subtest("Check the status before deployment"):
+      hello.fail("hello 1>&2")
+      cowsay.fail("cowsay 1>&2")
+
+    # SETTINGS.BIN_PATH
+    # CONFIG
+    env = {
+        "PATH": settings.bin_path,
+        # "TF_LOG": "info",
+    } | {
+        # pass in form info to our deployment
+        # FIXME: ensure sensitive info is protected
+        f"TF_VAR_{k}": v if isinstance(v, str) else json.dumps(v) for k, v in json.loads(config.model_dump_json()).items()
+    }
+
+    # USE ENV
+    # SETTINGS.REPO_DIR
+    with subtest("Run the deployment"):
+      deployer.succeed("cd ${settings.repo_dir}/infra/operator && tofu apply --auto-approve -lock=false -parallelism=1")
+
+    with subtest("Check the deployment"):
+      hello.succeed("hello 1>&2")
+      cowsay.succeed("cowsay hi 1>&2")
+  '';
+}

deployment/data-model-test.nix

@@ -1,7 +1,7 @@
 let
   inherit (import ../default.nix { }) pkgs inputs;
   inherit (pkgs) lib;
-  inherit (lib) mkOption;
+  inherit (lib) mkOption types;
   eval =
     module:
     (lib.evalModules {
@@ -13,17 +13,82 @@ let
         ./data-model.nix
       ];
     }).config;
+  inherit (inputs.nixops4.lib) mkDeployment;
 in
 {
   _class = "nix-unit";
 
   test-eval = {
+    /**
+      This tests a very simple arrangement that features all ingredients of the Fediversity business logic:
+      application, resource, environment, deployment; and wires it all up in one end-to-end exercise.
+      - The dummy resource is a login shell made available for some user.
+      - The dummy application is `hello` that requires a shell to be deployed.
+      - The dummy environment is a single NixOS VM that hosts one login shell, for the operator.
+      - The dummy configuration enables the `hello` application.
+      This will produce a NixOps4 deployment for a NixOS VM with a login shell for the operator and `hello` available.
+    */
     expr =
       let
         fediversity = eval (
-          { config, ... }:
+          { config, options, ... }:
           {
             config = {
+              resources.login-shell = {
+                description = "The operator needs to be able to log into the shell";
+                request =
+                  { ... }:
+                  {
+                    _class = "fediversity-resource-request";
+                    options = {
+                      wheel = mkOption {
+                        description = "Whether the login user needs root permissions";
+                        type = types.bool;
+                        default = false;
+                      };
+                      packages = mkOption {
+                        description = "Packages that need to be available in the user environment";
+                        type = with types; attrsOf package;
+                      };
+                    };
+                  };
+                policy =
+                  { config, ... }:
+                  {
+                    _class = "fediversity-resource-policy";
+                    options = {
+                      username = mkOption {
+                        description = "Username for the operator";
+                        type = types.str; # TODO: use the proper constraints from NixOS
+                      };
+                      wheel = mkOption {
+                        description = "Whether to allow login with root permissions";
+                        type = types.bool;
+                        default = false;
+                      };
+                    };
+                    config = {
+                      resource-type = types.raw; # TODO: splice out the user type from NixOS
+                      apply =
+                        requests:
+                        let
+                          # Filter out requests that need wheel if policy doesn't allow it
+                          validRequests = lib.filterAttrs (
+                            _name: req: !req.login-shell.wheel || config.wheel
+                          ) requests.resources;
+                        in
+                        lib.optionalAttrs (validRequests != { }) {
+                          ${config.username} = {
+                            isNormalUser = true;
+                            packages =
+                              with lib;
+                              attrValues (concatMapAttrs (_name: request: request.login-shell.packages) validRequests);
+                            extraGroups = lib.optional config.wheel "wheel";
+                          };
+                        };
+                    };
+                  };
+              };
               applications.hello =
                 { ... }:
                 {
@@ -31,15 +96,42 @@ in
                   module =
                     { ... }:
                     {
-                      options = {
-                        enable = lib.mkEnableOption "Hello in the shell";
+                      options.enable = lib.mkEnableOption "Hello in the shell";
+                    };
+                  implementation = cfg: {
+                    input = cfg;
+                    output = lib.optionalAttrs cfg.enable {
+                      resources.hello.login-shell.packages.hello = pkgs.hello;
+                    };
+                  };
+                };
+              environments.single-nixos-vm =
+                { config, ... }:
+                {
+                  resources.operator-environment.login-shell.username = "operator";
+                  implementation = requests: {
+                    input = requests;
+                    output.nixops4 =
+                      { providers, ... }:
+                      {
+                        providers = {
+                          inherit (inputs.nixops4.modules.nixops4Provider) local;
+                        };
+                        resources.the-machine = {
+                          type = providers.local.exec;
+                          imports = [
+                            inputs.nixops4-nixos.modules.nixops4Resource.nixos
+                          ];
+                          nixos.module =
+                            { ... }:
+                            {
+                              users.users = config.resources.shell.login-shell.apply (
+                                lib.filterAttrs (_name: value: value ? login-shell) requests
+                              );
+                            };
+                        };
                       };
-                    };
-                  implementation =
-                    cfg:
-                    lib.optionalAttrs cfg.enable {
-                      dummy.login-shell.packages.hello = pkgs.hello;
-                    };
+                  };
                 };
             };
             options = {
@@ -51,20 +143,64 @@ in
                   applications.hello.enable = true;
                 };
               };
+              example-deployment = mkOption {
+                type = options.deployments.nestedType;
+                readOnly = true;
+                default = config.environments.single-nixos-vm.deployment config.example-configuration;
+              };
             };
           }
         );
+        resources = fediversity.applications.hello.resources fediversity.example-configuration.applications.hello;
+        hello-shell = resources.resources.hello.login-shell;
+        environment = fediversity.environments.single-nixos-vm.resources.operator-environment.login-shell;
+        result = mkDeployment {
+          modules = [
+            (fediversity.environments.single-nixos-vm.deployment fediversity.example-configuration)
+          ];
+        };
+
       in
       {
-        inherit (fediversity)
-          example-configuration
-          ;
+        number-of-resources = with lib; length (attrNames fediversity.resources);
+        inherit (fediversity) example-configuration;
+        hello-package-exists = hello-shell.packages ? hello;
+        wheel-required = hello-shell.wheel;
+        wheel-allowed = environment.wheel;
+        operator-shell =
+          let
+            operator = (environment.apply resources).operator;
+          in
+          {
+            inherit (operator) isNormalUser;
+            packages = map (p: "${p.pname}") operator.packages;
+            extraGroups = operator.extraGroups;
+          };
+        deployment = {
+          inherit (result) _type;
+          deploymentFunction = lib.isFunction result.deploymentFunction;
+          getProviders = lib.isFunction result.getProviders;
+        };
       };
     expected = {
+      number-of-resources = 1;
       example-configuration = {
         enable = true;
         applications.hello.enable = true;
       };
+      hello-package-exists = true;
+      wheel-required = false;
+      wheel-allowed = false;
+      operator-shell = {
+        isNormalUser = true;
+        packages = [ "hello" ];
+        extraGroups = [ ];
+      };
+      deployment = {
+        _type = "nixops4Deployment";
+        deploymentFunction = true;
+        getProviders = true;
+      };
     };
   };
 }

deployment/data-model.nix

@@ -15,19 +15,66 @@ let
     ;
 
   functionType = import ./function.nix;
-  application-resources = {
+  application-resources = submodule {
     options.resources = mkOption {
       # TODO: maybe transpose, and group the resources by type instead
       type = attrsOf (
-        attrTag (lib.mapAttrs (_name: resource: mkOption { type = resource.request; }) config.resources)
+        attrTag (
+          lib.mapAttrs (_name: resource: mkOption { type = submodule resource.request; }) config.resources
+        )
       );
     };
   };
+  deployment = attrTag {
+    tf-ssh = mkOption {
+      description = "A Terraform deployment by SSH to update a single existing NixOS host";
+      type = types.attrset;
+    };
+  };
 in
 {
-  _class = "nixops4Deployment";
-
   options = {
+    resources = mkOption {
+      description = "Collection of deployment resources that can be required by applications and policed by hosting providers";
+      type = attrsOf (
+        submodule (
+          { ... }:
+          {
+            _class = "fediversity-resource";
+            options = {
+              description = mkOption {
+                description = "Description of the resource to help application module authors and hosting providers to work with it";
+                type = types.str;
+              };
+              request = mkOption {
+                description = "Options for declaring resource requirements by an application, a description of how the resource is consumed or accessed";
+                type = deferredModuleWith { staticModules = [ { _class = "fediversity-resource-request"; } ]; };
+              };
+              policy = mkOption {
+                description = "Options for configuring the resource policy for the hosting provider, a description of how the resource is made available";
+                type = deferredModuleWith {
+                  staticModules = [
+                    (policy: {
+                      _class = "fediversity-resource-policy";
+                      options.resource-type = mkOption {
+                        description = "The type of resource this policy configures";
+                        type = types.optionType;
+                      };
+                      # TODO(@fricklerhandwerk): we may want to make the function type explict here: `request -> resource-type`
+                      # and then also rename this to be consistent with the application's resource mapping
+                      options.apply = mkOption {
+                        description = "Apply the policy to a request";
+                        type = functionTo policy.config.resource-type;
+                      };
+                    })
+                  ];
+                };
+              };
+            };
+          }
+        )
+      );
+    };
     applications = mkOption {
       description = "Collection of Fediversity applications";
       type = attrsOf (
@@ -52,12 +99,13 @@ in
               readOnly = true;
               default = input: (application.config.implementation input).output;
             };
+            # TODO(@fricklerhandwerk): this needs a better name, it's just the type
             config-mapping = mkOption {
               description = "Function type for the mapping from application configuration to required resources";
               type = submodule functionType;
               readOnly = true;
               default = {
-                input-type = application.config.module;
+                input-type = submodule application.config.module;
                 output-type = application-resources;
               };
             };
@@ -65,6 +113,60 @@ in
         })
       );
     };
+    environments = mkOption {
+      description = "Run-time environments for Fediversity applications to be deployed to";
+      type = attrsOf (
+        submodule (environment: {
+          _class = "fediversity-environment";
+          options = {
+            resources = mkOption {
+              description = ''
+                Resources made available by the hosting provider, and their policies.
+
+                Setting this is optional, but provides a place to declare that information for programmatic use in the resource mapping.
+              '';
+              # TODO: maybe transpose, and group the resources by type instead
+              type = attrsOf (
+                attrTag (
+                  lib.mapAttrs (_name: resource: mkOption { type = submodule resource.policy; }) config.resources
+                )
+              );
+            };
+            implementation = mkOption {
+              description = "Mapping of resources required by applications to available resources; the result can be deployed";
+              type = environment.config.resource-mapping.function-type;
+            };
+            resource-mapping = mkOption {
+              description = "Function type for the mapping from resources to a deployment";
+              type = submodule functionType;
+              readOnly = true;
+              default = {
+                input-type = application-resources;
+                output-type = deployment;
+              };
+            };
+            # TODO(@fricklerhandwerk): maybe this should be a separate thing such as `fediversity-setup`,
+            # which makes explicit which applications and environments are available.
+            # then the deployments can simply be the result of the function application baked into this module.
+            deployment = mkOption {
+              description = "Generate a deployment from a configuration, by applying an environment's resource policies to the applications' resource mappings";
+              type = functionTo (environment.config.resource-mapping.output-type);
+              readOnly = true;
+              default =
+                cfg:
+                # TODO: check cfg.enable.true
+                let
+                  required-resources = lib.mapAttrs (
+                    name: application-settings: config.applications.${name}.resources application-settings
+                  ) cfg.applications;
+                in
+                (environment.config.implementation required-resources).output;
+
+            };
+          };
+        })
+      );
+    };
     configuration = mkOption {
       description = "Configuration type declaring options to be set by operators";
       type = optionType;

deployment/flake-part.nix

@@ -21,6 +21,11 @@
           inherit (pkgs.testers) runNixOSTest;
           inherit inputs sources;
         };
+
+        deployment-model = import ./check/data-model {
+          inherit (pkgs.testers) runNixOSTest;
+          inherit inputs sources;
+        };
       };
     };
 }

deployment/function.nix

@@ -5,7 +5,6 @@
 let
   inherit (lib) mkOption types;
   inherit (types)
-    deferredModule
     submodule
     functionTo
     optionType
@@ -14,10 +13,10 @@ in
 {
   options = {
     input-type = mkOption {
-      type = deferredModule;
+      type = optionType;
     };
     output-type = mkOption {
-      type = deferredModule;
+      type = optionType;
     };
     function-type = mkOption {
       type = optionType;
@@ -25,10 +24,10 @@ in
       default = functionTo (submodule {
         options = {
           input = mkOption {
-            type = submodule config.input-type;
+            type = config.input-type;
           };
           output = mkOption {
-            type = submodule config.output-type;
+            type = config.output-type;
           };
         };
       });

infra/dev/main.nix

@@ -0,0 +1,38 @@
+let
+  vm_domain = "abundos.eu";
+in
+{
+  module."nixos" =
+    builtins.mapAttrs
+      (service: hostname: {
+        source = "../sync-nix";
+        inherit vm_domain hostname;
+        config_tf = {
+          terraform = {
+            inherit hostname;
+            domain = vm_domain;
+          };
+        };
+        config_nix = ''
+          {
+            imports = [
+              # shared NixOS config
+              $${path.root}/../common/shared.nix
+              # FIXME: separate template options by service
+              $${path.root}/options.nix
+              # for service `forgejo` import `forgejo.nix`
+              $${path.root}/../../machines/dev/${hostname}/${service}.nix
+              # FIXME: get VM details from TF
+              $${path.root}/../../machines/dev/${hostname}
+            ];
+          }
+        '';
+      })
+      {
+        # wiki = "vm02187" # does not resolve
+        # forgejo = "vm02116" # does not resolve
+        # TODO: move these to a separate `host` dir
+        dns = "fedi200";
+        # fedipanel = "fedi201";
+      };
+}

infra/sync-nix/main.tf

@@ -0,0 +1,91 @@
+locals {
+  system = "x86_64-linux"
+  # dependency paths pre-calculated from npins
+  pins = jsondecode(file("${path.module}/.npins.json"))
+  # nix path: expose pins, use nixpkgs in flake commands (`nix run`)
+  nix_path = "${join(":", [for name, dir in local.pins : "${name}=${dir}"])}:flake=${local.pins["nixpkgs"]}:flake"
+}
+
+# hash of our code directory, used to trigger re-deploy
+# FIXME calculate separately to reduce false positives
+data "external" "hash" {
+  program = ["sh", "-c", "echo \"{\\\"hash\\\":\\\"$(nix-hash ..)\\\"}\""]
+}
+
+# TF resource to build and deploy NixOS instances.
+resource "terraform_data" "nixos" {
+
+  # trigger rebuild/deploy if (FIXME?) any potentially used config/code changed,
+  # preventing these (20+s, build being bottleneck) when nothing changed.
+  # terraform-nixos separates these to only deploy if instantiate changed,
+  # yet building even then - which may be not as bad using deploy on remote.
+  # having build/deploy one resource reflects wanting to prevent no-op rebuilds
+  # over preventing (with less false positives) no-op deployments,
+  # as i could not find a way to do prevent no-op rebuilds without merging them:
+  # - generic resources cannot have outputs, while we want info from the instantiation (unless built on host?).
+  # - `data` always runs, which is slow for deploy and especially build.
+  triggers_replace = [
+    data.external.hash.result,
+    var.hostname,
+    var.config_nix,
+    var.config_tf,
+  ]
+
+  provisioner "local-exec" {
+    # directory to run the script from. we use the TF project root dir,
+    # here as a path relative from where TF is run from,
+    # matching calling modules' expectations on config_nix locations.
+    # note that absolute paths can cause false positives in triggers,
+    # so are generally discouraged in TF.
+    working_dir = path.root
+    environment = {
+      # nix path used on build, lets us refer to e.g. nixpkgs like `<nixpkgs>`
+      NIX_PATH = local.nix_path
+    }
+    # TODO: refactor back to command="ignoreme" interpreter=concat([]) to protect sensitive data from error logs?
+    # TODO: build on target?
+    command = <<-EOF
+      set -euo pipefail
+
+      # INSTANTIATE
+      command=(
+        nix-instantiate
+        --expr
+        'import ./nixos.nix {
+          system = "${local.system}";
+          configuration =
+            ${var.config_nix} //
+            builtins.fromJSON "${replace(jsonencode(var.config_tf), "\"", "\\\"")}" //
+            {
+              nix.nixPath = [ "${local.nix_path}" ];
+            };
+        }'
+      )
+      # instantiate the config in /nix/store
+      "$${command[@]}" -A out_path
+      # get the other info
+      json="$("$${command[@]}" --eval --strict --json)"
+
+      # DEPLOY
+      declare substituters trusted_public_keys drv_path
+      # set our variables using the json object
+      eval "export $(echo $json | jaq -r 'to_entries | map("\(.key)=\(.value)") | @sh')"
+      host="root@${var.hostname}.${var.vm_domain}" # FIXME: #24
+      buildArgs=(
+        --option extra-binary-caches https://cache.nixos.org/
+        --option substituters $substituters
+        --option trusted-public-keys $trusted_public_keys
+      )
+      sshOpts=(
+        -o BatchMode=yes
+        -o StrictHostKeyChecking=no
+      )
+      # get the realized derivation to deploy
+      outPath=$(nix-store --realize "$drv_path" "$${buildArgs[@]}")
+      # deploy the config by nix-copy-closure
+      NIX_SSHOPTS="$${sshOpts[*]}" nix-copy-closure --to "$host" "$outPath" --gzip --use-substitutes
+      # switch the remote host to the config
+      ssh "$${sshOpts[@]}" "$host" "nix-env --profile /nix/var/nix/profiles/system --set $outPath; $outPath/bin/switch-to-configuration switch"
+    EOF
+  }
+}

infra/sync-nix/nixos.nix

@@ -0,0 +1,14 @@
+{
+  configuration,
+  system ? builtins.currentSystem,
+}:
+let
+  sources = import ../../npins;
+  os = import "${sources.nixpkgs}/nixos" { inherit system configuration; };
+in
+{
+  substituters = builtins.concatStringsSep " " os.config.nix.settings.substituters;
+  trusted_public_keys = builtins.concatStringsSep " " os.config.nix.settings.trusted-public-keys;
+  drv_path = os.config.system.build.toplevel.drvPath;
+  out_path = os.config.system.build.toplevel;
+}

infra/sync-nix/variables.nix

@@ -0,0 +1,27 @@
+# TODO: generate nix module from `variables.tf`
+# - TF -> JSON schema: https://melvinkoh.me/parsing-terraform-for-forms-clr4zq4tu000309juab3r1lf7
+#   - python313Packages.python-hcl2: hcl2tojson variables.tf
+# - JSON schema -> nix
+{ lib, ... }:
+let
+  inherit (lib) mkOption types;
+  inherit (types) string attrsOf any;
+in
+{
+  options = {
+    vm_domain = mkOption {
+      type = string;
+    };
+    hostname = mkOption {
+      type = string;
+    };
+    config_nix = mkOption {
+      type = string;
+      default = { };
+    };
+    config_tf = mkOption {
+      type = attrsOf any;
+      default = { };
+    };
+  };
+}

infra/sync-nix/variables.tf

@@ -0,0 +1,17 @@
+variable "vm_domain" {
+  type = string
+}
+
+variable "hostname" {
+  type = string
+}
+
+variable "config_nix" {
+  type = string
+  default = "{}"
+}
+
+variable "config_tf" {
+  type = map(any)
+  default = {}
+}