OpenParable
Skip to content
← Back to skills

Kcli Provider Development

Development
kcli-provider-development

Kcli Provider Development is an Agent Skill for development published in the karmab/kcli repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guides implementation of new virtualization providers for kcli. Use when adding support for a new cloud platform, hypervisor, or infrastructure provider.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/karmab/kcli/blob/HEAD/skills/kcli-provider-development/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/kcli-provider-development, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

  1. Minimum viable: create, delete, list, info, start, stop, exists, status, ip
  2. Storage: add_disk, delete_disk, list_disks, create_pool, delete_pool, list_pools
  3. Networking: create_network, delete_network, list_networks, net_exists
  4. Images: volumes, add_image, delete_image
  5. Advanced: Snapshots, cloning, export, buckets, security groups (as needed)

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