Chef cookbook metadata lets Chef understand a cookbook’s identity, version, dependencies, and platform support without evaluating every file in the cookbook. This guide is for DevOps engineers maintaining Chef cookbooks who want a clear, practical model of how metadata.rb and metadata.json are used.
Originally published on 2015-08-18; fully revised and updated.
This revision expands the original article from DevOpsSchool with a clearer operational workflow and command-focused examples.
What metadata does in a Chef cookbook
In Chef, metadata provides machine-readable information about a cookbook so tooling and the Chef Server can reason about it correctly. Instead of parsing all cookbook files to infer behavior, Chef uses metadata to quickly determine compatibility and dependency requirements.
- Cookbook identity (name, version, description)
- Dependency declarations (for example, other cookbooks required)
- Platform support and version constraints
- Chef version compatibility and related hints for deployment
metadata.rb is the editable source of truth
Every cookbook includes a metadata.rb file at the top level. This is the file you are expected to edit for permanent metadata changes. The original post also notes that knife cookbook create generates this file when scaffolding a new cookbook.
name 'my_cookbook'
maintainer 'Platform Team'
maintainer_email 'platform@example.com'
license 'Apache-2.0'
description 'Installs and configures my application'
version '1.2.3'
chef_version '>= 16.0'
supports 'ubuntu', '>= 20.04'
depends 'apt'
depends 'nginx'Code language: JavaScript (javascript)How metadata.json is generated and used
metadata.json is generated from metadata.rb. As described in the original content, metadata is compiled when a cookbook is uploaded or when you run the metadata subcommand. You can edit metadata.json directly for temporary changes, but regeneration or upload can overwrite it.
flowchart TD
A[Create cookbook] --> B[Edit metadata.rb]
B --> C[Run knife cookbook metadata]
C --> D[metadata.json written locally]
B --> E[Run knife cookbook upload]
E --> F[Chef compiles metadata from metadata.rb]
F --> G[Cookbook metadata stored on Chef Server]
metadata.rb vs metadata.json at a glance
| Aspect | metadata.rb | metadata.json |
|---|---|---|
| Purpose | Human-edited cookbook metadata definition | Generated JSON representation of cookbook metadata |
| How it is created | Typically scaffolded by knife cookbook create, then edited manually | Generated from metadata.rb (for example via knife cookbook metadata) |
| Where to make permanent changes | Yes, this is the preferred location | No, direct edits are temporary and may be overwritten |
| Precedence when both files exist | Preferred at cookbook load time (per original source) | Not preferred when metadata.rb is present |
| Behavior during upload | Used as input for compiled metadata | Not the primary source in the classic knife cookbook upload flow |
Common knife commands for metadata workflows
# Create a new cookbook (includes metadata.rb)
knife cookbook create my-cookbook
# Generate or regenerate metadata.json from metadata.rb
knife cookbook metadata my-cookbook -o <COOKBOOK_PATH>
# Example from the original article
knife cookbook metadata my-cookbook-name -o /opt/development/cookbooks/
# Upload cookbook; metadata is compiled from metadata.rb
knife cookbook upload my-cookbook-name -o /opt/development/cookbooks/Code language: PHP (php)When both files are present in a cookbook
If both metadata.rb and metadata.json are present, the original source states that metadata.rb is preferred at load time. Operationally, this means you should treat metadata.rb as canonical and use metadata.json as a generated artifact.
Best practices
- Keep
metadata.rbas the single source of truth for permanent metadata updates. - Regenerate metadata via tooling instead of hand-editing generated JSON.
- Commit intentional metadata changes with version bumps and clear change history.
- Validate dependency and platform constraints before upload.
- Re-check command behavior against the Chef version used in your environment.
I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.
I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.
Find Trusted Cardiac Hospitals
Compare heart hospitals by city and services — all in one place.
Explore Hospitals
