Environments and Puppet's HTTPS interface

Included in Puppet Enterprise 2016.5. A newer version is available; see the version menu above for details.

Puppet’s environments interact in several ways with Puppet’s HTTPS interface.

Environments are embedded in Puppet’s HTTPS requests

Puppet’s agent and master applications communicate via an HTTPS API. Most of the HTTPS URLs used today by Puppet agent include an environment. See the HTTP API reference for details about how to provide environments in requests.

For some endpoints, making a request “in” an environment is meaningless; for others, it influences which modules and manifests the configuration data will come from. Regardless, the API requires an environment to be provided.

Endpoints where the requested environment can be overridden by the ENC/node terminus:

  • Catalog — For this endpoint, the environment is just a request, as described above in the section on assigning nodes to environments; if the ENC specifies an environment for the node, it will override the environment in the request.

Endpoints where the requested environment is always used:

  • File content and file metadata — Files in modules, including plugins like custom facts and resource types, will always be served from the requested environment. Puppet agent has to account for this when fetching files; it does so by fetching its node object (see “node” below), then resetting the environment it will request to whatever the ENC specified and using that new environment for all subsequent requests. (Since custom facts might influence the decision of the ENC, the agent will repeat this process up to three times before giving up.)
  • Resource type — Puppet agent doesn’t use this; it’s just for extensions. The Puppet master will always respond with information for the requested environment.

Endpoints where environment makes no difference:

  • File Bucket File — There’s only one filebucket.
  • Report — Reports already contain environment info, and each report handler can decide what, if anything, to do with it.
  • Node — Puppet agent uses this to learn whether the master’s ENC has overridden its preferred environment. Theoretically, a node terminus could use the environment of the first node object request to decide whether to override the environment, but we’re not aware of anyone doing that and there wouldn’t seem to be much point to it.
  • Status
  • Certificate, certificate signing request, certificate status, and certificate revocation list — The CA doesn’t differ by environment.)

Controlling HTTPS access based on environment

The Puppet master’s auth.conf file can use the environment of a request to help decide whether to authorize a request. This generally isn’t necessary or useful, but it’s there if the need arises. See the auth.conf documentation for details.

You can query environment info via the master’s HTTP API

If you are extending Puppet and need a way to query information about the available environments, you can do this via the environments endpoint.

↑ Back to top