Add machines

Summary

In Clan, machines describe all client devices from cloud VMs to bare metal laptops and are defined using Nix code inside the flake.

The creation of machines will be the same process for all kinds of devices and only later branch into specific steps.

This general guide will navigate you through the machine creation.

When finishing it, you will have prepared at least one machine that can be rolled out to a target device in the next steps.

Requirements

Estimated time: 30min
You have created a clan during the previous step
You are logged in as root on your setup device
direnv is running in your clan folder (see previous step for setup)

Creating a Machine

Navigate to your clan folder and run the following command to create a machine for our test user Jon:

clan machines create jon-machine

A dedicated folder will be created at machines/jon-machine. You can see the complete list of auto-loaded files in our extended documentation.

Configuring a Machine

You can edit your clan.nix file for additional machine features. This example demonstrates a setup with two machines and a few extra settings:

clan.nix

{
    inventory.machines = {
        jon-machine = {
            deploy.targetHost = "root@192.168.0.2";
            # Define tags here (optional)
            tags = [ ]; 
        };
        sara-machine = {
            # Define tags here (optional)
            tags = [ ]; # 
        };
    };
    # Define additional nixosConfiguration here
    # Or in /machines/jon/configuration.nix (autoloaded)
    machines = {
        jon-machine = { config, pkgs, ... }: {
            users.users.root.openssh.authorizedKeys.keys = [
                "ssh-ed25519 AAAAC3NzaC..." # elided
            ];
        };
    };
}

inventory.machines: Tags can be used to automatically assign services to a machine later on (don't worry, we don't need to set this now). Additional machines - like sara-machine in this example - will all be listed here if created via clan machines create <name>

machines: It is advised to add the ssh key of your setup device's root user here - That will ensure you can always login to your new machine via ssh root@ip from your setup device in case something goes wrong.

Developer Note

The option: inventory.machines.<name> is used to define metadata about the machine.

That includes for example deploy.targethost or machineClass or tags

The option: machines.<name> is used to add extra nixosConfiguration to a machine

(Optional) Manually Create a `configuration.nix` instead

You can create the configuration file manually if you don't want to use the cli commands

./machines/jon/configuration.nix

{
    imports = [
        # enables GNOME desktop (optional)
        ../../modules/gnome.nix
    ];

    # Set nixosOptions here
    # Or import your own modules via 'imports'
    # ...
}

(Optional) Removing a Machine

If you need to delete a machine...

...you can remove the entries both from your flake.nix and from the machines directory. For example, to remove sara-machine, use:

git rm -rf ./machines/sara-machine

Make sure to also remove or update any references to that machine in your nix files and inventory.json

Checkpoint

Verify that your machines have been created successfully by listing them:

clan machines list

This should display all the machines you've created (e.g., jon-machine). If you don't see your machines listed, double-check the previous steps.

Up Next

In the next step, we will create and configure the users for the machines we just prepared.