Consider the following use cases.
# |1 | As a Puppet developer code workflow designer ,
I want to attach comments my teams to resources, create document-as-you-go annotations in their code for * Business-process identifier pertaining to configuration items
So I can export a high * Human - level summary readable descriptions of what configuration items
* Responsible party for configuration items |
So that later when Puppet is being managed by is making changes to a catalog system, I can easily look up who, what, and why.|
# |2| As a sysadmin / change reviewer Puppet content developer ,
I want to easily identify at a high level what is changing on my system attach ownership information to resources ,
So I don’t need to understand all the low-level my team can be identified and alerted if Puppet implementation code has a problem applying my resources.|
# |3| As an auditor a change deployment approver ,
When reviewing changes made in a lower-tier environment to decide if it's ok to promote,
I want to review consume a *human high - readable* list level summation for the _meaning_ of changes made applied to a system in the last month ,
So I can verify all audit controls are quickly get a sense of what's being satisfied by done,
Without needing to read low-level Puppet implementation code.|
# |4| As a manager customer receiving a Puppet-managed server as a service ,
I want to review a *human-readable* list of all “stuff” managed by Puppet on a given my system,
So I can understand have some understanding of what Puppet is doing .|
Currently, we don't have a way to attach any kind of self-documenting information to Puppet content, or produce dynamic reports about what Puppet is doing on a target system based on documentation or annotations written for human consumption.
Further, while we have puppet-strings to create self-documenting _code_, we don't have any tooling to create self-documenting _catalogs_ or _reports_—these being examples of artifact outputs produced by the potentially documented code.
h2. Feature Request
Provide a solve for use case #1 above, in support of the rest of the use cases.
h3. Suggestion
A very simple way to solve for this would be to add a new, non-operative metaparameter metaparam , " annotation *metadata* ". As a metaparameter metaparam , annotation "metadata" would be available to specify on any Puppet resource or class. Because it is non-operative and for reporting purposes only, the addition of the metaparameter metaparam would by itself constitute a fully functional foundational delivery of this feature.
The Puppet feature metadata metaparam could be built on by later PE features to produce polished reports, but would not depend on them being delivered such a thing to deliver value today.
For a customer engagement, a proof-of-concept module has been implemented [here|https://github.com/reidmv/reidmv-annotation]. (Note that the module is more complicated than a built-in integration would be).
h2. What about tags?
Tags have two characteristics that make them unsuitable to fully address these use cases.
# Tags cannot contain text written for human consumption, such as descriptions or text-form comments due to not allowing spaces and other special characters.
# Tags propagate. Especially for long-form comments, it may be desirable NOT to propagate them, as duplication and accidental scope escape can be undesirable.
For some use cases the propagation feature of tags may make them more desirable than using metadata. Metadata would be different enough that a meaningful decision could be made about which to use for a given purpose.
h3. Compatibility considerations
Afaik, there are no concerns with regards to backwards compatibility. If an existing class or type already uses a parameter called " annotation metadata ", that will mask/override a metaparameter metaparam by the same name.
Probable Implementation Difficulty: trivial. Improper diff to demonstrate:
{code:diff}
diff --git a/lib/puppet/type.rb b/lib/puppet/type.rb
index 8951854ddd..5f230e3cea 100644
--- a/lib/puppet/type.rb
+++ b/lib/puppet/type.rb
@@ -1714,6 +1714,16 @@ class Type
+ newmetaparam(: annotation metadata ) do
+ desc " A user User -supplied annotation descriptive or administrative information about
+ this resource. The annotation
+ Metadata is non-operative, but will be visible in the
+ node's catalog and can
+ be queried for reporting purposes."
+ end
+ {code}
h3. Naming considerations
Based on the Wikipedia definition of the term, metadata seems to describe exactly the generalized purpose of attaching data to Puppet resources non-operatively, and fit the use cases given above.
https://en.wikipedia.org/wiki/Metadata
The term "annotation" was considered as well, based on looking at similar constructs in Kubernetes. The definitions of both of those nouns more or less matches the use case for the proposed feature, but the natural use and rich explanations for "metadata" are a clear and obvious match to the use case, whereas the rich explanations for "annotation" are less so.
https://en.wikipedia.org/wiki/Annotation |
|
|
