confctl 1.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 869735b23809f8bef14f7e1e39b57e7bcaf4a90a37c7e5f4c03064a526cc1c46
-  data.tar.gz: 1badf4f41f9183cbc5c716d436d89b3ccae96519e2f37bf0b67c4ffe7fde89e7
+  metadata.gz: 94823b33bdeb90ed8aa1a2aa835e8a3f48300c116ee951c3d41e8c433e9ea1ed
+  data.tar.gz: 7ec55e71a411a0844a687047d797c0324efeeb2b2f2fd1dd5efa3261ede6a184
 SHA512:
-  metadata.gz: 889dc492d0996711bff26a442532cb955dc5fcf5f25c281e25475b7a9e657f64270cc6c839e81b4a3880ab250c50e7a817c30bbfc6c8a37e0b5d7fb755bad212
-  data.tar.gz: b894f7b1720684ad93af743e8fc55f221876c7665d7302682f8354865fdc9c54f17acb990d088981d6638d908624e4687e412dda141eede57556f03bf7f741d7
+  metadata.gz: 83cf4e6ef92ec1cf76f2b260e689a45b52dc3653c35d82bdddabb3246e37b0ddb5d056ad60ebed5506e72612f235e7a283d9eecd29b1822482013ffa1562037a
+  data.tar.gz: aa12794664afe5a91595f91da89e8fe7d8e7205ad4428918bf0e0047ea2f1603244f3fb7aec458d0d0f2e5fdef21add41d431136b6872ec2ae26fe401258111e

data/.editorconfig

@@ -5,7 +5,7 @@ root = true
 charset = utf-8
 end_of_line = lf
 
-[*.{rb,erb,nix}]
+[*.{rb,erb,md,nix}]
 indent_size = 2
 indent_style = space
 trim_trailing_whitespace = true

data/.gitignore

