Issue #17156 has been updated by Nick Fagerlund.
So I've thought about this a little more.
Principles:
* Puppet doc, in its "reference" mode, should only document components that are
**installed.**
* Plugins cached by puppet agent during a run aren't installed; they're a
temporary, volatile reflection of what's installed on the master.
* But plugins in every environment on the master are all installed! And our
solution for reading everything in every environment was to copy it all to the
master's libdir.
* Dunno what to say about puppet apply except that it sort of cares about
environments, but in practice it really doesn't.
So in conclusion:
* Having puppet doc read plugins from the **agent's** libdir is wrong.
* Having it read plugins from the **master's** libdir is right.
* Obviously the results will be stupid if the agent and the master share a
libdir, just like everything else gets stupid.
* And what it's probably actually doing is using the libdir from the `[user]`
config block, which is approximately as wrong as using the agent's libdir.
So given that... I suspect it makes sense to switch puppet doc to master run
mode. That way, the theoretical users who're generating docs for their custom
types and functions will get the correct behavior pretty much no matter what.
* If they're doing this on the puppet master, it'll document all plugins from
all environments, as expected.
* If they're doing it on a puppet apply standalone node, most users are
probably putting their settings in `[main]` instead of `[user]` (that's a
hunch) and leaving `[master]` blank, so since master has no secret sauce
anymore, they'll get correct behavior too.
* And if I'm right in my hunch, behavior will be correct for the "module
docs" mode as well as the "reference" mode. If I'm wrong, there are some rare
users who will get a surprise, but it won't be a huge one.
* If they're doing it on an arbitrary agent, they're doing it wrong.
* Docs team's use case remains idiosyncratic, and that's fine, we'll just blank
out the libdir on the command line.
Does that sound right? Also I may be overthinking this, as we're probably the
only ones who use "reference" mode. :/
----------------------------------------
Bug #17156: Regression: Can't restrict the plugins loaded by puppet doc with
--modulepath in 3.0.1
https://projects.puppetlabs.com/issues/17156#change-74996
Author: Nick Fagerlund
Status: Accepted
Priority: Normal
Assignee:
Category: settings
Target version: 3.x
Affected Puppet version: 3.0.1
Keywords: regression settings
Branch:
The docs team uses `puppet doc --reference` to generate certain docs for the
site, and we have to use `--modulepath /tmp/nothing` or something to exclude
non-core resource types and functions from our personal modules. This worked
through 3.0.0 and broke in 3.0.1.
The changed behavior:
* In 3.0.0, puppet doc would ONLY load plugins from the modulepath; the
contents of the agent's libdir had no effect, and changing the modulepath
swapped out the entire set of plugins available.
* In 3.0.1, puppet doc loads plugins from both the modulepath AND the libdir.
So if puppet agent has ever run, puppet doc will keep loading plugins until you
delete the libdir.
Git bisect tracks the change to commit:144bb76a7e825a221fd1cb5a20728c8cf5c03264
-- "(#16637) Fix default confdir and vardir with puppet master as normal user."
The command to test this with is `puppet doc --reference function --modulepath
/tmp/nothing` -- make sure you have something like puppetlabs-stdlib in your
modulepath when testing, so that the function reference gets nice and messy.
--
You have received this notification because you have either subscribed to it,
or are involved in it.
To change your notification preferences, please click here:
http://projects.puppetlabs.com/my/account
--
You received this message because you are subscribed to the Google Groups
"Puppet Bugs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/puppet-bugs?hl=en.
