Chef Infrastructure Fundamentals

My First Real Chef Cookbook

My first serious Chef cookbook was born out of necessity. I needed to standardize NGINX configurations across 30 web servers, each requiring slightly different virtual host configurations based on their role. Manual configuration was taking hours and introducing inconsistencies. I knew Chef could solve this, but I had to truly understand resources, recipes, and cookbooks to make it work.

After several iterations and some painful mistakes (like accidentally restarting nginx on all production servers simultaneously), I learned the patterns that make Chef powerful and reliable. This article shares those fundamental concepts that transformed me from a Chef novice to someone who could confidently automate complex infrastructure.

Understanding the Chef Resource Model

Resources are the foundation of Chef - they represent a desired state of a piece of infrastructure.

The Resource Anatomy

package 'nginx' do
  action :install
  version '1.18.0'
end

Breaking it down:

• package - Resource type

• 'nginx' - Resource name (what to manage)

• action :install - What to do with it

• version '1.18.0' - Resource properties

Why this matters: Chef doesn't run commands, it declares states. If nginx 1.18.0 is already installed, Chef does nothing. This idempotency is crucial for reliable automation.

Common Resources I Use Daily

File Resources

# Create a file
file '/etc/motd' do
  content 'Welcome to our automated infrastructure'
  owner 'root'
  group 'root'
  mode '0644'
end

# Delete a file
file '/tmp/old_config' do
  action :delete
end

# Create from template
template '/etc/nginx/nginx.conf' do
  source 'nginx.conf.erb'
  owner 'root'
  group 'root'
  mode '0644'
  notifies :reload, 'service[nginx]', :delayed
end

My lesson learned: Always use templates for configuration files that need variables. Static files are for truly static content only.

Package Resources

# Install package
package 'nginx' do
  action :install
end

# Install specific version
package 'postgresql' do
  version '12.3'
  action :install
end

# Install multiple packages
package %w(git vim curl wget) do
  action :install
end

# Remove package
package 'apache2' do
  action :remove
end

Platform abstraction: The same package resource works on Ubuntu (apt), CentOS (yum), and other platforms.

Service Resources

# Ensure service is running
service 'nginx' do
  action [:enable, :start]
end

# Restart service
service 'postgresql' do
  action :restart
end

# Service with multiple actions
service 'nginx' do
  supports status: true, restart: true, reload: true
  action [:enable, :start]
end

My pattern: Always use :enable to ensure services start on boot, not just :start.

Directory Resources

# Create directory
directory '/var/www/html' do
  owner 'www-data'
  group 'www-data'
  mode '0755'
  recursive true
  action :create
end

# Delete directory
directory '/tmp/old_files' do
  recursive true
  action :delete
end

User and Group Resources

# Create user
user 'deploy' do
  comment 'Deployment User'
  home '/home/deploy'
  shell '/bin/bash'
  manage_home true
  action :create
end

# Create group
group 'developers' do
  members ['alice', 'bob']
  action :create
end

Real scenario: I use this for creating application-specific service accounts with restricted permissions.

Execute Resources

# Run command only if file doesn't exist
execute 'download-app' do
  command 'wget https://example.com/app.tar.gz'
  cwd '/tmp'
  not_if { ::File.exist?('/tmp/app.tar.gz') }
end

# Run command and capture output
execute 'initialize-database' do
  command 'bundle exec rake db:migrate'
  cwd '/opt/myapp'
  user 'deploy'
  only_if 'test -f /opt/myapp/db/migrate/*.rb'
end

Critical lesson: Always use guards (only_if, not_if) with execute resources to maintain idempotency.

Building Recipes

Recipes are collections of resources that achieve a specific configuration goal.

My First Recipe: Web Server Setup

#
# Cookbook:: webserver
# Recipe:: default
#
# Sets up a basic NGINX web server

# Install nginx
package 'nginx' do
  action :install
end

# Create document root
directory '/var/www/html' do
  owner 'www-data'
  group 'www-data'
  mode '0755'
  recursive true
end

# Deploy configuration
template '/etc/nginx/sites-available/default' do
  source 'default-site.erb'
  owner 'root'
  group 'root'
  mode '0644'
  notifies :reload, 'service[nginx]', :delayed
