OLVM AIops

> Disclaimer: This is a community-maintained open-source project and is not affiliated with, endorsed by, or sponsored by Oracle or the oVirt project. "Oracle", "Oracle Linux" and "oVirt" are trademarks of their owners. Source code is publicly auditable at github.com/AIops-tools/OLVM-AIops under the MIT license.

Governed operations for Oracle Linux Virtualization Manager (OLVM) and oVirt 4.5 through the engine REST API — 17 MCP tools, every one wrapped with the bundled @governed_tool harness: a local audit log under ~/.olvm-aiops/, a token/runaway budget guard, and descriptive risk tiers. The engine password is stored encrypted (~/.olvm-aiops/secrets.enc) — never plaintext on disk.

> Read-only in this release. Inventory, health, capacity and diagnosis. Engine actions are asynchronous — the engine answers complete long before a VM or host reaches its target state — so write tools are held back until each can confirm its own outcome.

What This Skill Does

Each diagnosis returns findings ranked worst first. Every finding carries signal (what was measured, quoted from the engine), cause, action and rank.

Quick Install

uv tool install olvm-aiops
olvm-aiops init       # interactive wizard: engine URL, username with profile, CA, encrypted password
olvm-aiops doctor     # login + engine product version

Or as an OpenClaw plugin, which installs this skill and its MCP server together:

openclaw plugins install clawhub:@zw008/olvm-aiops
openclaw skills info olvm-aiops          # expect: Visible to model: yes

Needs uvx on PATH: the MCP server is fetched with uv, pinned to this release.

When to Use This Skill

• "Is anything wrong with my OLVM / oVirt environment?"
• A host is non-operational, non-responsive or stuck installing.
• A storage domain is inactive, low on space, or the engine refuses to create disks.
• A VM is paused, not responding, or will not start.
• "What happened in the last hour?" / "Follow new events."
• Capacity questions: how full each storage domain is, what is over-committed.

Related Skills — Skill Routing

Common Workflows

1. "Is anything wrong right now?"

1. engine_health_rca, then host_health_rca, then storage_capacity_rca, then vm_health_rca.
2. Report findings in rank order and quote each signal. Severity info means in progress or superseded — a host the engine is rebooting after deployment, an old event the host or VM has since recovered from — and low means it is not a fault of the object the finding is on — alert 9000 on a host without fencing hardware, or a guest-agent call that failed on a healthy host. A low finding can still carry work: read its action.
3. For context on a finding, event_list with min_severity="warning", and job_list with status="failed".

2. "Storage is filling up" / "the engine won't create a disk"

1. storage_capacity_rca — critical means free space is below the domain's critical blocker, and the engine refuses new disks and snapshots there.
2. storage_domain_list for free %, used and committed bytes of every domain.
3. vm_list to see which VMs live in the cluster that uses the domain.

3. "This VM is paused / not responding"

1. vm_health_rca — paused VMs point at storage first; an event is superseded when the VM started or was reported back up after it; events older than events_window_hours (default 24) are ignored.
2. vm_get and vm_stats for the VM's host, memory and CPU.
3. event_list with since_minutes=60 for what the engine logged around it.
4. storage_capacity_rca if the VM is paused.

4. "Tell me what changes from now on"

1. event_list once and note the highest index.
2. Next time, event_list with after_index set to that number — the events after it come back oldest first; repeat with the highest index returned while truncated is true.

5. "Will certificates or backups bite us?"

1. engine_health_rca — engine and CA certificate expiry, missing or failed engine backups, clock skew, the engine's own health check.
2. host_health_rca — host certificate expiry and time drift, per host.

Usage Mode

MCP Tools (17 — 15 read, 2 undo)

Any listing with a limit returns returned, limit and a measured truncated. A field the engine did not report is null, never an invented 0.

CLI Quick Reference

olvm-aiops engine health                   # engine findings: health check, clock, certificates, backups
olvm-aiops host health                     # host findings, worst first
olvm-aiops storage capacity                # storage findings, worst first
olvm-aiops vm health                       # VM findings, worst first
olvm-aiops host list --search 'status!=up'
olvm-aiops storage list
olvm-aiops vm list --search 'status=up'
olvm-aiops vm stats <vm-id>
olvm-aiops event list --min-severity warning --since-minutes 60
olvm-aiops event list --after-index 1234
olvm-aiops job list --status failed
olvm-aiops datacenter list
olvm-aiops cluster list
olvm-aiops doctor

Add --json to any list or diagnosis for the full payload. See references/cli-reference.md.

Troubleshooting

"Config file not found"

Run olvm-aiops init, or create ~/.olvm-aiops/config.yaml with a targets list.

"No password for target '<name>'"

Store it with olvm-aiops secret set <name>.

"Master password not set" / "Wrong master password"

Export OLVM_AIOPS_MASTER_PASSWORD for non-interactive use, or run the CLI on a terminal to be prompted.

"Engine SSO login failed … Cannot authenticate user"

The username must include its profile. On an engine where setup enabled Keycloak (the default since 4.5.1) the admin is admin@ovirt@internalsso; without Keycloak it is admin@internal.

"TLS verification failed … IP address mismatch"

The engine answered, but its certificate names the engine's FQDN, not its IP. Use the FQDN in url and point ca_file at the engine CA — this is not a connectivity fault.

"… timed out after 30s"

The engine accepted the connection but did not answer in time. Raise timeout for the target in config.yaml.

"Could not connect to … within 30s"

Nothing answered the connection attempt: the engine is down, a firewall drops the port, or url names the wrong host. A longer timeout will not help.

"Not retried: the last login failed …"

A login was refused less than 60 s ago, so the tool waits instead of trying again — repeated attempts with a wrong password can lock the engine account. Fix the stored password (olvm-aiops secret set <target>) and retry after the wait.

"Not authorized (403)"

The account is valid but its role does not cover the object. Grant a role (for read-only use, ReadOnlyAdmin) in the Administration Portal.

"Not found (404)"

The id is stale — list the parent collection again.

Audit & Safety

The skill reads and records; it does not decide what an agent may change. That belongs to the engine account you connect it with — give it a read-only role and the engine itself refuses anything else.

• Audit is the guarantee, and it is not bypassable. Every call — MCP and CLI alike — is logged to ~/.olvm-aiops/audit.db (relocatable via OLVM_AIOPS_HOME): params (secrets redacted), result, status, duration, and the risk tier.
• The engine password is stored encrypted in ~/.olvm-aiops/secrets.enc (Fernet/AES-128 + scrypt key derivation; chmod 600); the master password is never stored. The SSO token is held only in memory and revoked when the connection closes.
• SSO session ids that the engine prints in login events are redacted before any event text is returned.
• Budget / runaway guard — a safety backstop, not authorization: caps cumulative tool calls and wall-time, and trips on tight polling loops.
• Risk tier is a descriptive label on the audit row derived from risk_level; it gates nothing.

The harness is bundled in the package — no external dependency, no manual setup. See references/setup-guide.md for security details.

Contributing & feature requests

Coverage is intentionally focused. Missing a capability you need, or seeing an engine answer differently from what this tool expects? Open an issue or pull request at github.com/AIops-tools/OLVM-AIops — feature requests, contributions, and comments are all welcome.

License

MIT — github.com/AIops-tools/OLVM-AIops