OpenParable
Skip to content
← Back to skills

Kcli Ksushy

Apps & Automation
kcli-ksushy

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

Guides interaction with kcli VMs via ksushy (Redfish emulator). Use when booting, stopping, or managing baremetal-like VMs through the Redfish API, deploying the ksushy service, or working with sushy/redfish in general.

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-ksushy/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/kcli-ksushy, 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 ksushy (Redfish Emulation)

ksushy provides a REST interface to interact with VMs using Redfish. It offers functionality similar to sushy-emulator but extends it to more providers (typically vSphere, KubeVirt, and oVirt) and through more friendly URLs.

Requirements

ksushy is bundled within kcli. SSL support requires installing cherrypy and pyopenssl manually.

Deploying the ksushy service

kcli create sushy-service

This creates a systemd unit listening on port 9000. The following environment variables are supported:

VariableDescription
KSUSHY_LISTEN_PORTUse a specific port
KSUSHY_DEBUGEnable debug
KSUSHY_USERUsername for basic authentication
KSUSHY_PASSWORDPassword for basic authentication
KSUSHY_BOOTONCEEnable bootonce

Determining the ksushy endpoint

The ksushy endpoint is derived from the hypervisor hosting the VMs, NOT from the VM itself or the local machine hostname:

  1. Identify the current hypervisor with kcli list hosts (look for the Current column).
  2. Get the hypervisor's FQDN or IP with kcli info host <host_name> (use the host: field), or look it up in ~/.kcli/config.yml. If the host is a short name, check ~/.ssh/config for the actual Hostname (IP or FQDN).
  3. The ksushy base URL is https://<host_ip>:9000/redfish/v1/Systems.

API Structure

Systems are organized by provider under /redfish/v1/Systems/<provider>/<vm_name>.

The <provider> matches the provider name as defined in ~/.kcli/config.yml. For local libvirt VMs, the provider is local.

# List providers
curl -ks https://<host>:9000/redfish/v1/Systems

# List VMs under the local (libvirt) provider
curl -ks https://<host>:9000/redfish/v1/Systems/local

# Query a VM on a different provider
curl -ks https://<host>:9000/redfish/v1/Systems/myotherprovider/mynode

# Get info on a specific VM
curl -ks https://<host>:9000/redfish/v1/Systems/local/<vm_name>

VM Power Operations

Typical redfish operations (start, stop, info, listing NICs) are supported for all providers.

# Power on a VM
curl -ks https://<host>:9000/redfish/v1/Systems/local/<vm_name>/Actions/ComputerSystem.Reset \
  -H "Content-Type: application/json" \
  -d '{"ResetType": "On"}'

# Power off a VM
curl -ks https://<host>:9000/redfish/v1/Systems/local/<vm_name>/Actions/ComputerSystem.Reset \
  -H "Content-Type: application/json" \
  -d '{"ResetType": "ForceOff"}'

# Restart a VM
curl -ks https://<host>:9000/redfish/v1/Systems/local/<vm_name>/Actions/ComputerSystem.Reset \
  -H "Content-Type: application/json" \
  -d '{"ResetType": "ForceRestart"}'

Virtual Media (ISO)

ISO plugging is only supported on virtualization providers.

# Insert ISO
curl -ks https://<host>:9000/redfish/v1/Systems/local/<vm_name>/VirtualMedia/Cd/Actions/VirtualMedia.InsertMedia \
  -H "Content-Type: application/json" \
  -d '{"Image": "http://<iso_server>/<image>.iso"}'

# Eject ISO
curl -ks https://<host>:9000/redfish/v1/Systems/local/<vm_name>/VirtualMedia/Cd/Actions/VirtualMedia.EjectMedia \
  -H "Content-Type: application/json" -d '{}'

Authentication

When the service is deployed with KSUSHY_USER and KSUSHY_PASSWORD, access is secured through basic authentication:

curl -ks -u myuser:mypassword https://<host>:9000/redfish/v1/Systems/local/<vm_name>

Typical Workflow

  1. Create baremetal-like VMs with kcli:

    kcli create vm -P start=false -P memory=20480 -P numcpus=16 -P 'disks=[200]' -P uefi=true -P 'nets=[default]' -c 3 mycluster
    
  2. Determine the ksushy endpoint (see above).

  3. Boot VMs via redfish:

    for i in 0 1 2; do
      curl -ks https://<host>:9000/redfish/v1/Systems/local/mycluster-$i/Actions/ComputerSystem.Reset \
        -H "Content-Type: application/json" \
        -d '{"ResetType": "On"}'
    done