Chef Fundamentals

Chef Infra manages system configuration as code. You describe the state a node should have, and Chef Infra Client moves that node toward the described state. A package should be installed. A file should contain approved content. A service should be enabled and running.

The central idea is convergence. Chef Infra Client compares each resource declaration with the current node. It changes the node only when the declared state is not already present. Repeated runs should reach the same final state without repeating unnecessary work.

Chef is useful when you manage many long-lived systems that must follow consistent policy. It gives configuration changes the same review, testing, and version-control practices as application code. It can also correct configuration drift during later runs.

The operating model

A typical Chef Infra installation has three main parts:

Chef Workstation is where you author and test policy.
Chef Infra Server stores cookbooks, policies, and node metadata.
Chef Infra Client runs on managed nodes and applies policy locally.

A managed system is a node. During a client run, Chef Infra Client collects node details with Ohai, authenticates to Chef Infra Server, and retrieves its policy. It then compiles a resource collection and converges the node.

The pull model matters. Nodes normally contact Chef Infra Server on a schedule. The server distributes policy, but the client performs most configuration work on the node. A temporary network interruption can delay retrieval without changing the policy already assigned to that node.

Chef Infra also supports an agentless mode over secure shell. Treat that as a deployment option, not a change to the core model. Resources still describe desired state, and a Chef Infra Client run still compiles and converges them.

Resources describe desired state

A resource is one configuration statement. It has a resource type, a name, properties, and an action. Chef Infra Client includes resources for packages, files, directories, services, users, firewalls, and many other system components.

package 'nginx' do
  action :install
end

service 'nginx' do
  action [:enable, :start]
end

This code declares outcomes. It does not prescribe every operating-system command. The package and service resources contain provider logic for supported platforms.

Idempotency is the behavior that makes convergence safe to repeat. A well-designed resource checks current state before acting. Some resources need a guard to make that check explicit. Arbitrary shell commands often hide state, so prefer a purpose-built resource when one exists.

Recipes and cookbooks organize policy

A recipe groups resources in execution order. A cookbook is the main unit for authoring and distributing Chef Infra policy. It can contain recipes, attributes, templates, files, custom resources, libraries, tests, and metadata.

Chef uses Ruby as the reference language for recipes and custom resources. The resource syntax is a domain-specific language built on Ruby. Most policy should remain declarative and easy to inspect. Use general Ruby only when the resource model needs it.

A run-list selects recipes and defines their order for a node. Order is observable. If one resource creates a file that another resource consumes, place that dependency in a clear sequence.

Attributes provide data used by recipes. Ohai supplies automatic attributes about the node. Cookbooks and policy can supply other values. Attribute precedence can make an effective value hard to trace, so keep inputs narrow and document where each important value originates.

Compile, then converge

A Chef Infra Client run has two important phases.

During the compile phase, Chef loads libraries, attributes, custom resources, and recipes. It builds the resource collection in order. Ruby code evaluated at compile time can therefore affect which resources exist.

During the converge phase, Chef processes the resource collection. Each resource checks current state and takes its action when needed. This separation explains many surprising behaviors. Code that runs immediately during compilation does not behave like a resource processed during convergence.

Notifications connect changed resources to follow-up actions. A template can notify a service to restart after the file changes. Delayed notifications run at the end of the client run by default. Immediate notifications run at once. Use immediate timing only when later resources require the reaction.

Guards add conditions with only_if or not_if. They are useful when a resource cannot determine the relevant state on its own. A guard should test a specific precondition. It should not turn every run into an opaque script.

Policyfiles make releases explicit

Chef Infra supports traditional run-lists, roles, environments, and cookbook version constraints. It also supports Policyfiles.

A Policyfile defines a run-list, cookbook sources, dependencies, and attributes for a group of nodes. Running chef install resolves that input into Policyfile.lock.json. The lock file records the selected cookbook versions, content identifiers, sources, and attributes.

That lock gives a policy revision a repeatable cookbook set. You can upload it to Chef Infra Server and associate it with a policy group. Promotion then moves a tested revision between policy groups without recomputing dependencies on every node run.

Policyfiles reduce the mutability found in workflows based on global roles and environments. They do not remove the need to test. A locked set can still contain incorrect policy.

Develop and test as code

Chef Workstation includes the main authoring and testing tools. The chef command works with repositories and Policyfiles. knife interacts with Chef Infra Server objects and nodes. Cookstyle checks style, syntax, and selected logic problems. Test Kitchen creates test instances, converges cookbooks, and verifies outcomes.

A sound change path is ordered:

Author one clear policy change.
Run static checks with Cookstyle.
Converge an isolated Test Kitchen instance.
Verify the resulting state with automated tests.
Test in an environment representative of production.
Promote a pinned policy revision to a limited node group.
Review the run results before expanding scope.

A successful first run is not enough. Run the same policy again. The second run should report no changes when the desired state is stable. This catches resources and commands that are not actually idempotent.

Where Chef fits

Chef Infra fits fleets of servers and devices that need continuing configuration enforcement. It is especially useful when you need reusable policy, cross-platform resources, scheduled drift correction, centralized policy distribution, and an auditable promotion path.

Chef does not replace an image-building system. Images can establish a machine's initial state, while Chef maintains state after deployment. Chef also does not replace an application orchestrator or a cloud provisioning tool. Those systems create and schedule infrastructure; Chef configures operating systems and software within its supported scope.

The model carries costs. Managed nodes need a supported execution path. Centralized Chef Infra Server deployments require service operation, authentication, authorization, backup, and upgrades. Ruby-based policy allows flexibility, but excess imperative code can hide state and timing. Chef distributions also have current platform, version, and licensing requirements that you must check before adoption.

Use Chef when continuing convergence is valuable enough to justify that operating model. For short-lived immutable systems, an image pipeline and platform-native controls may own more of the configuration. The right boundary depends on when state is created, how long it lives, and which system can verify it.

Your durable mental model is a loop: policy becomes a resource collection, the client observes node state, resources converge differences, and later runs detect drift. Testing and promotion control what enters that loop.