Skip to content

Inventory

This provides an overview of the available options of the inventory model.

It can be set via the inventory attribute of the clan function, or via the clan.inventory attribute of flake-parts.

instances

Attribute: inventory.instances

Multi host service module instances

Type: attribute set of (submodule)

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

module

Attribute: inventory.instances.<name>.module

This option has no description.

Type: submodule

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

input

Attribute: inventory.instances.<name>.module.input

Name of the input. Default to 'null' which means the module is local

Type: null or string

Default:

"Name of the input. Default to 'null' which means the module is local"

Declared in: lib/modules/inventoryClass/inventory.nix

name

Attribute: inventory.instances.<name>.module.name

Attribute of the clan service module imported from the chosen input.

Defaults to the name of the instance.

Type: string

Default:

"<Name of the Instance>"

Declared in: lib/modules/inventoryClass/inventory.nix

roles

Attribute: inventory.instances.<name>.roles

This option has no description.

Type: attribute set of (submodule)

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

extraModules

Attribute: inventory.instances.<name>.roles.<name>.extraModules

List of additionally imported .nix expressions.

Supported types:

  • Strings: Interpreted relative to the 'directory' passed to lib.clan.
  • Paths: should be relative to the current file.
  • Any: Nix expression must be serializable to JSON.

Note

The import only happens if the machine is part of the service or role.

Other types are passed through to the nixos configuration.

Example

To import the special.nix file

. Clan Directory
├── flake.nix
...
└── modules
    ├── special.nix
    └── ...

{
  extraModules = [ "modules/special.nix" ];
}

Type: list of (string or absolute path or attribute set of anything)

Default:

[ ]

Declared in: lib/modules/inventoryClass/inventory.nix

machines

Attribute: inventory.instances.<name>.roles.<name>.machines

This option has no description.

Type: attribute set of (submodule)

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

settings

Attribute: inventory.instances.<name>.roles.<name>.machines.<name>.settings

This option has no description.

Type: deferred custom module. Must be JSON serializable.

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

settings

Attribute: inventory.instances.<name>.roles.<name>.settings

This option has no description.

Type: deferred custom module. Must be JSON serializable.

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

tags

Attribute: inventory.instances.<name>.roles.<name>.tags

This option has no description.

Type: (attribute set of (submodule)) or (list of string) convertible to it

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

machines

Attribute: inventory.machines

Machines in the inventory.

Each machine declared here can be referencd via its attributeName by the inventory.services roles.

Type: lazy attribute set of (submodule)

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

deploy

Attribute: inventory.machines.<name>.deploy

buildHost

Attribute: inventory.machines.<name>.deploy.buildHost

SSH address of the host to build the machine on

Type: null or string

Default:

null

Declared in: lib/modules/inventoryClass/inventory.nix

targetHost

Attribute: inventory.machines.<name>.deploy.targetHost

SSH address of the host to deploy the machine to

Type: null or string

Default:

null

Declared in: lib/modules/inventoryClass/inventory.nix

description

Attribute: inventory.machines.<name>.description

Optional freeform description

Type: null or string

Default:

null

Declared in: lib/modules/inventoryClass/inventory.nix

icon

Attribute: inventory.machines.<name>.icon

Under construction, will be used for the UI

Type: null or string

Default:

null

Declared in: lib/modules/inventoryClass/inventory.nix

installedAt

Attribute: inventory.machines.<name>.installedAt

Indicates when the machine was first installed.

Timestamp is in unix time (seconds since epoch).

Type: null or signed integer

Default:

null

Declared in: lib/modules/inventoryClass/inventory.nix

machineClass

Attribute: inventory.machines.<name>.machineClass

The module system that should be used to construct the machine

Set this to darwin for macOS machines

Type: one of "nixos", "darwin"

Default:

"nixos"

Declared in: lib/modules/inventoryClass/inventory.nix

name

Attribute: inventory.machines.<name>.name

Name of the machine or service

Type: string

Default:

"‹name›"

Declared in: lib/modules/inventoryClass/inventory.nix

tags

Attribute: inventory.machines.<name>.tags

List of tags for the machine.

The machine can be referenced by its tags in inventory.services

Example 
inventory.machines.machineA.tags = [ "tag1" "tag2" ];

services.borgbackup."instance_1".roles.client.tags = [ "tag1" ];

Note

Tags can be used to determine the membership of the machine in the services. Without changing the service configuration, the machine can be added to a service by adding the correct tags to the machine.

Type: list of string

Default:

[ ]

Declared in: lib/modules/inventoryClass/inventory.nix

meta

Attribute: inventory.meta

This option has no description.

Type: submodule

Declared in: lib/modules/inventoryClass/inventory.nix

description

Attribute: inventory.meta.description

Optional freeform description

Type: null or string

Default:

null

Declared in: lib/modules/inventoryClass/meta-interface.nix

icon

Attribute: inventory.meta.icon

Under construction, will be used for the UI

Type: null or string

Default:

null

Declared in: lib/modules/inventoryClass/meta-interface.nix

name

Attribute: inventory.meta.name

Name of the clan.

Needs to be (globally) unique, as this determines the folder name where the flake gets downloaded to.

Should only contain alphanumeric characters, _ and -.

Type: string matching the pattern [a-zA-Z0-9_-]*

Example 
"my_clan"

Declared in: lib/modules/inventoryClass/meta-interface.nix

modules

Attribute: inventory.modules

A mapping of module names to their path.

Each module can be referenced by its attributeName in the inventory.services attribute set.

Important

Each module MUST fulfill the following requirements to be usable with the inventory:

  • The module MUST have a README.md file with a description.
  • The module MUST have at least features = [ "inventory" ] in the frontmatter section.
  • The module MUST have a subfolder roles with at least one {roleName}.nix file.

For further information see: Module Authoring Guide.

Example 
clan-core.lib.clan {
    # 1. Add the module to the available inventory modules
    inventory.modules = {
      custom-module = ./modules/my_module;
    };
    # 2. Use the module in the inventory
    inventory.services = {
      custom-module.instance_1 = {
          roles.default.machines = [ "machineA" ];
      };
    };
};

Type: attribute set of raw value

Default:

"clanModules of clan-core"

Declared in: lib/modules/inventoryClass/inventory.nix

tags

Attribute: inventory.tags

Tags of the inventory are used to group machines together.

It is recommended to use machine.tags to define the tags of the machines.

This can be used to define custom tags that are either statically set or dynamically computed.

Static Tags

Static Tag Example 
inventory.tags = {
  foo = [ "machineA" "machineB" ];
};

The tag foo will always be added to machineA and machineB.

Dynamic Tags

It is possible to compute tags based on the machines properties or based on other tags.

Danger

This is a powerful feature and should be used with caution.

It is possible to cause infinite recursion by computing tags based on the machines properties or based on other tags.

Dynamic Tag Example

allButFoo is a computed tag. It will be added to all machines except 'foo'

all is a predefined tag. See the docs of tags.all.

#  inventory.tags ↓       ↓ inventory.machines
inventory.tags = {config, machines...}: {
  #                                                        ↓↓↓ The "all" tag
  allButFoo = builtins.filter (name: name != "foo") config.all;
};

Warning

Do NOT compute tags from machine.tags this will cause infinite recursion.

Type: lazy attribute set of list of string

Default:

{ }

Declared in: lib/modules/inventoryClass/inventory.nix

all

Attribute: inventory.tags.all

Predefined Tag

Will be added to all machines

inventory.machines.machineA.tags = [ "all" ];

Type: list of string

Default:

"[ <All Machines> ]"

Declared in: lib/modules/inventoryClass/inventory.nix

darwin

Attribute: inventory.tags.darwin

Predefined Tag

Will be added to all machines that set machineClass = "darwin"

inventory.machines.machineA.tags = [ "darwin" ];

Type: list of string

Default:

"[ <All Darwin Machines> ]"

Declared in: lib/modules/inventoryClass/inventory.nix

nixos

Attribute: inventory.tags.nixos

Predefined Tag

Will be added to all machines that set machineClass = "nixos"

inventory.machines.machineA.tags = [ "nixos" ];

Type: list of string

Default:

"[ <All NixOS Machines> ]"

Declared in: lib/modules/inventoryClass/inventory.nix