{"id":418,"date":"2026-10-14T06:31:09","date_gmt":"2026-10-14T06:31:09","guid":{"rendered":"http:\/\/www.scmgalaxy.com\/tutorials\/2015\/08\/18\/know-about-metadata-rb-and-metadata-json-in-chef\/"},"modified":"2026-10-14T06:31:09","modified_gmt":"2026-10-14T06:31:09","slug":"know-about-metadata-rb-and-metadata-json-in-chef","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/know-about-metadata-rb-and-metadata-json-in-chef\/","title":{"rendered":"Chef Cookbook Metadata Explained: metadata.rb vs metadata.json"},"content":{"rendered":"\n

Chef cookbook metadata lets Chef understand a cookbook\u2019s 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<\/code> and metadata.json<\/code> are used.<\/p>\n\n\n\n

Originally published on 2015-08-18; fully revised and updated.<\/em><\/p>\n\n\n\n

This revision expands the original article from DevOpsSchool<\/a> with a clearer operational workflow and command-focused examples.<\/p>\n\n\n\n

What metadata does in a Chef cookbook<\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

  • Cookbook identity (name, version, description)<\/li>
  • Dependency declarations (for example, other cookbooks required)<\/li>
  • Platform support and version constraints<\/li>
  • Chef version compatibility and related hints for deployment<\/li><\/ul>\n\n\n\n

    metadata.rb is the editable source of truth<\/h2>\n\n\n\n

    Every cookbook includes a metadata.rb<\/code> 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<\/code> generates this file when scaffolding a new cookbook.<\/p>\n\n\n

    name 'my_cookbook'<\/span>\nmaintainer 'Platform Team'<\/span>\nmaintainer_email 'platform@example.com'<\/span>\nlicense 'Apache-2.0'<\/span>\ndescription 'Installs and configures my application'<\/span>\nversion '1.2.3'<\/span>\nchef_version '>= 16.0'<\/span>\nsupports 'ubuntu'<\/span>, '>= 20.04'<\/span>\ndepends 'apt'<\/span>\ndepends 'nginx'<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    How metadata.json is generated and used<\/h2>\n\n\n\n
    metadata.json<\/code> is generated from metadata.rb<\/code>. 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<\/code> directly for temporary changes, but regeneration or upload can overwrite it.<\/p>\n\n\n\n
    \nflowchart TD\n    A[Create cookbook] --> B[Edit metadata.rb]\n    B --> C[Run knife cookbook metadata]\n    C --> D[metadata.json written locally]\n    B --> E[Run knife cookbook upload]\n    E --> F[Chef compiles metadata from metadata.rb]\n    F --> G[Cookbook metadata stored on Chef Server]\n<\/pre>\n\n\n\n
    metadata.rb vs metadata.json at a glance<\/h2>\n\n\n\n
    Aspect<\/th>metadata.rb<\/th>metadata.json<\/th><\/tr><\/thead>
    Purpose<\/td>Human-edited cookbook metadata definition<\/td>Generated JSON representation of cookbook metadata<\/td><\/tr>
    How it is created<\/td>Typically scaffolded by knife cookbook create<\/code>, then edited manually<\/td>Generated from metadata.rb<\/code> (for example via knife cookbook metadata<\/code>)<\/td><\/tr>
    Where to make permanent changes<\/td>Yes, this is the preferred location<\/td>No, direct edits are temporary and may be overwritten<\/td><\/tr>
    Precedence when both files exist<\/td>Preferred at cookbook load time (per original source)<\/td>Not preferred when metadata.rb<\/code> is present<\/td><\/tr>
    Behavior during upload<\/td>Used as input for compiled metadata<\/td>Not the primary source in the classic knife cookbook upload<\/code> flow<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Common knife commands for metadata workflows<\/h2>\n\n\n
    # Create a new cookbook (includes metadata.rb)<\/span>\nknife cookbook create my-cookbook\n\n# Generate or regenerate metadata.json from metadata.rb<\/span>\nknife cookbook metadata my-cookbook -o <COOKBOOK_PATH>\n\n# Example from the original article<\/span>\nknife cookbook metadata my-cookbook-name -o \/opt\/development\/cookbooks\/\n\n# Upload cookbook; metadata is compiled from metadata.rb<\/span>\nknife cookbook upload my-cookbook-name -o \/opt\/development\/cookbooks\/<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    When both files are present in a cookbook<\/h2>\n\n\n\n
    If both metadata.rb<\/code> and metadata.json<\/code> are present, the original source states that metadata.rb<\/code> is preferred at load time. Operationally, this means you should treat metadata.rb<\/code> as canonical and use metadata.json<\/code> as a generated artifact.<\/p>\n\n\n\n
    Best practices<\/h2>\n\n\n\n
    • Keep metadata.rb<\/code> as the single source of truth for permanent metadata updates.<\/li>
    • Regenerate metadata via tooling instead of hand-editing generated JSON.<\/li>
    • Commit intentional metadata changes with version bumps and clear change history.<\/li>
    • Validate dependency and platform constraints before upload.<\/li>
    • Re-check command behavior against the Chef version used in your environment.<\/li><\/ul>\n","protected":false},"excerpt":{"rendered":"
      Understand how Chef uses cookbook metadata, when metadata.json is generated, and why metadata.rb should be your source of truth. Includes workflow, command examples, and precedence rules when both files exist.<\/p>\n","protected":false},"author":1,"featured_media":3446,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[88],"tags":[407,1659,604,602,1050,1653,1654,1656,1655,670,1658,1657],"class_list":["post-418","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-chef","tag-chef","tag-chef-cookbooks","tag-chef-guide","tag-chef-tutorials","tag-cookbooks","tag-metadata","tag-metadata-in-chef","tag-metadata-json","tag-metadata-rb","tag-what","tag-what-is-metadata-json","tag-what-is-metadata-rb"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/418","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=418"}],"version-history":[{"count":4,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/418\/revisions"}],"predecessor-version":[{"id":79291,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/418\/revisions\/79291"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media\/3446"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=418"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=418"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=418"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}