Package: python-ourkvm
ourkvmOur KVM solution. Cluster, API and local tools all in one.What is ourkvm?There are four overall components:ProductDescriptionAPIA FastAPI backend that browsers can talk toClusterThe API optionally supports enabling cluster servicesCLI ToolA CLI tool that can produce virtual machines, report health and run cluster agentsLibraryA Python library which the above uses to perform their tasksDemo of UsageCreating a machine, then starting it, attaching to the--serialdevice, snapshotting the machine with--snapshotand stopping it:!videoAPIThe API is a rest API enabled by runningpython -m ourkvm --apiThe API is built usingFastAPI.The API requires authentication and usesOpenID connectandJWTfor SSO.This is done usingfastapi_resource_server. It's tested againstKeycloakusing a custom realm, users and roles/groups to isolate permissions.ClusterThe cluster communicates on port 8050 using JWT and standard sockets.
For documentation on the protocol, seedocs/clusterfor more information.
To register a cluster agent, simply run the CLI tool with the parameter--cluster-agent.CLI ToolThe library ships with a Python module that can produce qemu strings that you can use to launch a machine.It can create local resources such as Qemu disk images, Virtual Machine templates, configuration and.servicefiles.These.servicefiles that the module generates, can be started withsystemctl --user start machineX.servicewhich is described below.Creating a local virtual machine$python-mourkvm\--machine-nametestmachine\--namespacetestmachine\--memory4096\--harddrives./testimg.qcow2:20G,./testlarge.qcow2:40G\--cdroms~/archiso/out/*.iso\--service/etc/systemd/system/\--config/etc/qemu.d/The following will create a minimal virtual machine using NAT for networking, headless operation meant to be started withsystemctl start testmachine.service.Stopping a machine$sudosystemctlstoptestmachine.serviceUsing the above example service oftestmachine.service, the service will triggerpython -m ourkvm --machine-name testmachine --stopwhich will attach to the Qemu QMP socket at/tmp/testmachine.qmpand execute apoweroff(followed byqemu-quitafter a grace period if the machine has not yet powered off).Adding custom networking$python-mourkvm\--machine-nametestmachine\--namespacetestmachine\--memory4096\--harddrives./testimg.qcow2:20G,./testlarge.qcow2:40G\--cdroms~/archiso/out/*.iso\--service/etc/systemd/system/\--config/etc/qemu.d/\--network'[ {  "type": "tap",  "name": "tap0",  "bridge": "ns_br0",  "namespace": {"from": null, "to": true},  "attach": true}, {  "type": "veth",  "name": "vens0",  "bridge": "test_bridge",  "namespace": {"from": null, "to": true},  "veth_pair": "vens0_ns" }, {  "type": "veth",  "name": "vens0_ns",  "bridge": "ns_br0",  "namespace": {"from": null, "to": true},  "veth_pair": "vens0",  "mac": "fe:00:00:00:00:01" }]'Adding to the previous example, this will add networking according to the following JSON layout:[{"type":"tap","name":"tap0","bridge":"ns_br0","namespace":{"from":null,"to":true},"attach":true},{"type":"veth","name":"vens0","bridge":"test_bridge","namespace":{"from":null,"to":null},"veth_pair":"vens0_ns"},{"type":"veth","name":"vens0_ns","bridge":"ns_br0","namespace":{"from":null,"to":true},"veth_pair":"vens0","mac":"fe:00:00:00:00:01"}]This creates several network components. Beginning from the top of the JSON file(but backwards logically):Atap0interface attached to the virtual machineA bridgens_br0connectingtap0to itMoving the above two interfaces into a namespace calledtestmachineCreating a veth-pair ofvens0<-->vens0_nsCreating a bridge calledtest_bridgeAddingvens0to thetest_bridgeMovingvens0_nsinto the namespacetestmachineSets MAC address FE:00:00:00:00:01 to interface vens0_ns upon VM startupCreating a network chain that looks like the following:[host] test_bridge <--> vens0--|--vens0_ns <--> ns_br0 <--> tap0 [vm].The API will take care of creating the elaborate network infrastructure, but the CLI does the work for now.Note:thenamespacedeclaration in the network struct isTrueand will automatically get converted to the--namespacedefinition. Specific namespace names can be supplied here instead if the VM are to connect between multiple namespaces using bridges or veth interfaces.note: MAC addresses will be auto-generated for tap0 and vens0 in the above example upon creationContributingWe use tabs over spaces. We follow pep8 to some extent usingFlake8(see.flake8for exceptions). We follow strict typing usingmypywith the--strictparameter and we require every function to have a associatedpytestfunction under/tests/.We welcome PR's on any addition/change. They might not all make it, but we develop straight againstmainwhich is our master branch. OccationalvX.y.z-devbranch might appear to fix an older version while a major release is being on the way. PR's will not be merged until the three GitHub workflows(flake8, mypy and pytest)have completed successfully.HelpFeel free to open a issue if you think it's a bug or you want to suggest an improvement.DiscussionsOpen a discussion on a topic you believe is relevant to discuss or talk about surrounding ourkvm, if it doesn't fit the #help section.