kebairia / kvmcli

A Python wrapper for managing virtual machines in a KVM-based cluster.

KVMcli

A Python script for managing virtual machines in a KVM-based environment.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Demo
Deploy with a single command (after updating the configuration files)

Built With

Technologies	Used for
	Python is the primary programming language used in this project.
	YAML is utilized to describe the virtual machines cluster.
	TOML is used for managing configuration files in the project.

Getting Started

Installation

1. Clone the repo

   git clone https://github.com/kebairia/kvmcli.git

2. Install the project

   make install

Usage

Note: This project is still under development, but you can use it to provision VMs with different operating systems.

The project has the following structure:

• A YAML file named servers.yml ¹ for describing your cluster.
• A configuration file named config.cfg for assigning default values, such as the name of the main YAML file.
• The kvmcli command line tool is the main tool for the project.

Configuring default values

Modify config.cfg with the default values that you need. You can specify the path to the server YAML file, the path to the artifacts and images directories, the name of the image that you want to use, on so on.

Here's an example of how to configure the default values in config.cfg:

# KVMCLI provisioner script configuration file
 
[misc]
# Number of forks to use in a multi-process application
fork = 5  

# YAML configurations
[yaml]
# Default path for YAML file
path = "servers.yml"
# Name of template YAML file used when initializing script
template = "servers.yml"

# Image configurations
[image]
artifacts_path = "/home/zakaria/dox/homelab/artifacts"
images_path = "/home/zakaria/dox/homelab/images"
image_name = "homelab"

...

Launching the provisioning process

The kvmcli command is used for launching the provisioning process. You can use it to create a template, print information about your cluster, apply configuration from a YAML file, or ignore a specific node.

Creating a template

To begin, utilize the --init option for generating a template that will serve as a reference for creating your virtual machines."

kvmcli --init

Template file with the name `template.yml` is created !

This will create a template file named template.yml. The content of the template will be like the following:

version: 1.0
vms:
- info:
    name: node1
    image: rocky9.1
    ram: 1536
    cpus: 1
    os: rocky9
  network:
    interface:
      bridge: virbr1
      mac_address: 02:A3:10:00:00:10
  storage:
    disk:
      format: qcow2
      size: 30
      type: SSD

You can use the --info option to print the content of the template file in a pretty table: It uses the default value of template_name from the config.cfg configuration file

kvmcli --info

If you want to use another file as a reference, use the -f or --file option:

kvmcli --info -f template.yml

                                  TEMPLATE.YML                                 
 ┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
 ┃ SERVERS ┃ SYSTEM ┃ RAM     ┃ CPUS ┃ BRIDGE ┃ MAC ADDRESS       ┃ DISK SIZE ┃
 ┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
 │ node1   │ rocky9 │ 1536 MB │ 1    │ virbr1 │ 02:A3:10:00:00:10 │ 30 GB     │
 └─────────┴────────┴─────────┴──────┴────────┴───────────────────┴───────────┘

Applying configuration from a YAML file

When you're happy with the result, you can start provisioning using the -a or --apply option:

kvmcli --apply -f template.yml

 INFO: Copying new VM to /home/zakaria/dox/homelab/images/node1.qcow2
 INFO: Provisioning a new VM named node1
 
 INFO: All VMs provisioned successfully!

The --ignore flag is used to exclude specific nodes from the provisioning process when applying a configuration from a YAML file using the kvmcli tool.

For example, running kvmcli --apply -f template.yml --ignore node1 will apply the configuration defined in template.yml, but exclude the node1 node from being provisioned.

kvmcli --apply -f template.yml --ignore node1

-h, --help Show the help message and exit.

usage: kvmcli [-h] [-I] [-i] [-a] [-f YAML_FILE] [--ignore NODE_NAME]

A Python script for managing virtual machines in a KVM-based environment.

options:
  -h, --help            show this help message and exit
  -I, --info            Print information about your cluster
  -i, --init            Create template file
  -a, --apply           apply configuration from YAML_FILE
  -f YAML_FILE, --file YAML_FILE
                        Specify a yaml file
  --ignore NODE_NAME    Ignore NODE NAME

Enjoy

Roadmap

• Print report for the cluster
• Provision multiple VMs with different Operating Systems
• Enhancing command line tool
• Multiprocessing support
• Provisioning system
• Logging system

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the GPL-3.0 License. See LICENSE.md for more information.

Contact

Project Link: https://github.com/kebairia/kvmcli

Acknowledgments

• README Template

Footnotes

Footnotes

1. Or any name you like, you can change that by changing the path and template_name keys under [yaml] section in config.cfg

   [yaml]
   # Default path for YAML file
   path = "servers.yml"
   # Name of template YAML file used when initializing script
   template = "servers.yml"
   

   ↩