kcli-configuration

name	kcli-configuration
description	Guides kcli configuration and provider setup. Use when setting up ~/.kcli/config.yml, configuring providers (KVM, AWS, GCP, Azure, etc.), or managing profiles.

kcli Configuration

Configuration Files Location

~/.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

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

# 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

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

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

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

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

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

oVirt/RHV Configuration

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

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)

# 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

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:

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

Validation Commands

# 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):

# Check libvirt is running
sudo systemctl status libvirtd

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

SSH key issues:

# 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:

kcli -d list vm             # Shows provider connection details