https://github.com/SaumonNet/proxmox-nixos
The Proxmox Hypervisor, on NixOS [maintainers=@camillemndn @julienmalka]
https://github.com/SaumonNet/proxmox-nixos
nix-ci
Last synced: 4 months ago
JSON representation
The Proxmox Hypervisor, on NixOS [maintainers=@camillemndn @julienmalka]
- Host: GitHub
- URL: https://github.com/SaumonNet/proxmox-nixos
- Owner: SaumonNet
- License: agpl-3.0
- Created: 2024-02-18T13:54:11.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-29T17:40:10.000Z (11 months ago)
- Last Synced: 2024-08-29T23:42:41.666Z (11 months ago)
- Topics: nix-ci
- Language: Nix
- Homepage:
- Size: 11 MB
- Stars: 481
- Watchers: 11
- Forks: 16
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - SaumonNet/proxmox-nixos - The Proxmox Hypervisor, on NixOS [maintainers=@camillemndn @julienmalka] (Nix)
- awesome-starred - SaumonNet/proxmox-nixos - The Proxmox Hypervisor, on NixOS [maintainers=@camillemndn @julienmalka] (Nix)
README
# Proxmox on NixOS
This project is a port of the [Proxmox Hypervisor](https://www.proxmox.com/) on NixOS.
⚠️ Proxmox-NixOS is still **experimental** and we do not advise running it on production machines. Do it at your own risk and only if you are ready to fix issues by yourself.
## 🚦 Supported features
Proxmox-NixOS has been tested on real hardware with most basic features of Proxmox (booting VMs, user management, etc), more involved setups (clusters, HA, etc) are still under development and testing.
While we export other architectures for convenience of the user, we only support `x86_64-linux` for now;
## 🗃️ Cache
Some Proxmox packages have a quite power intensive build process. We make a cache available to download directly the artifacts:
- address: `https://cache.saumon.network/proxmox-nixos`
- public key: `proxmox-nixos:nveXDuVVhFDRFx8Dn19f1WDEaNRJjPrF2CPD2D+m1ys=`
## 🚀 Quick start
### With [`npins`](https://github.com/andir/npins)
Add `proxmox-nixos` as a dependency of your npins project.
```console
$ npins add github SaumonNet proxmox-nixos -b main
[INFO ] Adding 'proxmox-nixos' …
repository: https://github.com/SaumonNet/proxmox-nixos.git
branch: main
revision: ...
url: https://github.com/saumonnet/proxmox-nixos/archive/$revision.tar.gz
hash: ...
```
Below is a fragment of a NixOS configuration that enables Proxmox VE.
```nix
# file: configuration.nix
{ pkgs, lib, ... }:
let
sources = import ./npins;
proxmox-nixos = import sources.proxmox-nixos;
in
{
imports = [ proxmox-nixos.nixosModules.proxmox-ve ];
services.proxmox-ve = {
enable = true;
ipAddress = "192.168.0.1";
};
nixpkgs.overlays = [
proxmox-nixos.overlays.x86_64-linux
];
# The rest of your configuration...
}
```
### With Flakes
Below is a fragment of a NixOS configuration that enables Proxmox VE.
```nix
{
description = "A flake with Proxmox VE enabled";
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
proxmox-nixos.url = "github:SaumonNet/proxmox-nixos";
};
outputs = { self, nixpkgs, proxmox-nixos, ...}: {
nixosConfigurations = {
yourHost = nixpkgs.lib.nixosSystem rec {
system = "x86_64-linux";
modules = [
proxmox-nixos.nixosModules.proxmox-ve
({ pkgs, lib, ... }: {
services.proxmox-ve = {
enable = true;
ipAddress = "192.168.0.1";
};
nixpkgs.overlays = [
proxmox-nixos.overlays.${system}
];
# The rest of your configuration...
})
];
};
};
};
}
```
Do not override the `nixpkgs-stable` input of the flake, as the only tested and supported version of Proxmox-NixOS is with the upstream stable NixOS release.
## 🌐 Networking
To get internet in your VMs, you need to add a network device to the VM, connected to a bridge. To get this working, follow this 2 steps:
1. Create the bridge in `System->Network->Create->Linux Bridge`. This operation has no effect on your system and is just a quirk for Proxmox to know the existence of your bridge.
2. Configure your networking through NixOS configuration so that the bridge you created in the Proxmox web interface actually exists!
### Example NixOS networking configurations
Any kind of advanced networking configuration is possible through the usual NixOS options, but here are basic examples that can get you started:
#### With `systemd-networkd`
```nix
systemd.network.networks."10-lan" = {
matchConfig.Name = [ "ens18" ];
networkConfig = {
Bridge = "vmbr0";
};
};
systemd.network.netdevs."vmbr0" = {
netdevConfig = {
Name = "vmbr0";
Kind = "bridge";
};
};
systemd.network.networks."10-lan-bridge" = {
matchConfig.Name = "vmbr0";
networkConfig = {
IPv6AcceptRA = true;
DHCP = "ipv4";
};
linkConfig.RequiredForOnline = "routable";
};
```
### With scripted networking
```nix
networking.bridges.vmbr0.interfaces = [ "ens18" ];
networking.interfaces.vmbr0.useDHCP = lib.mkDefault true;
```
## 🧱 Declarative VMs
### Using the module [`virtualisation.proxmox`](modules/declarative-vms)
_This solution is available even for the admin of a particular VM with only
a restricted API access to the Proxmox Hypervisor._
The utility `nixmoxer` allows one to bootstrap NixOS virtual machines on an
existing Proxmox hypervisor, using the API.
First, configure the virtual machine settings using the options of the NixOS module
`virtualisation.proxmox` of your `nixosConfigurations.myvm`:
```nix
# myvm.nix
{ config, ... }:
{
imports = [ ./disko.nix ];
networking.hostName = "myvm";
virtualisation.proxmox = {
node = "myproxmoxnode";
iso = ;
vmid = 101;
memory = 4096;
cores = 4;
sockets = 2;
net = [
{
model = "virtio";
bridge = "vmbr0";
}
];
scsi = [ { file = "local:16"; } ]; # This will create a 16GB volume in 'local'
};
# The rest of your configuration...
}
```
You can find an exhaustive list of options in [modules/declarative-vms/options.nix](modules/declarative-vms/options.nix),
or in the official [documentation](https://pve.proxmox.com/pve-docs/api-viewer/#/nodes/{node}/qemu) of the Proxmox API.
Then configure the access to the Proxmox API:
```sh
# nixmoxer.conf
host=192.168.0.3
user=root
password=
verify_ssl=0
```
Now you can bootstrap `myvm` using `nixmoxer`:
```console
$ nix run github:SaumonNet/proxmox-nixos#nixmoxer -- [--flake] myvm
```
`nixmoxer` will setup the VM on the Proxmox node and attach the specified iso. Instead of specified an iso, setting `autoInstall = true;` will automatically generate an iso that will automatically install the configuration to the VM being bootstrapped.
⚠️ `nixmoxer` shall only be used for the initial bootstraping of a VM, the NixOS VM can be rebuilt with usual tools like `nixos-rebuild`, `colmena`, etc. Changes to the `virtualisation.proxmox` options after the boostraping have no impact.
### Using the module [`services.proxmox-ve.vms`](modules/proxmox-ve/vms.nix)
_This solution is only available for the admin of a Proxmox Hypervisor on NixOS_.
This configuration will create two VMs on a Proxmox-NixOS Hypervisor. Then you can attach an
iso and configure your VMs as usual.
```nix
# configuration.nix
{
services.proxmox-ve = {
enable = true;
ipAddress = "192.168.0.1";
vms = {
myvm1 = {
vmid = 100;
memory = 4096;
cores = 4;
sockets = 2;
kvm = false;
net = [
{
model = "virtio";
bridge = "vmbr0";
}
];
scsi = [ { file = "local:16"; } ];
};
myvm2 = {
vmid = 101;
memory = 8192;
cores = 2;
sockets = 2;
scsi = [ { file = "local:32"; } ];
};
};
};
# The rest of your configuration...
}
```
You can find an exhaustive list of options in [modules/declarative-vms/options.nix](modules/declarative-vms/options.nix),
or in the official [documentation](https://pve.proxmox.com/pve-docs/api-viewer/#/nodes/{node}/qemu) of the Proxmox API.
⚠️ The current limitation is that if for instance VM `myvm1` has already been initialised,
subsequent changes to the configuration in `services.proxmox-ve.vms.myvm1` will have no impact.
### Note
Truly declarative configuration of virtual machines is very difficult with Proxmox-NixOS because there is essentially 2 sources of truth (the NixOS configuration and the Proxmox web interface) that have to be reconciliated. If you want truly declarative VMs configurations we recommend the amazing project [microvms.nix](https://github.com/astro/microvm.nix).
## 🚧 Roadmap
- Support for clusters / HA with Ceph
- More coverage of NixOS tests
- Proxmox backup server
## 🔧 Maintainance
Most packages are regularly and automatically updated thanks to [a modified version](https://github.com/SaumonNet/proxmox-nixos-update) of the [`nixpkgs-update`](https://github.com/nix-community/nixpkgs-update) bot, whose logs are available [here](https://proxmox-nixos-update-logs.saumon.network/).
## 📬 Help / Discussions
There is [a matrix room](https://matrix.to/#/#proxmox-nixos:matrix.org) for discussions about Proxmox-NixOS.
## Thanks
This project has received support from [NLNet](https://nlnet.nl/).
