Skip to content

docs: add a troubleshooting section and document how a converge runs - #117

Merged
tas50 merged 2 commits into
mainfrom
docs/readme-troubleshooting
Aug 30, 2026
Merged

tas50 merged 2 commits into
mainfrom
docs/readme-troubleshooting

Conversation

@tas50

@tas50 tas50 commented Aug 30, 2026

Copy link
Copy Markdown
Member

The README documents every option, but it never says what to do when a converge fails — which is when people actually open it. This fills that in.

What changed

A "How it works" section. Five numbered steps: set the LCM, prepare the instance and install gallery modules, stage files into the sandbox, compile the MOF, apply it. Two reasons for it — the option tables below now have somewhere to hang, and a converge that dies partway through can be traced to a named step.

A "Troubleshooting" section. Written from the errors this provisioner can actually produce, not generic advice. It covers the two throw messages we generate on the instance (Failed to find <path>, Failed to create a configuration command <name>), the local ENOENT before the instance is even touched, and the resource that never reached the PSModulePath.

The three I most wanted written down are the ones that fail silently:

  • modules_from_gallery is ignored unless dsc_local_configuration_manager_version is exactly wmf5. On wmf4 nothing installs and nothing is logged.
  • Module style is only detected when the kitchen root contains <directory name>.psd1 — a manifest named after the directory you cloned into. Clone xWebAdministration into a folder called webadmin and it silently falls back to repository style.
  • gallery_name on its own only works if that package source is already registered on the instance.

A Type column on every option table, plus the resolved behaviour that was previously only discoverable by reading the source:

  • which gallery name you actually get with none, one, or both of gallery_name and gallery_uri (PSGallery, testing, or yours)
  • that an unrecognised LCM version falls back to the base WMF 4 settings without warning
  • that the reboot defaults (retry_on_exit_code: [35], max_retries: 3) are only applied if you left Test Kitchen's own defaults alone
  • that a missing modules_path is not an error

A Contents list, matching kitchen-docker.

Also picks up the one-line gemspec spacing fix from #115 so lint is green here too — cookstyle 9 flags it and it currently fails on every PR. Whichever lands first, the other becomes a no-op.

Verification

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

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

$ bundle exec rake test
68 examples, 0 failures

tas50 added 2 commits August 29, 2026 18:53
Cookstyle 9 flags the aligned `gem.add_dependency` calls, so the lint job fails on every pull request. Gemfile.lock is gitignored, so CI resolves a newer cookstyle than a stale local bundle does and this only shows up on a runner.

Signed-off-by: Tim Smith <tim@mondoo.com>
The README covered every option but not what to do when a converge fails,
which is when people actually reach for it. Three additions:

A "How it works" section walking the five phases a converge goes through,
so the options below it have somewhere to hang and so a failure part way
through points at a specific step.

A "Troubleshooting" section covering the failures this provisioner can
actually produce -- the two `throw` messages generated on the instance, the
resource that never reached the PSModulePath, and three that fail silently
and so are the hardest to work out:

- modules_from_gallery is ignored unless the LCM version is exactly "wmf5"
- module style is only detected when the manifest is named after the
  directory you cloned into, not after the module
- gallery_name on its own needs the package source to be registered already

A Type column on every option table, plus the resolved defaults that were
only discoverable by reading the source: which gallery name you get when
you set one, both, or neither of gallery_name and gallery_uri; that an
unrecognised LCM version falls back to WMF 4 without warning; and that the
reboot defaults only apply if you left Test Kitchen's own values alone.

Also adds a Contents list, matching kitchen-docker.

Signed-off-by: Tim Smith <tim@mondoo.com>
@tas50
tas50 merged commit f94d904 into main Aug 30, 2026
8 checks passed
@tas50
tas50 deleted the docs/readme-troubleshooting branch August 30, 2026 02:23
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