nixos-servers/scripts/create-host/README.md

NixOS Host Configuration Generator

Automated tool for generating NixOS host configurations, flake.nix entries, and Terraform VM definitions for homelab infrastructure.

Installation

The tool is available in the Nix development shell:

nix develop

Usage

Basic Usage

Create a new host with DHCP networking:

python -m scripts.create_host.create_host create --hostname test01

Create a new host with static IP:

python -m scripts.create_host.create_host create \
  --hostname test01 \
  --ip 10.69.13.50/24

Create a host with custom resources:

python -m scripts.create_host.create_host create \
  --hostname bighost01 \
  --ip 10.69.13.51/24 \
  --cpu 8 \
  --memory 8192 \
  --disk 100G

Dry Run Mode

Preview what would be created without making changes:

python -m scripts.create_host.create_host create \
  --hostname test01 \
  --ip 10.69.13.50/24 \
  --dry-run

Force Mode (Regenerate Existing Configuration)

Overwrite an existing host configuration (useful for testing):

python -m scripts.create_host.create_host create \
  --hostname test01 \
  --ip 10.69.13.50/24 \
  --force

This mode:

• Skips hostname and IP uniqueness validation
• Overwrites files in hosts/<hostname>/
• Updates existing entries in flake.nix and terraform/vms.tf (doesn't duplicate)
• Useful for iterating on configuration templates during testing

Options

• --hostname (required): Hostname for the new host

  • Must be lowercase alphanumeric with hyphens
  • Must be unique (not already exist in repository)

• --ip (optional): Static IP address with CIDR notation

  • Format: 10.69.13.X/24
  • Must be in 10.69.13.0/24 subnet
  • Last octet must be 1-254
  • Omit this option for DHCP configuration

• --cpu (optional, default: 2): Number of CPU cores

  • Must be at least 1

• --memory (optional, default: 2048): Memory in MB

  • Must be at least 512

• --disk (optional, default: "20G"): Disk size

  • Examples: "20G", "50G", "100G"

• --dry-run (flag): Preview changes without creating files

• --force (flag): Overwrite existing host configuration

  • Skips uniqueness validation
  • Updates existing entries instead of creating duplicates

What It Does

The tool performs the following actions:

1. Validates the configuration:

   • Hostname format (RFC 1123 compliance)
   • Hostname uniqueness
   • IP address format and subnet (if provided)
   • IP address uniqueness (if provided)

2. Generates host configuration files:

   • hosts/<hostname>/default.nix - Import wrapper
   • hosts/<hostname>/configuration.nix - Full host configuration

3. Updates repository files:

   • flake.nix - Adds new nixosConfigurations entry
   • terraform/vms.tf - Adds new VM definition

4. Displays next steps for:

   • Reviewing changes with git diff
   • Verifying NixOS configuration
   • Verifying Terraform configuration
   • Committing changes
   • Deploying the VM

Generated Configuration

Host Features

All generated hosts include:

• Full system imports from ../../system:

  • Nix binary cache integration
  • SSH with root login
  • SOPS secrets management
  • Internal ACME CA integration
  • Daily auto-upgrades with auto-reboot
  • Prometheus node-exporter
  • Promtail logging to monitoring01

• VM guest agent from ../../common/vm

• Hardware configuration from ../template/hardware-configuration.nix

Networking

Static IP mode (when --ip is provided):

systemd.network.networks."ens18" = {
  matchConfig.Name = "ens18";
  address = [ "10.69.13.50/24" ];
  routes = [ { Gateway = "10.69.13.1"; } ];
  linkConfig.RequiredForOnline = "routable";
};

DHCP mode (when --ip is omitted):

systemd.network.networks."ens18" = {
  matchConfig.Name = "ens18";
  networkConfig.DHCP = "ipv4";
  linkConfig.RequiredForOnline = "routable";
};

DNS Configuration

All hosts are configured with:

• DNS servers: 10.69.13.5, 10.69.13.6 (ns1, ns2)
• Domain: home.2rjus.net

Examples

Create a test VM with defaults

python -m scripts.create_host.create_host create --hostname test99

This creates a DHCP VM with 2 CPU cores, 2048 MB memory, and 20G disk.

Create a database server with static IP

python -m scripts.create_host.create_host create \
  --hostname pgdb2 \
  --ip 10.69.13.52/24 \
  --cpu 4 \
  --memory 4096 \
  --disk 50G

Preview changes before creating

python -m scripts.create_host.create_host create \
  --hostname test99 \
  --ip 10.69.13.99/24 \
  --dry-run

Error Handling

The tool validates input and provides clear error messages for:

• Invalid hostname format (must be lowercase alphanumeric with hyphens)
• Duplicate hostname (already exists in repository)
• Invalid IP format (must be X.X.X.X/24)
• Wrong subnet (must be 10.69.13.0/24)
• Invalid last octet (must be 1-254)
• Duplicate IP address (already in use)
• Resource constraints (CPU < 1, memory < 512 MB)

Integration with Deployment Pipeline

This tool implements Phase 2 of the automated deployment pipeline:

1. Phase 1: Template building ✓ (build-and-deploy-template.yml)
2. Phase 2: Host configuration generation ✓ (this tool)
3. Phase 3: Bootstrap automation (planned)
4. Phase 4: Secrets management (planned)
5. Phase 5: DNS automation (planned)
6. Phase 6: Full integration (planned)

Development

Project Structure

scripts/create-host/
├── create_host.py          # Main CLI entry point (typer app)
├── __init__.py            # Package initialization
├── validators.py          # Validation logic
├── generators.py          # File generation using Jinja2
├── manipulators.py        # Text manipulation for flake.nix and vms.tf
├── models.py              # Data models (HostConfig)
├── templates/
│   ├── default.nix.j2     # Template for default.nix
│   └── configuration.nix.j2  # Template for configuration.nix
└── README.md              # This file

Testing

Run the test cases from the implementation plan:

# Test 1: DHCP host with defaults
python -m scripts.create_host.create_host create --hostname testdhcp --dry-run

# Test 2: Static IP host
python -m scripts.create_host.create_host create \
  --hostname test50 --ip 10.69.13.50/24 --dry-run

# Test 3: Custom resources
python -m scripts.create_host.create_host create \
  --hostname test51 --ip 10.69.13.51/24 \
  --cpu 8 --memory 8192 --disk 100G --dry-run

# Test 4: Duplicate hostname (should error)
python -m scripts.create_host.create_host create --hostname ns1 --dry-run

# Test 5: Invalid subnet (should error)
python -m scripts.create_host.create_host create \
  --hostname testbad --ip 192.168.1.50/24 --dry-run

# Test 6: Invalid hostname (should error)
python -m scripts.create_host.create_host create --hostname Test_Host --dry-run

License

Part of the nixos-servers homelab infrastructure repository.