docs: add a troubleshooting section and a table of contents to the README - #170
Merged
Merged
Conversation
…ADME The README documents every configuration option and has working examples, but it stopped at the happy path. Hyper-V has a small set of failure modes that catch nearly everyone -- an unelevated shell, no virtual switch, a generation 2 Linux guest that Secure Boot refuses to start, a private switch with no DHCP behind it -- and none of them were written down. Adds a Troubleshooting section covering: - the three commands that answer most questions before reading any error (kitchen doctor, kitchen diagnose --all, kitchen create -l debug), plus dry_run for seeing the generated PowerShell - Get-VM not recognized / access denied - "Failed to find a default VM Switch." - Missing parent_vhd_folder / parent_vhd_name, including that parent_vhd_name is a file name and that the paths are remote when hyperv_server is set - a create that hangs waiting for an IP address - generation 2 VMs that will not boot - "Additional disk file already exists" - a destroy that cannot find a VM that is still running, with the PowerShell to remove it by hand - WinRM failures against a remote hyperv_server - copy_vm_files silently doing nothing without enable_guest_services Also adds a Contents list, matching kitchen-docker. The README is long enough now that jumping to a section beats scrolling. Signed-off-by: Tim Smith <tim@mondoo.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The README already documents every configuration option with a type and default, and has working
kitchen.ymlexamples for each feature. What it did not have was any help for the moment things go wrong — and Hyper-V has a small, very predictable set of failure modes that catch nearly everyone the first time.What is new
A Troubleshooting section covering, in the order a new user hits them:
kitchen doctor,kitchen diagnose --all, andkitchen create -l debug. Plusdry_run: true, which echoes the generated PowerShell instead of running it.The term 'Get-VM' is not recognized/Access denied— the Hyper-V module is missing, or the shell is not elevated. Both are prerequisites and both are easy to miss.Failed to find a default VM Switch.— how to list the switches the host actually has, and thatvm_switchmatches on name.Missing parent_vhd_folder/Missing parent_vhd_name— including two things the option table does not say:parent_vhd_nameis a file name, not a path, and whenhyperv_serveris set these paths refer to the remote host, so the local pre-flight check is skipped.Additional disk file already exists— what leaves one behind and where to find it.kitchen destroycannot find a VM that is still running — Test Kitchen tracks VMs by id, so a lost.kitchen/orphans them. Includes the PowerShell to clean up by hand.hyperv_server—Enable-PSRemoting,Test-WSMan, and howhyperv_sslandhyperv_insecureinteract.copy_vm_filessilently doing nothing — it needsenable_guest_services: true.Also adds a Contents list under the intro, the way kitchen-docker's README has one. At around 400 lines this file is past the point where scrolling is a reasonable way to find the networking options.
Verification
Every in-page anchor in the new Contents list and cross-reference resolves to a real heading.