Indirection Reference

This page is autogenerated; any changes will get overwritten

About Indirection

Puppet’s indirector support pluggable backends (termini) for a variety of key-value stores (indirections). Each indirection type corresponds to a particular Ruby class (the “Indirected Class” below) and values are instances of that class. Each instance’s key is available from its name method. The termini can be local (e.g., on-disk files) or remote (e.g., using a REST interface to talk to a puppet master).

An indirector has five methods, which are mapped into HTTP verbs for the REST interface:

  • find(key) - get a single value (mapped to GET or POST with a singular endpoint)
  • search(key) - get a list of matching values (mapped to GET with a plural endpoint)
  • head(key) - return true if the key exists (mapped to HEAD)
  • destroy(key) - remove the key and value (mapped to DELETE)
  • save(instance) - write the instance to the store, using the instance’s name as the key (mapped to PUT)

These methods are available via the indirection class method on the indirected classes. For example:

foo_cert = Puppet::SSL::Certificate.indirection.find('foo.example.com')

At startup, each indirection is configured with a terminus. In most cases, this is the default terminus defined by the indirected class, but it can be overridden by the application or face, or overridden with the route_file configuration. The available termini differ for each indirection, and are listed below.

Indirections can also have a cache, represented by a second terminus. This is a write-through cache: modifications are written both to the cache and to the primary terminus. Values fetched from the terminus are written to the cache.

Interaction with REST

REST endpoints have the form /{prefix}/{version}/{indirection}/{key}?environment={environment}, where the indirection can be singular or plural, following normal English spelling rules. On the server side, REST responses are generated from the locally-configured endpoints.

Indirections and Termini

Below is the list of all indirections, their associated terminus classes, and how you select between them.

In general, the appropriate terminus class is selected by the application for you (e.g., puppet agent would always use the rest terminus for most of its indirected classes), but some classes are tunable via normal settings. These will have terminus setting documentation listed with them.

catalog

  • Indirected Class: Puppet::Resource::Catalog
  • Terminus Setting: catalog_terminus

compiler terminus

Compiles catalogs on demand using Puppet’s compiler.

json terminus

Store catalogs as flat files, serialized using JSON.

msgpack terminus

Store catalogs as flat files, serialized using MessagePack.

rest terminus

Find resource catalogs over HTTP via REST.

store_configs terminus

Part of the “storeconfigs” feature. Should not be directly set by end users.

yaml terminus

Store catalogs as flat files, serialized using YAML.

certificate

This indirection wraps an OpenSSL::X509::Certificate object, representing a certificate (signed public key). The indirection key is the certificate CN (generally a hostname).

  • Indirected Class: Puppet::SSL::Certificate

ca terminus

Manage the CA collection of signed SSL certificates on disk.

disabled_ca terminus

Manage SSL certificates on disk, but reject any remote access to the SSL data store. Used when a master has an explicitly disabled CA to prevent clients getting confusing ‘success’ behaviour.

file terminus

Manage SSL certificates on disk.

rest terminus

Find certificates over HTTP via REST.

certificate_request

This indirection wraps an OpenSSL::X509::Request object, representing a certificate signing request (CSR). The indirection key is the certificate CN (generally a hostname).

  • Indirected Class: Puppet::SSL::CertificateRequest

ca terminus

Manage the CA collection of certificate requests on disk.

disabled_ca terminus

Manage SSL certificate requests on disk, but reject any remote access to the SSL data store. Used when a master has an explicitly disabled CA to prevent clients getting confusing ‘success’ behaviour.

file terminus

Manage the collection of certificate requests on disk.

memory terminus

Store certificate requests in memory. This is used for testing puppet.

rest terminus

Find and save certificate requests over HTTP via REST.

certificate_revocation_list

This indirection wraps an OpenSSL::X509::CRL object, representing a certificate revocation list (CRL). The indirection key is the CA name (usually literally ca).

  • Indirected Class: Puppet::SSL::CertificateRevocationList

ca terminus

Manage the CA collection of certificate requests on disk.

disabled_ca terminus

Manage SSL certificate revocation lists, but reject any remote access to the SSL data store. Used when a master has an explicitly disabled CA to prevent clients getting confusing ‘success’ behaviour.

file terminus

Manage the global certificate revocation list.

rest terminus

Find and save certificate revocation lists over HTTP via REST.

certificate_status

This indirection represents the host that ties a key, certificate, and certificate request together. The indirection key is the certificate CN (generally a hostname).

  • Indirected Class: Puppet::SSL::Host

file terminus

Manipulate certificate status on the local filesystem. Only functional on the CA.

rest terminus

Sign, revoke, search for, or clean certificates & certificate requests over HTTP.

data_binding

Where to find external data bindings.

  • Indirected Class: Puppet::DataBinding
  • Terminus Setting: data_binding_terminus