@@ -5,4 +5,5 @@ man/*.html
 man/**/*.html
 man/man?/*.?
 html_doc
+.gems
 .yardoc

data/.rubocop.yml

@@ -1,6 +1,7 @@
 inherit_from: .rubocop_todo.yml
 
 AllCops:
+  TargetRubyVersion: 3.1.0
   NewCops: enable
   Exclude:
     - '*.rb'

data/CHANGELOG.md

@@ -1,2 +1,31 @@
-# Sat Feb 17 2023 -- version 1.0.0
+# Sun May 11 2025 -- version 2.1.0
+- Support for referring to generations by their offset
+- Resolved generations are printed on build/deploy/etc.
+- Automatically rollback faulty configurations
+- Interleave copying of carried machine generations
+- Add `confctl.programs.kexec-netboot`
+- Let the user retry dry activation in interactive mode
+- Fix listing, deletion and garbage collection of carried machines' generations
+- Read and display kernel version for each generation
+- Option to disable the garbage collection in `confctl generation rotate`
+- Shorten titles and entries in netboot menus
+
+# Sun Nov 17 2024 -- version 2.0.0
+- Distinguish machine `config` and `metaConfig` (breaking change)
+- Support for machine carriers and netboot servers
+- Optimized git fetch calls when updating software pins
+- Added option `--cores` that is passed to nix-build
+- Added RuboCop
+- Bug fixes
+
+## Transition to `metaConfig`
+The use of `config` has been ambiguous, it could either mean machine
+configuration, i.e. the result of all configured NixOS/vpsAdminOS options,
+or it could mean machine metadata from `module.nix`. Machine metadata
+is now accessible as `metaConfig`.
+
+- `confLib.findConfig` has been renamed to `confLib.findMetaConfig`
+- `confLib.getClusterMachines` returns a list of machines with `metaConfig` attribute
+
+# Sat Feb 17 2024 -- version 1.0.0
 - Initial release

data/README.md

@@ -13,6 +13,8 @@ machines.
   configurations)
 * Query machine state, view changelogs and diffs
 * Run health checks
+* Automatically roll back faulty configurations
+* Support for creating netboot servers with option to kexec, see [docs/carrier.md](docs/carrier.md)
 
 ## Requirements
 
@@ -40,19 +42,12 @@ stored:
 ```
 mkdir cluster-configuration
 ```
-3. Prepare `shell.nix` in the new directory:
-  - Create a `shell.nix` and import the same file from confctl:
+3. Create `shell.nix` and import the same file from confctl:
 ```
 cd cluster-configuration
 cat > shell.nix <<EOF
 import ../confctl/shell.nix
 EOF
-```
-
-  - Alternatively, you can symlink `shell.nix` from the confctl repository:
-```
-cd cluster-configuration
-ln -s ../confctl/shell.nix shell.nix
 ```
 
 4. Enter the `nix-shell`. This will make confctl available and install its
@@ -489,7 +484,7 @@ Then you can use it in machine module as:
 Note that these modules are self-contained. They are not evaluated with the full
 set of NixOS modules. You have to import modules that you need.
 
-## User-defined confctl commands 
+## User-defined confctl commands
 User-defined Ruby scripts can be placed in directory `scripts`. Each script
 should create a subclass of `ConfCtl::UserScript` and call class-method `register`.
 Scripts can define their own `confctl` subcommands.

data/confctl.gemspec

@@ -15,19 +15,19 @@ Gem::Specification.new do |s|
   s.executables = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
   s.license     = 'GPL-3.0-only'
 
-  s.required_ruby_version = ">= #{File.read('.ruby-version').strip}"
+  s.required_ruby_version = '>= 3.1.0'
 
-  s.add_runtime_dependency 'curses'
-  s.add_runtime_dependency 'gli', '~> 2.21.0'
-  s.add_runtime_dependency 'json'
-  s.add_runtime_dependency 'md2man'
-  s.add_runtime_dependency 'rainbow', '~> 3.1.1'
-  s.add_runtime_dependency 'rake'
-  s.add_runtime_dependency 'require_all', '~> 2.0.0'
-  s.add_runtime_dependency 'tty-command', '~> 0.10.1'
-  s.add_runtime_dependency 'tty-cursor', '~> 0.7.1'
-  s.add_runtime_dependency 'tty-pager', '~> 0.14.0'
-  s.add_runtime_dependency 'tty-progressbar', '~> 0.18.2'
-  s.add_runtime_dependency 'tty-spinner', '~> 0.9.3'
-  s.add_runtime_dependency 'vpsfree-client', '~> 0.18.0'
+  s.add_dependency 'curses'
+  s.add_dependency 'gli', '~> 2.22.0'
+  s.add_dependency 'json'
+  s.add_dependency 'md2man'
+  s.add_dependency 'rainbow', '~> 3.1.1'
+  s.add_dependency 'rake'
+  s.add_dependency 'require_all', '~> 2.0.0'
+  s.add_dependency 'tty-command', '~> 0.10.1'
+  s.add_dependency 'tty-cursor', '~> 0.7.1'
+  s.add_dependency 'tty-pager', '~> 0.14.0'
+  s.add_dependency 'tty-progressbar', '~> 0.18.2'
+  s.add_dependency 'tty-spinner', '~> 0.9.3'
+  s.add_dependency 'vpsfree-client', '~> 0.19.0'
 end

data/docs/carrier.md

@@ -0,0 +1,150 @@
+# confctl carriers
+Carrier is a machine that can carry other machines. The concept was created
+for the purpose of building netboot servers, but can be used in other settings
+as well.
+
+All machines must be defined within the cluster as usual. We can then designate
+a machine that will serve as a carrier and provide a list of machines that it
+will carry, e.g.:
+
+```nix
+# File cluster/pxe-server/module.nix
+cluster.pxe-server = {
+  # ...
+  carrier = {
+    enable = true;
+
+    # A list of machines found in the cluster/ directory that will be
+    # available on the netboot server. Note that you will have to create
+    # your own buildAttribute, so that the resulting path contains bzImage,
+    # initrd and possibly a machine.json file.
+    machines = [
+      {
+        machine = "node1";
+        buildAttribute = [ "system" "build" "dist" ];
+      }
+    ];
+  };
+};
+```
+
+Now the `node1` machine is available as two machines within the cluster:
+`node1` and `pxe-server#node1`. We can build and deploy both:
+
+  * `confctl deploy node1` will deploy the target machine as defined by the configuration
+  * `confctl deploy pxe-server#node1` will build the machine and copy the result to `pxe-server`, its carrier
+
+We need both commands to build a slightly different output, but based on the same
+configuration. When deploying `node1`, confctl will build attribute
+`config.system.build.toplevel`, where as deploying `pxe-server#node1` will build
+attribute `config.system.build.dist`. This attribute is configured in `buildAttribute`
+option in the example above. `config.system.build.dist` is defined within vpsAdminOS,
+its output is a directory with kernel bzImage, initrd and the root filesystem
+in a squashfs image, i.e. what we need for booting from network.
+
+Custom build attributes can be created by the user. For example, this is how
+`config.system.build.dist` would be defined for NixOS:
+
+```nix
+# File cluster/nixos/config.nix
+{ config, pkgs, lib, confMachine, swpinsInfo, ... }:
+let
+  # machine.json contains metadata about the machine that the carrier uses
+  # to assemble the netboot server
+  machineJson = pkgs.writeText "machine-${config.networking.hostName}.json" (builtins.toJSON {
+    # machine spin, nixos/vpsadminos
+    spin = "nixos";
+
+    # fully qualified domain name
+    fqdn = confMachine.host.fqdn;
+
+    # label used e.g. in user menus
+    label = confMachine.host.fqdn;
+
+    # path to the top-level derivation, needed for system boot
+    toplevel = builtins.unsafeDiscardStringContext config.system.build.toplevel;
+
+    # NixOS version and git revision
+    version = config.system.nixos.version;
+    revision = config.system.nixos.revision;
+
+    # MAC addresses for auto-detection
+    macs = confMachine.netboot.macs;
+
+    # Information used by confctl status
+    swpins-info = swpinsInfo;
+  });
+in {
+  imports = [
+    <nixpkgs/nixos/modules/installer/netboot/netboot-minimal.nix>
+  ];
+
+  # Define custom build attribute
+  system.build.dist = pkgs.symlinkJoin {
+    name = "nixos-netboot";
+    paths = [
+      config.system.build.netbootRamdisk
+      config.system.build.kernel
+      config.system.build.netbootIpxeScript
+    ];
+
+    # Install machine.json
+    postBuild = ''
+      ln -s ${machineJson} $out/machine.json
+    '';
+  };
+
+  # other NixOS configuration
+}
+```
+
+The carrier must be configured to handle the carried machines. Netboot server
+support is integrated within confctl and it only has to be enabled.
+
+```nix
+# File cluster/pxe-server/config.nix
+{ config, ... }:
+{
+  confctl.carrier.netboot = {
+    enable = true;
+
+    # IP address or hostname the netboot server will be available on
+    host = "192.168.100.5";
+
+    # IP ranges that will have access to the server
+    allowedIPv4Ranges = [
+      "192.168.100.0/24"
+    ];
+  };
+}
+```
+
+The netboot server is rebuilt whenever a machine is deployed to it.
+The rebuild can be also run manually using command `build-netboot-server`.
+
+## Other uses
+You can define your own commands to be run on the carrier machine when
+images are deployed to it:
+
+```nix
+# File cluster/pxe-server/config.nix
+{ config, ... }:
+{
+  confctl.carrier.onChangeCommands = ''
+    # List profiles of carried machines
+    ls -l /nix/var/nix/profiles/confctl-*
+  '';
+}
+```
+
+## kexec from the netboot server
+Set `confctl.programs.kexec-netboot.enable = true;` within your netbooted machine
+configurations. This will add program `kexec-netboot` to your system path.
+
+This program can be used to load kernel and initrd from the netboot server for kexec.
+It automatically discovers the netboot server it was booted from, by default it uses
+the latest generation found on the netboot server at the moment of execution. Use
+`kexec-netboot --interactive` to select which machine/generation/variant should be
+loaded. See `kexec-netboot --help` for all available options.
+
+The loaded kernel can be run either by `kexec-netboot -e` or `kexec -e` directly.

data/lib/confctl/cli/app.rb

@@ -11,6 +11,13 @@ module ConfCtl::Cli
     end
 
     def self.run
+      # Workaround for nix-build error:
+      #   error: creating directory '/tmp/nix-shell-5100-0/nix-build-1986594-0': No such file or directory
+      if ENV['IN_NIX_SHELL']
+        ENV['TMP'] = '/tmp'
+        ENV['TMPDIR'] = '/tmp'
+      end
+
       cli = get
       exit(cli.run(ARGV))
     end
@@ -213,6 +220,12 @@ module ConfCtl::Cli
         c.desc 'Do not activate copied closures'
         c.switch 'copy-only', negatable: false
 
+        c.desc 'Enable auto-rollback'
+        c.switch 'enable-auto-rollback', default_value: false, negatable: false
+
+        c.desc 'Disable auto-rollback'
+        c.switch 'disable-auto-rollback', default_value: false, negatable: false
+
         c.desc 'Reboot target systems after deployment'
         c.switch :reboot
 
@@ -447,6 +460,9 @@ module ConfCtl::Cli
           c.desc 'List remote machine generations'
           c.switch %i[r remote]
 
+          c.desc 'Do not run the garbage collector if enabled in configuration'
+          c.switch %i[gc collect-garbage], default_value: true
+
           c.desc 'Max number of concurrent nix-collect-garbage processes'
           c.flag 'max-concurrent-gc', arg_name: 'n', type: Integer,
                                       default_value: 5
@@ -546,6 +562,9 @@ module ConfCtl::Cli
     def nix_build_options(cmd)
       cmd.desc 'Maximum number of build jobs (see nix-build)'
       cmd.flag %w[j max-jobs], arg_name: 'number'
+
+      cmd.desc 'Number of CPU cores to be used (see nix-build)'
+      cmd.flag :cores, arg_name: 'number'
     end
   end
 end