[SERVER-1994] Ambiguity in docs about the purpose of environment_timeout Created: 2017/09/25  Updated: 2018/06/08

Status: Accepted
Project: Puppet Server
Component/s: DOCS
Affects Version/s: SERVER 5.1.0
Fix Version/s: None

Type: Improvement Priority: Normal
Reporter: Adam Buxton Assignee: Adam Buxton
Resolution: Unresolved Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Template:
Epic Link: Puppet Environment Handling Improvements
Team: Server
Sub-team: Language
CS Priority: Trivial
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

 Description   

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.

https://puppet.com/docs/puppetserver/5.1/puppet-api/v3/environment_classes.html#changes-class-information-caching-behavior

https://puppet.com/docs/puppet/5.2/environments_creating.html#configuring-environmenttimeout



 Comments   
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:

How long the Puppet master should cache the data it loads from an environment. If present, this will override the value of environment_timeout from puppet.conf.

*

Unless you have a specific reason, we recommend only setting environment_timeout globally, in puppet.conf.

  • We also don’t recommend using any value other than 0 or unlimited.

> "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.

Generated at Thu Nov 14 01:42:42 PST 2019 using JIRA 7.7.1#77002-sha1:e75ca93d5574d9409c0630b81c894d9065296414.