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