vm-guest-agent

name

vm_guest_agent

description

Maintains the ansible/roles/guest_agent Ansible role (this skill is named vm_guest_agent, but the actual role directory is guest_agent — see the note in the file body) that detects the hypervisor a system runs under and installs/enables the matching guest agent (qemu-guest-agent, open-vm-tools, hyperv-daemons/WALinuxAgent) as part of the Linux SOE, removing guest-agent packages on bare metal or unrecognized/Nutanix virtualization instead. Use when checking guest-agent presence or state on a virtual machine.

vm_guest_agent

Maintains ansible/roles/guest_agent/ (see the naming-mismatch note under "What to do" below — this skill is named vm_guest_agent, but the actual role directory, and the tag that works against every playbook in this repo, are both guest_agent). See docs/ARCHITECTURE.md for the shared conventions. Unlike most domains, this role branches on detected virtualization type rather than checking one fixed baseline.

ansible/roles/guest_agent/README.md documents this role's full configuration surface (every defaults/main.yml variable, with its original inline comments, rendered as a single reference). Read it before proposing or explaining how to configure this role — it reflects the role's actual current defaults even if a variable summary elsewhere in this file has drifted out of sync with the role.

Baseline

guest_agent_enable (default true) is the only real on/off switch — there is no per-hypervisor mapping variable to override; which package/ service applies is resolved entirely inside tasks/main.yml from ansible_facts.virtualization_type/virtualization_role/system_vendor, not from anything in defaults/main.yml. guest_agent_remove_firmware (default true) separately controls whether VM firmware packages (*firmware* families) get removed on guest hosts.

Actual behavior by detected virtualization (verified directly against tasks/main.yml, not assumed):

• virtualization_role != "guest" (bare metal, or guest_agent_enable: false) → actively removes hyperv*, open-vm-tools, qemu-guest-agent, spice-vdagent, WALinuxAgent if present. This is enforcement, not a passive [INFO] report — a host that used to be a VM and is now bare metal gets cleaned up on the next run.
• system_vendor == "Nutanix" (AHV) → all guest-agent packages are removed, none installed. Nutanix AHV doesn't use any of the packages this role manages, so this is deliberate, not an oversight.
• virtualization_type == "kvm" (and not Nutanix) → installs qemu-guest-agent, enables + starts qemu-guest-agent.service; removes the other platforms' packages first.
• virtualization_type == "VirtualPC" (Hyper-V/Azure) → installs hyperv-daemons and WALinuxAgent, enables + starts waagent.service; removes the other platforms' packages first.
• virtualization_type == "VMware" → installs open-vm-tools, enables + starts vmtoolsd.service; removes the other platforms' packages first.
• Any other guest type (not kvm/VirtualPC/VMware, not Nutanix) → removes all known guest packages, installs nothing — there's no generic fallback agent, unlike what a naive reading of "detects and installs the matching agent" might suggest.

What to do

Known naming mismatch (pre-existing, not introduced by this change): the actual role directory and the tag used by configure_rhel.yml's roles: list are both guest_agent, not vm_guest_agent — see .claude/skills/guest_agent/SKILL.md and the note in .claude/skills/soe/SKILL.md's domain table ("role dir is guest_agent, not vm_guest_agent"). --tags vm_guest_agent will report "did not match any tags" against every playbook in this repo. Use --tags guest_agent (see that skill) until this mismatch is resolved, or flag it to a human operator as something worth fixing via the branch + PR workflow.

Audit: ansible-playbook ansible/configure_rhel.yml --tags guest_agent --check --diff

Remediate: same command without --check, after explicit user approval.

Propose a change to the role itself (e.g. adding a new hypervisor to the agent_packages/agent_services dicts in tasks/main.yml): never commit directly. On a branch named soe/guest_agent/<short-desc> (the role's real name — see the naming-mismatch note above), edit ansible/roles/guest_agent/, validate locally (--syntax-check, ansible-lint roles/guest_agent/, --check --diff), push, and open a PR titled [guest_agent] <what changed> with the --check --diff output in the body — then stop for human review. See docs/ARCHITECTURE.md's "Contribution workflow".

Notes

• The per-hypervisor package/service mapping is hardcoded in tasks/main.yml (agent_packages/agent_services dicts), not exposed as a defaults/main.yml variable — there's nothing to override via -e or group_vars for a new hypervisor type, only a role code change.
• If ansible_facts.virtualization_type is something not covered by the role's dicts (kvm, VirtualPC, VMware) but the user says the host is a VM, ask rather than assuming — on an uncovered guest type the role removes every known guest package and installs nothing, which could surprise someone expecting some agent to end up installed.