end

# Ensure service is running
service 'nginx' do
  action [:enable, :start]
end

Why this works:

1. Install package first

2. Create necessary directories

3. Deploy configuration

4. Start service (notified if config changes)

Recipe Organization Patterns

Single Responsibility:

recipes/
├── default.rb        # Includes other recipes
├── install.rb        # Package installation
├── configure.rb      # Configuration files
└── service.rb        # Service management

My default.rb pattern:

#
# Cookbook:: webserver
# Recipe:: default
#

include_recipe 'webserver::install'
include_recipe 'webserver::configure'
include_recipe 'webserver::service'

Working with Templates

Templates use ERB (Embedded Ruby) to create dynamic configuration files.

Basic Template

templates/default/nginx.conf.erb:

user www-data;
worker_processes <%= node['cpu']['total'] %>;
pid /run/nginx.pid;

events {
    worker_connections <%= node['webserver']['worker_connections'] %>;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    server {
        listen <%= node['webserver']['port'] %>;
        server_name <%= node['webserver']['server_name'] %>;
        
        root /var/www/html;
        index index.html;
    }
}

Using the template:

template '/etc/nginx/nginx.conf' do
  source 'nginx.conf.erb'
  variables(
    port: 80,
    server_name: 'example.com'
  )
  notifies :reload, 'service[nginx]'
end

Advanced Template with Conditionals

templates/default/app-config.erb:

# Application Configuration
app_name: <%= @app_name %>
environment: <%= node.chef_environment %>

<% if node.chef_environment == 'production' %>
# Production settings
debug: false
log_level: warn
cache_enabled: true
<% else %>
# Development settings
debug: true
log_level: debug
cache_enabled: false
<% end %>

database:
  host: <%= @db_host %>
  port: <%= @db_port %>
  
# Feature flags
features:
<% @features.each do |feature, enabled| %>
  <%= feature %>: <%= enabled %>
<% end %>

My real usage:

template '/opt/myapp/config.yml' do
  source 'app-config.erb'
  variables(
    app_name: 'MyApplication',
    db_host: node['myapp']['db_host'],
    db_port: node['myapp']['db_port'],
    features: {
      'new_ui' => true,
      'beta_api' => node.chef_environment != 'production'
    }
  )
  notifies :restart, 'service[myapp]'
end

Understanding Attributes

Attributes provide data for recipes and templates.

Attribute Precedence

From lowest to highest priority:

1. Default attributes (in cookbook)

2. Environment attributes

3. Role attributes

4. Node attributes

5. Override attributes

attributes/default.rb:

# Default attributes for webserver
default['webserver']['port'] = 80
default['webserver']['worker_connections'] = 1024
default['webserver']['server_name'] = 'localhost'
default['webserver']['ssl_enabled'] = false
default['webserver']['ssl_cert'] = '/etc/ssl/certs/server.crt'
default['webserver']['ssl_key'] = '/etc/ssl/private/server.key'

# Environment-specific defaults
case node.chef_environment
when 'production'
  default['webserver']['worker_connections'] = 4096
  default['webserver']['ssl_enabled'] = true
when 'development'
  default['webserver']['worker_connections'] = 512
end

Accessing Attributes in Recipes

# Access nested attributes
port = node['webserver']['port']

# Set node attributes (persisted)
node.normal['webserver']['last_configured'] = Time.now.to_s

# Use in resources
service 'nginx' do
  action node['webserver']['service_action'].to_sym
end

My Attribute Organization Pattern

# attributes/default.rb
# Keep it organized by component

# Package versions
default['webserver']['nginx_version'] = '1.18.0'

# Paths
default['webserver']['config_path'] = '/etc/nginx'
default['webserver']['log_path'] = '/var/log/nginx'
default['webserver']['pid_path'] = '/var/run/nginx.pid'

# Service settings
default['webserver']['service_name'] = 'nginx'
default['webserver']['service_action'] = 'start'

# Performance tuning
default['webserver']['worker_processes'] = 'auto'
default['webserver']['worker_connections'] = 1024

