Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Roles, Environments and Policyfiles

Environments and Cookbook Version Constraints

Learn how Chef environments separate dev, staging and production, how cookbook version constraints such as ~> work, and test constraint matching in Ruby.

The same cookbook should not hit every server at the same moment. A new version of the nginx cookbook should first run on a development node, then on staging, and only then on production. Chef models this with environments: named groups of nodes, each with its own cookbook version rules and attributes.

In this lesson you will learn what an environment contains, what the version constraint operators mean (especially the pessimistic ~>), how the Chef Server picks a cookbook version for a node, and how to place a node in an environment. You will also run a model of version matching, using the same Gem::Version rules that Chef's constraints follow.

The Chef Server is not available here. Environment files and knife commands are read-only. The runnable examples use Ruby's built-in version classes, which are real and behave like Chef's constraint matching.

What an environment is

Every node belongs to exactly one environment. If you never choose, it is in _default, which cannot be edited. An environment has:

  • a name and a description,
  • cookbook version constraints (cookbook_versions),
  • default and override attributes.
Ruby
name 'production'
description 'Live servers'

cookbook_versions(
  'nginx'  => '= 12.1.3',
  'myapp'  => '~> 2.4.0',
  'base'   => '>= 1.0.0'
)

default_attributes(
  'myapp' => { 'log_level' => 'warn', 'replicas' => 4 }
)

Upload with knife environment from file environments/production.rb, and put a node in it:

Terminal
knife node environment set web01 production
knife node show web01 -a chef_environment

You can also set it in client.rb (environment 'production') or at bootstrap with -E production.

Version constraints

Cookbook versions follow semantic versioning: major.minor.patch. A constraint is an operator plus a version:

Constraint Meaning
= 1.2.3 Exactly this version
> 1.2.3, >= 1.2.3 Newer than / at least
< 2.0.0, <= 2.0.0 Older than / at most
~> 1.2 At least 1.2.0 and below 2.0.0 (patch and minor updates)
~> 1.2.3 At least 1.2.3 and below 1.3.0 (patch updates only)

The pessimistic operator ~> ("twiddle-wakka") is the most useful: it allows safe upgrades but blocks the next major or minor jump, depending on how many digits you write. Chef's constraint syntax is the same as RubyGems', so Ruby can test it:

Ruby Which versions satisfy a constraint?

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 gets), it gets the next line from this box.

Look at ~> 1.2 and ~> 1.2.0: the first accepts 1.3.0 and 1.9.4, the second stops at 1.2.7. The number of digits you write sets how much freedom you give.

Notice also that the string comparison trap is real: "1.10.0" is newer than "1.9.0", but a plain text sort says the opposite. Always compare with a version class.

How the server solves versions

When a node starts a run, the server builds the set of cookbooks needed by its expanded run list and dependencies (depends lines in each metadata.rb). It then picks the newest version of each cookbook that satisfies all constraints: the environment's, and those from other cookbooks' depends. If no combination works, the run fails with a message that lists the conflict.

Ruby Stand-in: pick versions under an environment's constraints

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 gets), it gets the next line from this box.

Staging gets the newest allowed versions (nginx 13.0.0, myapp 2.5.0), production stays on the pinned nginx and the newest 2.4.x of myapp. The last call shows the failure mode: an impossible constraint stops the run before anything changes.

Environment attributes

Environments can set attributes too, which is handy for values that differ between stages: log levels, replica counts, hostnames of the database. Environment default_attributes rank above cookbook defaults, and override_attributes rank near the top. The attribute precedence lesson shows the exact order.

A promotion workflow

flowchart LR
  A["Commit cookbook v2.5.0"] --> B["Upload to server"]
  B --> C["dev: >= 2.4"]
  C --> D["staging: ~> 2.5"]
  D --> E["production: = 2.5.0"]

Pin production last. Each stage loosens or tightens the constraint to control what runs where.

A common practice is to pin exact versions in production (= 2.5.0) and promote by changing one line. Changing an environment is a quick, reviewable edit, but note that it applies to all nodes in that environment at their next run.

Common mistakes

  • No constraint on production. Anyone who uploads a newer cookbook changes production silently.
  • Version not bumped. Uploading changed code with the same version fails on frozen cookbooks, or worse, mixes content. Bump version in metadata.rb for every change.
  • Too loose a ~>. ~> 1.0 allows every 1.x release; use ~> 1.0.0 when you want patch updates only.
  • One huge environment per application. Remember that environments are shared by all cookbooks; do not make production-myapp and production-billing unless you must.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which versions does ~> 1.2.3 allow?

    With three digits, the last digit may rise but the minor version is fixed. ~> 1.2 (two digits) would allow up to but not including 2.0.0.
  2. 2. Which environment does a node join if you do nothing?

    Every node belongs to an environment; the built-in _default has no constraints and cannot be edited.
  3. 3. How does the server choose a cookbook version when several versions satisfy all constraints?

    The solver prefers the newest version that fits every constraint.
  4. 4. Why is a text comparison of versions unsafe?

    Compare version objects. Text comparison orders characters, not numeric parts.

Summary

  • An environment groups nodes and sets cookbook version constraints and attributes; _default is the fallback.
  • Operators: =, >, >=, <, <=, and the pessimistic ~>, where the digits you write set the freedom.
  • The server picks the newest version that satisfies the environment and all depends constraints, or fails.
  • Promote cookbooks stage by stage and pin production exactly; always bump versions.

Next: Attribute Precedence with Roles and Environments