kcli Configuration

Configuration Files Location

code

~/.kcli/
├── config.yml           # Main configuration (clients/providers)
├── profiles.yml         # VM profiles (optional, can be in config.yml)
├── id_rsa / id_rsa.pub  # SSH keys for VM access
├── id_ed25519           # Alternative SSH key
└── clusters/            # Cluster state (created by kcli)

Basic config.yml Structure

yaml

default:
  client: localhost       # Default provider to use
  numcpus: 2
  memory: 512
  pool: default
  nets:
    - default
  disks:
    - size: 10

# Provider definitions
localhost:
  type: kvm
  host: 127.0.0.1

Provider Types

Type	Description	Required Fields
`kvm`	Local/remote libvirt	host
`aws`	Amazon Web Services	access_key_id, access_key_secret, region
`gcp`	Google Cloud Platform	credentials, project, zone
`azure`	Microsoft Azure	subscription_id, credentials (file)
`kubevirt`	VMs on Kubernetes	context, host
`openstack`	OpenStack cloud	auth_url, user, password, project
`ovirt`	oVirt/RHV	host, user, password, datacenter
`vsphere`	VMware vSphere	host, user, password, datacenter
`proxmox`	Proxmox VE	host, user, password
`hcloud`	Hetzner Cloud	token
`ibm`	IBM Cloud	iam_api_key, region, vpc

KVM/Libvirt Configuration

yaml

# Local libvirt
localhost:
  type: kvm
  host: 127.0.0.1
  pool: default

# Remote libvirt via SSH
remote-kvm:
  type: kvm
  host: 192.168.1.100
  protocol: ssh           # ssh (default), tcp, or tls
  user: root              # SSH user
  pool: default
  # url: qemu+ssh://root@host/system  # Or custom URI

AWS Configuration

yaml

myaws:
  type: aws
  access_key_id: AKIAIOSFODNN7EXAMPLE
  access_key_secret: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  region: us-east-1
  keypair: mykey          # EC2 key pair name

GCP Configuration

yaml

mygcp:
  type: gcp
  credentials: ~/service-account.json   # Service account JSON
  project: my-project-id
  zone: us-central1-a
  region: us-central1     # Optional, derived from zone

Azure Configuration

yaml

myazure:
  type: azure
  subscription_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  credentials: ~/.azure/credentials.json
  # Or use environment: AZURE_AUTH_LOCATION
  location: eastus
  resource_group: my-rg   # Optional, created if needed

KubeVirt Configuration

yaml

mykubevirt:
  type: kubevirt
  context: my-k8s-context   # kubectl context
  host: api.cluster.local   # API server for SSH tunneling
  pool: my-storageclass     # StorageClass name
  multus: true              # Use Multus CNI
  cdi: true                 # Use CDI for images

OpenStack Configuration

yaml

myopenstack:
  type: openstack
  auth_url: https://openstack:5000/v3
  user: admin
  password: secret
  project: myproject
  domain: Default

oVirt/RHV Configuration

yaml

myovirt:
  type: ovirt
  host: ovirt-engine.local
  user: admin@internal
  password: secret
  datacenter: Default
  cluster: Default
  pool: DataDomain
  ca_file: ~/ovirt.pem      # Engine CA certificate

Default Section Options

yaml

default:
  # Client selection
  client: localhost

  # Compute
  numcpus: 2
  memory: 512               # MB
  cpumodel: host-model
  nested: true              # Nested virtualization

  # Storage
  pool: default
  disks:
    - size: 10
  diskinterface: virtio
  diskthin: true

  # Network
  nets:
    - default
  reservedns: false
  reservehost: false
  reserveip: false

  # OS/Cloud-init
  cloudinit: true
  keys: []                  # SSH public keys
  cmds: []                  # Post-boot commands
  files: []                 # Files to inject

  # Access
  tunnel: false             # SSH tunneling for console
  insecure: false           # Ignore SSH host keys
  enableroot: true          # Allow root SSH

  # Metadata
  storemetadata: false
  planview: false

Profiles (profiles.yml or in config.yml)

yaml

# In ~/.kcli/profiles.yml or config.yml profiles section
small:
  numcpus: 1
  memory: 1024
  disks:
    - size: 10

medium:
  numcpus: 2
  memory: 2048
  disks:
    - size: 20

large:
  numcpus: 4
  memory: 4096
  disks:
    - size: 40
    - size: 100

webserver:
  image: centos9stream
  numcpus: 2
  memory: 4096
  nets:
    - default
  cmds:
    - dnf -y install nginx
    - systemctl enable --now nginx
  base: medium              # Inherit from another profile

Multiple Clients

yaml

default:
  client: local-kvm         # Default client

local-kvm:
  type: kvm
  host: 127.0.0.1

remote-kvm:
  type: kvm
  host: 192.168.1.100

myaws:
  type: aws
  access_key_id: ...
  access_key_secret: ...
  region: us-east-1

Switch clients:

bash

kcli switch local-kvm       # Change default
kcli -C myaws list vm       # Use specific client

Validation Commands

bash

# List configured clients
kcli list client

# Check client connectivity
kcli list host

# Info about current client
kcli info host

# Switch default client
kcli switch <client>

# Test with specific client
kcli -C <client> list vm

Environment Variables

Some values can come from environment:

•GOOGLE_APPLICATION_CREDENTIALS - GCP credentials path
•AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY - AWS credentials
•AZURE_AUTH_LOCATION - Azure credentials path
•OS_* - OpenStack credentials (standard OS_ vars)

Troubleshooting

Connection refused (KVM):

bash

# Check libvirt is running
sudo systemctl status libvirtd

# Test virsh connection
virsh -c qemu:///system list

SSH key issues:

bash

# Generate kcli SSH key
ssh-keygen -t rsa -N '' -f ~/.kcli/id_rsa

# Or use ed25519
ssh-keygen -t ed25519 -N '' -f ~/.kcli/id_ed25519

Debug mode:

bash

kcli -d list vm             # Shows provider connection details