# Security settings
default['webserver']['ssl_protocols'] = 'TLSv1.2 TLSv1.3'
default['webserver']['ssl_ciphers'] = 'HIGH:!aNULL:!MD5'

Notification and Subscriptions

Resources can trigger other resources to take action.

Notifies Pattern

# Template notifies service to reload
template '/etc/nginx/nginx.conf' do
  source 'nginx.conf.erb'
  notifies :reload, 'service[nginx]', :delayed
end

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

Timing options:

• :delayed - Run at end of Chef run (default, safest)

• :immediate - Run immediately

My rule: Use :delayed unless you need immediate action. It prevents cascading restarts.

Multiple Notifications

template '/etc/nginx/nginx.conf' do
  source 'nginx.conf.erb'
  notifies :run, 'execute[test-nginx-config]', :immediate
  notifies :reload, 'service[nginx]', :delayed
end

execute 'test-nginx-config' do
  command 'nginx -t'
  action :nothing
end

Real scenario: Test configuration before reloading to avoid breaking the service.

Subscribes Pattern

service 'nginx' do
  action [:enable, :start]
  subscribes :reload, 'template[/etc/nginx/nginx.conf]', :delayed
end

When I use subscribes: When the triggered resource is defined in a different recipe.

Cookbook Structure Best Practices

My Standard Cookbook Layout

my_cookbook/
├── attributes/
│   ├── default.rb
│   └── production.rb
├── recipes/
│   ├── default.rb
│   ├── install.rb
│   ├── configure.rb
│   └── service.rb
├── templates/
│   └── default/
│       ├── config.erb
│       └── service.erb
├── files/
│   └── default/
│       └── static-file.txt
├── test/
│   └── integration/
│       └── default/
│           └── default_test.rb
├── metadata.rb
├── README.md
└── CHANGELOG.md

metadata.rb - The Cookbook Manifest

name 'webserver'
maintainer 'Your Name'
maintainer_email '[email protected]'
license 'Apache-2.0'
description 'Configures NGINX web server'
version '1.2.0'

supports 'ubuntu', '>= 18.04'
supports 'centos', '>= 7.0'

depends 'apt', '~> 7.0'
depends 'firewall', '~> 2.7'

chef_version '>= 15.0'

Version management: I use semantic versioning and update with each change.

Guards and Conditional Execution

only_if and not_if

# Run only if condition is true
execute 'bundle-install' do
  command 'bundle install'
  cwd '/opt/myapp'
  only_if { ::File.exist?('/opt/myapp/Gemfile') }
end

# Run only if command succeeds
service 'nginx' do
  action :start
  only_if 'test -f /etc/nginx/nginx.conf'
end

# Don't run if condition is true
execute 'initialize-db' do
  command 'rake db:setup'
  not_if { ::File.exist?('/var/lib/myapp/db.initialized') }
end

Platform-Specific Resources

# Using case statement
case node['platform_family']
when 'debian'
  package 'nginx'
when 'rhel'
  package 'nginx' do
    version '1.18.0'
  end
end

# Using platform? helper
if platform?('ubuntu')
  execute 'apt-update' do
    command 'apt-get update'
  end
end

My approach: Write platform-agnostic code when possible, use conditionals only when necessary.

Real-World Example: Database Server Cookbook

Let me share a complete cookbook I built for PostgreSQL:

recipes/default.rb:

include_recipe 'postgresql::install'
include_recipe 'postgresql::configure'
include_recipe 'postgresql::service'
include_recipe 'postgresql::databases'

recipes/install.rb:

package 'postgresql' do
  version node['postgresql']['version']
  action :install
end

package 'postgresql-contrib' do
  action :install
end

recipes/configure.rb:

template '/etc/postgresql/12/main/postgresql.conf' do
  source 'postgresql.conf.erb'
  owner 'postgres'
  group 'postgres'
  mode '0644'
  variables(
    max_connections: node['postgresql']['max_connections'],
    shared_buffers: node['postgresql']['shared_buffers'],
    work_mem: node['postgresql']['work_mem']
  )
  notifies :reload, 'service[postgresql]', :delayed
end

