Repository navigation
docs: add a troubleshooting section and document how a converge runs - #117
Merged
Merged
Conversation
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>
This was referenced Aug 30, 2026
This was referenced Aug 30, 2026
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 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
throwmessages we generate on the instance (Failed to find <path>,Failed to create a configuration command <name>), the localENOENTbefore the instance is even touched, and the resource that never reached thePSModulePath.The three I most wanted written down are the ones that fail silently:
modules_from_galleryis ignored unlessdsc_local_configuration_manager_versionis exactlywmf5. Onwmf4nothing installs and nothing is logged.<directory name>.psd1— a manifest named after the directory you cloned into. ClonexWebAdministrationinto a folder calledwebadminand it silently falls back to repository style.gallery_nameon 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:
gallery_nameandgallery_uri(PSGallery,testing, or yours)retry_on_exit_code: [35],max_retries: 3) are only applied if you left Test Kitchen's own defaults alonemodules_pathis not an errorA 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