[SERVER-1994] Ambiguity in docs about the purpose of environment_timeout Created: 2017/09/25 Updated: 2018/06/08
|Affects Version/s:||SERVER 5.1.0|
|Reporter:||Adam Buxton||Assignee:||Adam Buxton|
|Remaining Estimate:||Not Specified|
|Time Spent:||Not Specified|
|Original Estimate:||Not Specified|
|Epic Link:||Server-side Environment Handling Improvements|
|CS Frequency:||1 - 1-5% of Customers|
|CS Severity:||2 - Annoyance|
|CS Business Value:||1 - ?|
|CS Impact:||These docs are confusing. It may be better to just remove them. Attempting to explain the differences between the two is incredibly confusing even to people who know the code bases involved.|
|QA Risk Assessment:||Needs Assessment|
When read together the following two links create an ambiguity as to what the environment_timeout does and whether the resource api is still in use? it is documented as not in use, but referred to in the document as being the subject of the environment_timeout!
Needs clarification, was asked in Puppet Slack and confused me as i thought i knew the answer.
|Comment by Maggie Dreyer [ 2018/02/08 ]|
Garrett Guillotte would mind looking into this?
|Comment by Garrett Guillotte [ 2018/02/08 ]|
I last touched the server docs on this in March 2016 with JB's feedback, so I can't speak to their content and how it might have changed since, and JB's left Puppet. So anything I say here really needs another dev to double-check me, because my memory is at best incomplete on this.
tl;dr: environment_timeout predates the environment classes API, which is only available in Puppet Server. When set, environment_timeout has a similar purpose but accomplishes it differently depending on the API in use.
The Server doc you linked to describes those functional differences, and is targeted at users migrating from the deprecated API to the supported API so they understand how they're different, and how to enable its functionality via the environment-class-cache-enabled setting.
The Puppet doc you linked to describes the setting's usage, is targeted more broadly at Puppet users who might not be using Puppet Server (and therefore might not have access to the environment classes API), and describes its functionality at a higher level. It also doesn't appear to have been updated substantially since Puppet 4.10 and could use additional clarification about how it interacts differently with or without Puppet Server.
> "what the environment_timeout does"
That's defined in the environment.conf docs, which are the link target (https://puppet.com/docs/puppet/5.3/config_file_environment.html#environmenttimeout) of the "environment_timeout" text in that Server doc:
> "whether the resource api is still in use"
The resource type API is deprecated but AFAIK not removed yet. IIRC the environment classes API wasn't a complete replacement for the resource type API.
So yes, it is still in use, but users should move away from it for use cases that can be supported by the environment classes API.
> "it is documented as not in use, but referred to in the document as being the subject of the environment_timeout!"
Can you be more explicit here? I'm not seeing this in the content, but I also don't understand the problem. I'm also unfortunately not able to figure out which of the two products or docs "it" and "the document" refer to.
From what I do understand, hopefully this helps:
The section of that Server document you linked to, https://puppet.com/docs/puppetserver/5.1/puppet-api/v3/environment_classes.html#changes-class-information-caching-behavior, is a subsection of the parent section "Changes in the environment classes API", which details how the environment classes API differs from the deprecated resource type API, for the purposes of migrating away from the resource type API.
environment_timeout as a setting predates the environment class API. Its value is used by both the resource type API and environment class API, and it serves the same purpose for both APIs, but goes about that in functionally different ways. Those differences are described in the "Changes class information caching behavior" subsection.
|Comment by Garrett Guillotte [ 2018/02/08 ]|
Adam Buxton can you provide more context about how this came up? I know this ticket is now months old and understand if you can't. If users who aren't already using the resource types API are winding up in the Server docs about migrating from it, I can understand the confusion.
I'll also add a link from the Puppet doc you mentioned to the environment_timeout definition in config_file_environment, and be more explicit on both pages about the setting's relationship to Puppet Server's APIs.