template '/etc/postgresql/12/main/pg_hba.conf' do
  source 'pg_hba.conf.erb'
  owner 'postgres'
  group 'postgres'
  mode '0640'
  notifies :reload, 'service[postgresql]', :delayed
end

recipes/service.rb:

service 'postgresql' do
  action [:enable, :start]
  supports restart: true, reload: true, status: true
end

attributes/default.rb:

default['postgresql']['version'] = '12'
default['postgresql']['max_connections'] = 100
default['postgresql']['shared_buffers'] = '256MB'
default['postgresql']['work_mem'] = '4MB'
default['postgresql']['maintenance_work_mem'] = '64MB'

# Production overrides
if node.chef_environment == 'production'
  default['postgresql']['max_connections'] = 300
  default['postgresql']['shared_buffers'] = '4GB'
  default['postgresql']['work_mem'] = '16MB'
end

templates/default/postgresql.conf.erb:

# PostgreSQL Configuration
# Managed by Chef - DO NOT EDIT MANUALLY

max_connections = <%= @max_connections %>
shared_buffers = <%= @shared_buffers %>
work_mem = <%= @work_mem %>

# Logging
log_directory = 'pg_log'
log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'
logging_collector = on

# Performance
effective_cache_size = <%= (node['memory']['total'].to_i * 0.75 / 1024).to_i %>MB
checkpoint_completion_target = 0.9

Common Patterns I Use

Idempotent File Markers

# Initialize only once
execute 'app-setup' do
  command '/opt/myapp/bin/setup.sh'
  creates '/var/lib/myapp/.initialized'
end

# Or create marker explicitly
file '/var/lib/myapp/.initialized' do
  content "Initialized at #{Time.now}"
  action :create_if_missing
end

Graceful Service Management

# Test before reload
execute 'test-nginx-config' do
  command 'nginx -t'
  action :nothing
end

template '/etc/nginx/nginx.conf' do
  source 'nginx.conf.erb'
  notifies :run, 'execute[test-nginx-config]', :immediate
  notifies :reload, 'service[nginx]', :delayed
end

Looping Over Data

# Create multiple virtual hosts
node['webserver']['vhosts'].each do |vhost|
  template "/etc/nginx/sites-available/#{vhost['name']}" do
    source 'vhost.erb'
    variables(
      server_name: vhost['server_name'],
      port: vhost['port'],
      root: vhost['root']
    )
  end
end

Testing Your Recipes

Using Test Kitchen

# Test all platforms
kitchen test

# Test specific suite
kitchen test default-ubuntu-2004

Writing Integration Tests

test/integration/default/default_test.rb:

describe package('nginx') do
  it { should be_installed }
end

describe service('nginx') do
  it { should be_enabled }
  it { should be_running }
end

describe file('/etc/nginx/nginx.conf') do
  it { should exist }
  its('owner') { should eq 'root' }
  its('mode') { should cmp '0644' }
end

describe port(80) do
  it { should be_listening }
end

Lessons Learned

1. Always Use Idempotent Resources

❌ execute 'restart nginx' - Runs every time ✅ Use notifications to restart only when needed

2. Test Configurations Before Applying

execute 'test-config' do
  command 'nginx -t'
  action :nothing
end

3. Use Templates for Configuration

• Static files for truly static content

• Templates for anything with variables

• Never hardcode environment-specific values

4. Organize Attributes Clearly

# Bad: scattered attributes
default['port'] = 80
default['nginx_workers'] = 4

# Good: namespaced attributes
default['webserver']['port'] = 80
default['webserver']['worker_processes'] = 4

5. Keep Recipes Focused

One recipe = one responsibility

What's Next?

You now understand: ✅ Chef resources and their properties ✅ Building recipes with proper structure ✅ Working with templates and attributes ✅ Notifications and service management ✅ Cookbook organization best practices ✅ Testing and validation patterns

Continue to Writing and Testing Cookbooks for advanced cookbook development patterns, or jump to Chef Server and Node Management to learn about scaling your Chef infrastructure.

The fundamentals you've learned here are the building blocks for all Chef automation. Master these patterns, and you'll be able to automate any infrastructure configuration with confidence.

---

Ready to level up your cookbook development? Continue to Writing and Testing Cookbooks