Make salt.states.virt consistent with salt.modules.virt and add virt.reset

[ngaugler]

salt.states.virt has inconsistencies making it difficult to appropriately interface with libvirt. Within libvirt one can perform both a soft and hard shutdown or reboot/reset of a guest domain. The module salt.modules.virt functions seem to appropriately reflect these features, but the state salt.states.virt functions are inconsistent and intermingle terminology. Documentation is also inconsistent as well adding more confusion.

Below is a mapping showing some basic inconsistencies:

Type	Task	libvirt	Module	State
soft	shutdown	shutdown	salt.modules.virt.shutdown	salt.states.virt.stopped
hard	power off	destroy	salt.modules.virt.stop	salt.states.virt.powered_off
soft	reboot	reboot	salt.modules.virt.reboot	salt.states.virt.rebooted
hard	reset	reset	salt.modules.virt.reset	N/A

It's inconsistency makes it difficult to anticipate what command will be sent to libvirt. It's so difficult that even the documentation for salt.states.virt.powered_off shows the wrong example in the SLS YAML and lists virt.stopped https://docs.saltproject.io/en/latest/ref/states/all/salt.states.virt.html#salt.states.virt.powered_off

It would be easy to add the missing salt.states.virt.reset function, but ideally this entire state would be revamped to be consistent with the module. Also, the documentation should be fixed to reflect the right command.

[welcome[bot]]

Hi there! Welcome to the Salt Community! Thank you for making your first contribution. We have a lengthy process for issues and PRs. Someone from the Core Team will follow up as soon as possible. In the meantime, here’s some information that may help as you continue your Salt journey.
Please be sure to review our Code of Conduct. Also, check out some of our community resources including:

• Community Wiki
• Salt’s Contributor Guide
• Join our Community Slack
• IRC on LiberaChat
• Salt Project YouTube channel
• Salt Project Twitch channel

There are lots of ways to get involved in our community. Every month, there are around a dozen opportunities to meet with other contributors and the Salt Core team and collaborate in real time. The best way to keep track is by subscribing to the Salt Community Events Calendar.
If you have additional questions, email us at saltproject@vmware.com. We’re glad you’ve joined our community and look forward to doing awesome things with you!

[whytewolf]

Thank you for the report. so. state modules always differ greatly from the execution modules, by design. they are not meant to be one to one comparisons. states are meant to be a description of how the thing should be. it uses the execution modules to get to that state. reset and reboot are actions taken, not states. they should be handled by a mod_watch function.

take the service state as an example of how this should be.

there is no service state function for restart or reload. there is a mod_watch that gets triggered when watched states happen. that triggers a restart or reload.

So there is work to be done. the documentation being one piece, that definitely needs updated.
and the creation of a mod_watch function to handle reset and reboot.