Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 38 ยท Architecture and Setup

Environments and puppet.conf

Use Puppet environments to separate production, staging and development code, understand the environment directory layout, environment.conf, and the puppet.conf sections.

Changing code that controls every server is risky. Environments let you keep several independent copies of your code, so you can try a change on a few nodes before it reaches production. This lesson covers the directory layout, how nodes pick an environment, the settings files, and how to inspect configuration.

What is an environment?

An environment is a directory on the server holding its own manifests and modules. The default one is production. Every node belongs to exactly one environment at a time, and the server compiles that node's catalog from that environment's code only.

TEXT
/etc/puppetlabs/code/
  environments/
    production/
      manifests/       # site.pp and other entry-point manifests
      modules/         # modules written or downloaded for this environment
      data/            # Hiera data (with hiera.yaml in the environment root)
      hiera.yaml
      environment.conf # optional per-environment settings
    staging/
      ...
  modules/             # shared base modules (optional)

Typical practice: each Git branch becomes an environment (branch main is production, branch feature-x is an environment named feature_x). Environment names may only contain letters, digits and underscores (so no hyphens). The tool that does this automatically is r10k or Code Manager, covered in the Code Management chapter.

Picking an environment

A node's environment is chosen by (highest priority first):

  1. The --environment flag on a one-off run (puppet agent -t --environment=staging).
  2. An external node classifier (ENC) that returns an environment.
  3. The agent's environment setting in puppet.conf.
  4. The default, production.

If the server's setting environment_timeout is 0 the server re-reads code on every request. In production it is usually unlimited and code deployments clear the cache.

environment.conf

Each environment may have an environment.conf at its root to override a few settings. Relative paths are resolved against the environment directory.

INI
# environment.conf
modulepath = site-modules:modules:$basemodulepath
manifest = manifests/
config_version = bin/config_version.sh
  • modulepath: where to look for modules, in order. The first module with a given name wins.
  • manifest: the entry point (a file or directory of .pp files, by default manifests/). Node definitions go in manifests/site.pp.
  • config_version: a script whose output (for example a Git commit hash) is stored in the catalog and the report so you can tell which code version was applied.

puppet.conf in detail

/etc/puppetlabs/puppet/puppet.conf is an INI file with sections:

INI
[main]
server = puppet.example.test
environment = production

[agent]
runinterval = 30m
report = true

[server]
autosign = /opt/puppetlabs/bin/policy.sh
  • [main] applies to every Puppet command.
  • [agent] applies only to the agent (older docs say [user] for puppet apply).
  • [server] applies only to Puppet Server (older docs say [master]).

Some settings need a restart of the service; always check which. Edit with a text editor or with the helper:

Terminal
sudo puppet config set environment staging --section agent
puppet config print environment
puppet config print --section server | head

puppet config print <name> shows the effective value, including defaults. puppet config print without a name prints everything, which is the best way to learn the available settings.

The entry point: site.pp

In manifests/site.pp you decide which classes each node gets:

PUPPET
# manifests/site.pp
node default {
  include base
}

node 'web1.example.test' {
  include base
  include nginx
}

node /^db\d+\.example\.test$/ {
  include base
  include postgresql
}

node default applies when no other block matches. Names may be exact strings or regular expressions. Larger sites replace this with Hiera-driven classification, or with roles (roles and profiles arrive later in the course). Each node gets exactly one matching node block (the most specific wins), so include base repeated inside blocks is a known pattern; moving it to a role avoids the repetition.

A stand-in for environment lookup

Python Stand-in: which environment wins?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: first module on the modulepath wins

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

This is why a local nginx in site-modules can override a Forge copy: order in modulepath is the rule.

Common mistakes

  • Environment name with a hyphen: invalid. Use feature_x.
  • Forgetting that environments are separate copies: a fix in staging does not exist in production until merged and deployed.
  • Editing code on the server by hand in the live environment instead of through Git.
  • Leaving an agent pinned to a test environment through its puppet.conf after the test.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which environment does a node use if nothing else is set?

    The default environment is production.
  2. 2. Which value wins if the command line, an ENC and puppet.conf all name an environment?

    The --environment flag has the highest priority.
  3. 3. What does modulepath do?

    Modules are searched in order, and the first module with a name wins.
  4. 4. Which is a valid environment name?

    Environment names allow letters, digits and underscores only.

Summary

  • An environment is a separate copy of code under /etc/puppetlabs/code/environments/<name>.
  • Branch-per-environment is the usual workflow; names use letters, digits, underscores.
  • Priority: command line, then ENC, then puppet.conf, then production.
  • environment.conf sets modulepath, manifest and config_version.
  • puppet.conf has [main], [agent] and [server] sections; inspect with puppet config print.
  • site.pp maps nodes to classes.

Next: Resources and Resource Types