Guides implementation of new virtualization providers for kcli. Use when adding support for a new cloud platform, hypervisor, or infrastructure provider.
Providers are located in kvirt/providers/ as subdirectories. Each provider implements the interface defined in kvirt/providers/sampleprovider.py (class Kbase).
kvirt/providers/yourprovider/
├── __init__.py # Contains your Kyourprovider class
└── (optional helpers)
Your class must:
self.conn attribute in __init__ (set to None if backend unreachable)self.debug from the debug parameterReturn Value Pattern:
# Success
return {'result': 'success'}
# Failure
return {'result': 'failure', 'reason': "VM %s not found" % name}
VM Lifecycle (required):
create() - Create VM with all parameters (cpus, memory, disks, nets, etc.)start(name) - Start VMstop(name, soft=False) - Stop VMrestart(name) - Restart VM (default calls start)delete(name, snapshots=False, keep_disks=False) - Delete VMlist() - Return list of [name, state, ip, source, plan, profile]info(name, output, fields, values, vm, debug) - Return VM details dictexists(name) - Check if VM existsstatus(name) - Return VM statusip(name) - Return IP stringclone(old, new, full=False, start=False) - Clone VMexport(name, image=None) - Export VM as imageconsole(name, tunnel, tunnelhost, tunnelport, tunneluser, web) - Graphical consoleserialconsole(name, web) - Serial consoleStorage:
create_pool(name, poolpath, pooltype, user, thinpool)delete_pool(name, full)list_pools() - Return list of pool namesget_pool_path(pool) - Get pool pathadd_disk(name, size, pool, thin, image, shareable, existing, interface, novm, overrides)delete_disk(name, diskname, pool, novm)create_disk(name, size, pool, thin, image) - Create standalone disklist_disks() - Return dict {'diskname': {'pool': poolname, 'path': name}}disk_exists(pool, name) - Check if disk existsdetach_disks(name) - Detach all disks from VMNetworking:
create_network(name, cidr, dhcp, nat, domain, plan, overrides)delete_network(name, cidr, force)update_network(name, dhcp, nat, domain, plan, overrides)list_networks() - Return dict of networksinfo_network(name) - Get network infonet_exists(name) - Check if network existsnetwork_ports(name) - List ports on networkadd_nic(name, network, model)delete_nic(name, interface)update_nic(name, index, network) - Update NICSubnets (cloud providers):
create_subnet(name, cidr, dhcp, nat, domain, plan, overrides)delete_subnet(name, force)update_subnet(name, overrides)list_subnets() - Return subnet dictinfo_subnet(name) - Get subnet infoImages:
volumes(iso=False, extended=False) - List available imagesadd_image(url, pool, short, cmds, name, size, convert)delete_image(image, pool)Snapshots:
create_snapshot(name, base) - Create snapshotdelete_snapshot(name, base) - Delete snapshotlist_snapshots(base) - List snapshots (returns list)revert_snapshot(name, base) - Revert to snapshotUpdate Operations:
update_metadata(name, metatype, metavalue, append)update_memory(name, memory)update_cpus(name, numcpus)update_start(name, start) - Set autostartupdate_information(name, information) - Update info metadataupdate_iso(name, iso) - Change attached ISOupdate_flavor(name, flavor) - Change VM flavorBuckets (object storage):
create_bucket(bucket, public) - Create storage bucketdelete_bucket(bucket) - Delete bucketlist_buckets() - List all bucketslist_bucketfiles(bucket) - List files in bucketupload_to_bucket(bucket, path, overrides, temp_url, public)download_from_bucket(bucket, path)delete_from_bucket(bucket, path)Security Groups (cloud providers):
create_security_group(name, overrides)delete_security_group(name)update_security_group(name, overrides)list_security_groups(network) - List security groupsDNS:
reserve_dns(name, nets, domain, ip, alias, force, primary, instanceid)list_dns_zones() - List DNS zonesdnsinfo(name) - Return (dnsclient, domain) for VMOther:
close() - Clean up connectioninfo_host() - Return host info dictvm_ports(name) - List ports on VMlist_flavors() - Return [[name, numcpus, memory], ...] if platform supports flavorsAdd import and instantiation in kvirt/config.py (around lines 102-220):
elif self.type == 'yourprovider':
# Get provider-specific options
option1 = options.get('option1')
if option1 is None:
error("Missing option1 in configuration. Leaving")
sys.exit(1)
try:
from kvirt.providers.yourprovider import Kyourprovider
except Exception as e:
exception = e if debug else None
dependency_error('yourprovider', exception)
k = Kyourprovider(option1=option1, debug=debug)
YOURPROVIDER = ['required-package1', 'required-package2']
# Add to extras_require dict:
extras_require={
'yourprovider': YOURPROVIDER,
# ...
}
# Add to ALL list if needed:
ALL = EXTRAS + AWS + ... + YOURPROVIDER
The info() method should build a dict with these keys:
name, autostart, plan, profile, image, ip, memory, numcpus, creationdatenets: list of {'device': device, 'mac': mac, 'net': network, 'type': network_type}disks: list of {'device': device, 'size': disksize, 'format': diskformat, 'type': drivertype, 'path': path}snapshots: list of {'snapshot': snapshot, 'current': current}Then call: common.print_info(yamlinfo, output=output, fields=fields, values=values)
Study these existing providers:
kvirt/providers/kvm/ - Libvirt (most complete reference, ~4300 lines)kvirt/providers/aws/ - AWS cloud (~2200 lines)kvirt/providers/gcp/ - Google Cloud Platform (~2100 lines)kvirt/providers/kubevirt/ - KubeVirt on Kubernetes (~1900 lines)kvirt/providers/vsphere/ - VMware vSphere (~1900 lines)kvirt/providers/azure/ - Microsoft Azure (~1500 lines)kvirt/providers/ibm/ - IBM Cloud (~1500 lines)kvirt/providers/ovirt/ - oVirt/RHV (~1400 lines)kvirt/providers/openstack/ - OpenStack (~1350 lines)kvirt/providers/proxmox/ - Proxmox VE (~1200 lines)kvirt/providers/hcloud/ - Hetzner Cloud (~550 lines)kvirt/providers/web/ - Web-based provider (~530 lines)kvirt/providers/fake/ - Minimal stub for testing (~20 lines)Not all providers need to implement every method. Focus on:
create, delete, list, info, start, stop, exists, status, ipadd_disk, delete_disk, list_disks, create_pool, delete_pool, list_poolscreate_network, delete_network, list_networks, net_existsvolumes, add_image, delete_imageMethods can return {'result': 'success'} with a print("not implemented") for optional features.