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 =
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 };
158in
159{
160 inherit format settingsModule;
161}