Skip to content

docs: add a troubleshooting section and a table of contents to the README - #170

Merged
tas50 merged 1 commit into
mainfrom
docs/readme-troubleshooting
Aug 30, 2026
Merged

tas50 merged 1 commit into
mainfrom
docs/readme-troubleshooting

Conversation

@tas50

@tas50 tas50 commented Aug 30, 2026

Copy link
Copy Markdown
Member

The README already documents every configuration option with a type and default, and has working kitchen.yml examples 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:

  • Start here — the three commands that answer most questions before you read a single error message: kitchen doctor, kitchen diagnose --all, and kitchen create -l debug. Plus dry_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 that vm_switch matches on name.
  • Missing parent_vhd_folder / Missing parent_vhd_name — including two things the option table does not say: parent_vhd_name is a file name, not a path, and when hyperv_server is set these paths refer to the remote host, so the local pre-flight check is skipped.
  • A create that hangs waiting for an IP address — the three real causes, ordered by how often they are the answer: a private or internal switch with no DHCP behind it, a generation 2 Linux guest that Secure Boot refused to boot, and missing guest integration services.
  • A generation 2 VM that will not boot — Secure Boot's default template only trusts Microsoft bootloaders.
  • Additional disk file already exists — what leaves one behind and where to find it.
  • kitchen destroy cannot 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.
  • WinRM failures against a remote hyperv_serverEnable-PSRemoting, Test-WSMan, and how hyperv_ssl and hyperv_insecure interact.
  • copy_vm_files silently doing nothing — it needs enable_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

$ npx markdownlint-cli2 README.md
Summary: 0 issues in 0 files

$ bundle exec rake test
120 examples, 0 failures

$ bundle exec cookstyle --chefstyle
12 files inspected, no offenses detected

Every in-page anchor in the new Contents list and cross-reference resolves to a real heading.

…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>
@tas50
tas50 merged commit 9f87e02 into main Aug 30, 2026
8 checks passed
@tas50
tas50 deleted the docs/readme-troubleshooting branch August 30, 2026 02:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant