kcli Provider Development

Provider Architecture

Providers are located in kvirt/providers/ as subdirectories. Each provider implements the interface defined in kvirt/providers/sampleprovider.py (class Kbase ).

Required Implementation Steps

1. Create Provider Directory

kvirt/providers/yourprovider/ ├── init.py # Contains your Kyourprovider class └── (optional helpers)

2. Implement the Provider Class

Your class must:

• Set self.conn attribute in init (set to None if backend unreachable)

• Set self.debug from the debug parameter

• Return standardized response dicts from methods

Return Value Pattern:

Success

return {'result': 'success'}

Failure

return {'result': 'failure', 'reason': "VM %s not found" % name}

3. Core Methods to Implement

VM Lifecycle (required):

• create()

• Create VM with all parameters (cpus, memory, disks, nets, etc.)

• start(name)

• Start VM

• stop(name, soft=False)

• Stop VM

• restart(name)

• Restart VM (default calls start)

• delete(name, snapshots=False, keep_disks=False)

• Delete VM

• list()

• Return list of [name, state, ip, source, plan, profile]

• info(name, output, fields, values, vm, debug)

• Return VM details dict

• exists(name)

• Check if VM exists

• status(name)

• Return VM status

• ip(name)

• Return IP string

• clone(old, new, full=False, start=False)

• Clone VM

• export(name, image=None)

• Export VM as image

• console(name, tunnel, tunnelhost, tunnelport, tunneluser, web)

• Graphical console

• serialconsole(name, web)

• Serial console

Storage:

• create_pool(name, poolpath, pooltype, user, thinpool)

• delete_pool(name, full)

• list_pools()

• Return list of pool names

• get_pool_path(pool)

• Get pool path

• add_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 disk

• list_disks()

• Return dict {'diskname': {'pool': poolname, 'path': name}}

• disk_exists(pool, name)

• Check if disk exists

• detach_disks(name)

• Detach all disks from VM

Networking:

• 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 networks

• info_network(name)

• Get network info

• net_exists(name)

• Check if network exists

• network_ports(name)

• List ports on network

• add_nic(name, network, model)

• delete_nic(name, interface)

• update_nic(name, index, network)

• Update NIC

Subnets (cloud providers):

• create_subnet(name, cidr, dhcp, nat, domain, plan, overrides)

• delete_subnet(name, force)

• update_subnet(name, overrides)

• list_subnets()

• Return subnet dict

• info_subnet(name)

• Get subnet info

Images:

• volumes(iso=False, extended=False)

• List available images

• add_image(url, pool, short, cmds, name, size, convert)

• delete_image(image, pool)

Snapshots:

• create_snapshot(name, base)

• Create snapshot

• delete_snapshot(name, base)

• Delete snapshot

• list_snapshots(base)

• List snapshots (returns list)

• revert_snapshot(name, base)

• Revert to snapshot

Update Operations:

• update_metadata(name, metatype, metavalue, append)

• update_memory(name, memory)

• update_cpus(name, numcpus)

• update_start(name, start)

• Set autostart

• update_information(name, information)

• Update info metadata

• update_iso(name, iso)

• Change attached ISO

• update_flavor(name, flavor)

• Change VM flavor

Buckets (object storage):

• create_bucket(bucket, public)

• Create storage bucket

• delete_bucket(bucket)

• Delete bucket

• list_buckets()

• List all buckets

• list_bucketfiles(bucket)

• List files in bucket

• upload_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 groups

DNS:

• reserve_dns(name, nets, domain, ip, alias, force, primary, instanceid)

• list_dns_zones()

• List DNS zones

• dnsinfo(name)

• Return (dnsclient, domain) for VM

Other:

• close()

• Clean up connection

• info_host()

• Return host info dict

• vm_ports(name)

• List ports on VM

• list_flavors()

• Return [[name, numcpus, memory], ...] if platform supports flavors

4. Register Provider in config.py

Add 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)

5. Add Dependencies to setup.py

YOURPROVIDER = ['required-package1', 'required-package2']

Add to extras_require dict:

extras_require={ 'yourprovider': YOURPROVIDER, # ... }

Add to ALL list if needed:

ALL = EXTRAS + AWS + ... + YOURPROVIDER

Info Method Structure

The info() method should build a dict with these keys:

• name , autostart , plan , profile , image , ip , memory , numcpus , creationdate

• nets : 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)

Reference Implementations

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)

Provider Complexity Guide

Not all providers need to implement every method. Focus on:

• Minimum viable: create , delete , list , info , start , stop , exists , status , ip

• Storage: add_disk , delete_disk , list_disks , create_pool , delete_pool , list_pools

• Networking: create_network , delete_network , list_networks , net_exists

• Images: volumes , add_image , delete_image

• Advanced: Snapshots, cloning, export, buckets, security groups (as needed)

Methods can return {'result': 'success'} with a print("not implemented") for optional features.