nixos/modules/services/continuous-integration/hercules-ci-agent/settings.nix

   1 # Not a module
   2 { pkgs, lib }:
   3 let
   4   inherit (lib)
   5     types
   6     literalExpression
   7     mkOption
   8     ;
   9
  10   format = pkgs.formats.toml { };
  11
  12   settingsModule =
  13     {
  14       config,
  15       packageOption,
  16       pkgs,
  17       ...
  18     }:
  19     {
  20       freeformType = format.type;
  21       options = {
  22         apiBaseUrl = mkOption {
  23           description = ''
  24             API base URL that the agent will connect to.
  25
  26             When using Hercules CI Enterprise, set this to the URL where your
  27             Hercules CI server is reachable.
  28           '';
  29           type = types.str;
  30           default = "https://hercules-ci.com";
  31         };
  32         baseDirectory = mkOption {
  33           type = types.path;
  34           default = "/var/lib/hercules-ci-agent";
  35           description = ''
  36             State directory (secrets, work directory, etc) for agent
  37           '';
  38         };
  39         concurrentTasks = mkOption {
  40           description = ''
  41             Number of tasks to perform simultaneously.
  42
  43             A task is a single derivation build, an evaluation or an effect run.
  44             At minimum, you need 2 concurrent tasks for `x86_64-linux`
  45             in your cluster, to allow for import from derivation.
  46
  47             `concurrentTasks` can be around the CPU core count or lower if memory is
  48             the bottleneck.
  49
  50             The optimal value depends on the resource consumption characteristics of your workload,
  51             including memory usage and in-task parallelism. This is typically determined empirically.
  52
  53             When scaling, it is generally better to have a double-size machine than two machines,
  54             because each split of resources causes inefficiencies; particularly with regards
  55             to build latency because of extra downloads.
  56           '';
  57           type = types.either types.ints.positive (types.enum [ "auto" ]);
  58           default = "auto";
  59           defaultText = lib.literalMD ''
  60             `"auto"`, meaning equal to the number of CPU cores.
  61           '';
  62         };
  63         labels = mkOption {
  64           description = ''
  65             A key-value map of user data.
  66
  67             This data will be available to organization members in the dashboard and API.
  68
  69             The values can be of any TOML type that corresponds to a JSON type, but arrays
  70             can not contain tables/objects due to limitations of the TOML library. Values
  71             involving arrays of non-primitive types may not be representable currently.
  72           '';
  73           type = format.type;
  74           defaultText = literalExpression ''
  75             {
  76               agent.source = "..."; # One of "nixpkgs", "flake", "override"
  77               lib.version = "...";
  78               pkgs.version = "...";
  79             }
  80           '';
  81         };
  82         workDirectory = mkOption {
  83           description = ''
  84             The directory in which temporary subdirectories are created for task state. This includes sources for Nix evaluation.
  85           '';
  86           type = types.path;
  87           default = config.baseDirectory + "/work";
  88           defaultText = literalExpression ''baseDirectory + "/work"'';
  89         };
  90         staticSecretsDirectory = mkOption {
  91           description = ''
  92             This is the default directory to look for statically configured secrets like `cluster-join-token.key`.
  93
  94             See also `clusterJoinTokenPath` and `binaryCachesPath` for fine-grained configuration.
  95           '';
  96           type = types.path;
  97           default = config.baseDirectory + "/secrets";
  98           defaultText = literalExpression ''baseDirectory + "/secrets"'';
  99         };
 100         clusterJoinTokenPath = mkOption {
 101           description = ''
 102             Location of the cluster-join-token.key file.
 103
 104             You can retrieve the contents of the file when creating a new agent via
 105             <https://hercules-ci.com/dashboard>.
 106
 107             As this value is confidential, it should not be in the store, but
 108             installed using other means, such as agenix, NixOps
 109             `deployment.keys`, or manual installation.
 110
 111             The contents of the file are used for authentication between the agent and the API.
 112           '';
 113           type = types.path;
 114           default = config.staticSecretsDirectory + "/cluster-join-token.key";
 115           defaultText = literalExpression ''staticSecretsDirectory + "/cluster-join-token.key"'';
 116         };
 117         binaryCachesPath = mkOption {
 118           description = ''
 119             Path to a JSON file containing binary cache secret keys.
 120
 121             As these values are confidential, they should not be in the store, but
 122             copied over using other means, such as agenix, NixOps
 123             `deployment.keys`, or manual installation.
 124
 125             The format is described on <https://docs.hercules-ci.com/hercules-ci-agent/binary-caches-json/>.
 126           '';
 127           type = types.path;
 128           default = config.staticSecretsDirectory + "/binary-caches.json";
 129           defaultText = literalExpression ''staticSecretsDirectory + "/binary-caches.json"'';
 130         };
 131         secretsJsonPath = mkOption {
 132           description = ''
 133             Path to a JSON file containing secrets for effects.
 134
 135             As these values are confidential, they should not be in the store, but
 136             copied over using other means, such as agenix, NixOps
 137             `deployment.keys`, or manual installation.
 138
 139             The format is described on <https://docs.hercules-ci.com/hercules-ci-agent/secrets-json/>.
 140           '';
 141           type = types.path;
 142           default = config.staticSecretsDirectory + "/secrets.json";
 143           defaultText = literalExpression ''staticSecretsDirectory + "/secrets.json"'';
 144         };
 145       };
 146       config = {
 147         labels = {
 148           agent.source =
 149             if packageOption.highestPrio == (lib.modules.mkOptionDefault { }).priority then
 150               "nixpkgs"
 151             else
 152               lib.mkOptionDefault "override";
 153           pkgs.version = pkgs.lib.version;
 154           lib.version = lib.version;
 155         };
 156       };
 157     };
 158 in
 159 {
 160   inherit format settingsModule;
 161 }