hiera terminus

Retrieve data using Hiera.

none terminus

A Dummy terminus that always throws :no_such_key for data lookups.

facts

  • Indirected Class: Puppet::Node::Facts
  • Terminus Setting: facts_terminus

facter terminus

Retrieve facts from Facter. This provides a somewhat abstract interface between Puppet and Facter. It’s only somewhat abstract because it always returns the local host’s facts, regardless of what you attempt to find.

memory terminus

Keep track of facts in memory but nowhere else. This is used for one-time compiles, such as what the stand-alone puppet does. To use this terminus, you must load it with the data you want it to contain.

network_device terminus

Retrieve facts from a network device.

rest terminus

Find and save facts about nodes over HTTP via REST.

store_configs terminus

Part of the “storeconfigs” feature. Should not be directly set by end users.

yaml terminus

Store client facts as flat files, serialized using YAML, or return deserialized facts from disk.

file_bucket_file

  • Indirected Class: Puppet::FileBucket::File

file terminus

Store files in a directory set based on their checksums.

rest terminus

This is a REST based mechanism to send/retrieve file to/from the filebucket

selector terminus

Select the terminus based on the request

file_content

  • Indirected Class: Puppet::FileServing::Content

file terminus

Retrieve file contents from disk.

file_server terminus

Retrieve file contents using Puppet’s fileserver.

http terminus

Retrieve file contents from a remote HTTP server.

rest terminus

Retrieve file contents via a REST HTTP interface.

selector terminus

Select the terminus based on the request

file_metadata

  • Indirected Class: Puppet::FileServing::Metadata

file terminus

Retrieve file metadata directly from the local filesystem.

file_server terminus

Retrieve file metadata using Puppet’s fileserver.

http terminus

Retrieve file metadata from a remote HTTP server.

rest terminus

Retrieve file metadata via a REST HTTP interface.

selector terminus

Select the terminus based on the request

key

This indirection wraps an `OpenSSL::PKey::RSA object, representing a private key. The indirection key is the certificate CN (generally a hostname).

  • Indirected Class: Puppet::SSL::Key

ca terminus

Manage the CA’s private key on disk. This terminus works with the CA key only, because that’s the only key that the CA ever interacts with.

disabled_ca terminus

Manage the CA private key, but reject any remote access to the SSL data store. Used when a master has an explicitly disabled CA to prevent clients getting confusing ‘success’ behaviour.

file terminus

Manage SSL private and public keys on disk.

memory terminus

Store keys in memory. This is used for testing puppet.

node

Where to find node information. A node is composed of its name, its facts, and its environment.

  • Indirected Class: Puppet::Node
  • Terminus Setting: node_terminus

exec terminus

Call an external program to get node information. See the External Nodes page for more information.

ldap terminus

Search in LDAP for node configuration information. See the LDAP Nodes page for more information. This will first search for whatever the certificate name is, then (if that name contains a .) for the short name, then default. Requires ruby-ldap with MRI ruby or jruby-ldap with puppetserver/jruby

memory terminus

Keep track of nodes in memory but nowhere else. This is used for one-time compiles, such as what the stand-alone puppet does. To use this terminus, you must load it with the data you want it to contain; it is only useful for developers and should generally not be chosen by a normal user.

msgpack terminus

Store node information as flat files, serialized using MessagePack, or deserialize stored MessagePack nodes.

plain terminus

Always return an empty node object. Assumes you keep track of nodes in flat file manifests. You should use it when you don’t have some other, functional source you want to use, as the compiler will not work without a valid node terminus.

Note that class is responsible for merging the node’s facts into the node instance before it is returned.

rest terminus

Get a node via REST. Puppet agent uses this to allow the puppet master to override its environment.

store_configs terminus

Part of the “storeconfigs” feature. Should not be directly set by end users.

write_only_yaml terminus

(Deprecated) Store node information as flat files, serialized using YAML, does not deserialize (write only).

yaml terminus

Store node information as flat files, serialized using YAML, or deserialize stored YAML nodes.

report

  • Indirected Class: Puppet::Transaction::Report

msgpack terminus

Store last report as a flat file, serialized using MessagePack.

processor terminus

Puppet’s report processor. Processes the report with each of the report types listed in the ‘reports’ setting.

rest terminus

Get server report over HTTP via REST.

yaml terminus

Store last report as a flat file, serialized using YAML.

resource

  • Indirected Class: Puppet::Resource

ral terminus

Manipulate resources with the resource abstraction layer. Only used internally.

store_configs terminus

Part of the “storeconfigs” feature. Should not be directly set by end users.

status

  • Indirected Class: Puppet::Status

local terminus

Get status locally. Only used internally.

rest terminus

Get puppet master’s status via REST. Useful because it tests the health of both the web server and the indirector.