Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


sc-mongodb (38) Versions 5.1.19

Installs and configures mongodb

cookbook 'sc-mongodb', '= 5.1.19', :supermarket
cookbook 'sc-mongodb', '= 5.1.19'
knife supermarket install sc-mongodb
knife supermarket download sc-mongodb
Quality 50%

sc-MongoDB Cookbook

Cookbook Version
CI State

Installs and configures MongoDB


This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit or come chat with us on the Chef Community Slack in #sous-chefs.


  • Single MongoDB instance
  • Replication
  • Sharding
  • Replication and Sharding
  • MongoDB Monitoring System



  • none

Chef Infra Client

  • Chef Infra Client 14+


Currently we 'actively' test using test-kitchen on Ubuntu, Debian, CentOS, Redhat


This cookbook contains a definition mongodb_instance which can be used to configure
a certain type of mongodb instance, like the default mongodb or various components
of a sharded setup.

For examples see the USAGE section below.


MongoDB setup

  • default['mongodb']['install_method'] - This option can be "mongodb-org" or "none" - Default ("mongodb-org")

MongoDB Configuration

The node['mongodb']['config'] is split into 2 keys, mongod and mongos (i.e. node['mongodb']['config']['mongod']). They attributes are rendered out as a yaml config file. All settings defined in the Configuration File Options documentation page can be added to the node['mongodb']['config'][<setting>] attribute:

Several important attributes to note:

  • node['mongodb']['config']['mongod']['net']['bindIp'] - Configure from which address to accept connections
  • node['mongodb']['config']['mongod']['net']['port'] - Port the mongod listens on, default is 27017
  • node['mongodb']['config']['mongod']['replication']['oplogSizeMB'] - Specifies a maximum size in megabytes for the replication operation log
  • node['mongodb']['config']['mongod']['storage']['dbPath'] - Location for mongodb data directory, defaults to "/var/lib/mongodb"
  • node['mongodb']['config']['mongod']['storage']['engine'] - Storage engine to use, default is "wiredTiger"
  • node['mongodb']['config']['mongod']['systemLog']['path'] - Path for the logfiles, default is "/var/lib/mongo" for rhel and fedora and "/var/log/mongodb/mongod.log" for all others
  • node['mongodb']['config']['mongod'][<setting>] - General MongoDB Configuration File option

Cookbook specific attributes

  • node['mongodb']['reload_action'] - Action to take when MongoDB conf files are modified, default is "restart"
  • node['mongodb']['package_version'] - Version of the MongoDB package to install, default is nil
  • node['mongodb']['client_roles'] - Role identifying all external clients which should have access to a mongod instance

Sharding and replication attributes

  • node['mongodb']['config']['mongod']['replication']['replSetName'] - Define name of replicaset
  • node['mongodb']['cluster_name'] - Name of the cluster, all members of the cluster must reference to the same name, as this name is used internally to identify all members of a cluster.
  • node['mongodb']['shard_name'] - Name of a shard, default is "default"
  • node['mongodb']['sharded_collections'] - Define which collections are sharded
  • node['mongodb']['replica_arbiter_only'] - Set to true to make node an arbiter.
  • node['mongodb']['replica_build_indexes'] - Set to false to omit index creation.
  • node['mongodb']['replica_hidden'] - Set to true to hide node from replicaset.
  • node['mongodb']['replica_slave_delay'] - Number of seconds to delay slave replication.
  • node['mongodb']['replica_priority'] - Node priority.
  • node['mongodb']['replica_tags'] - Node tags.
  • node['mongodb']['replica_votes'] - Number of votes node will cast in an election.

shared MMS Agent attributes

  • node['mongodb']['mms_agent']['api_key'] - MMS Agent API Key. No default, required.
  • node['mongodb']['mms_agent']['automation']['config'][<setting>] - General MongoDB MMS Automation Agent configuration file option.
  • node['mongodb']['mms_agent']['backup']['config'][<setting>] - General MongoDB MMS Monitoring Agent configuration file option.
  • node['mongodb']['mms_agent']['monitoring']['config'][<setting>] - General MongoDB MMS Monitoring Agent configuration file option.

Automation Agent Settings

The defaults values installed by the package are:


Backup Agent Settings

The defaults values installed by the package are:

Monitoring Agent Settings

The defaults values installed by the package are:


User management attributes

  • node['mongodb']['config']['auth'] - Require authentication to access or modify the database (True or False), Default is nil
  • node['mongodb']['admin'] - The admin user with userAdmin privileges that allows user management
  • node['mongodb']['users'] - Array of users to add when running the user management recipe


Single mongodb instance

Simply add

include_recipe "sc-mongodb::default"

to your recipe. This will run the mongodb instance as configured by your distribution.
You can change the dbpath, logpath and port settings (see ATTRIBUTES) for this node by
using the mongodb_instance definition:

mongodb_instance "mongodb" do
  port node['application']['port']

This definition also allows you to run another mongod instance with a different
name on the same node

mongodb_instance "my_instance" do
  port node['mongodb']['port'] + 100

The result is a new system service with

  /etc/init.d/my_instance <start|stop|restart|status>


Add sc-mongodb::replicaset (instead of sc-mongodb::default) to the node's run_list. Also choose a name for your
replicaset cluster and set the value of node['mongodb']['cluster_name'] for each
member to this name.

The recipe will try to configure the replicaset with the instances already registered in your chef-server with the same
node['mongodb']['cluster_name'], to configure various machines with the replicaset you'll need to deactivate the
automatic configuration with node['mongodb']['auto_configure']['replicaset'] = false and enable that flag only on the last
instance of the replicaset.


You need a few more components, but the idea is the same: identification of the
members with their different internal roles (mongos, configserver, etc.) is done via
the node['mongodb']['cluster_name'] and node['mongodb']['shard_name'] attributes.

Let's have a look at a simple sharding setup, consisting of two shard servers, one
config server and one mongos.

First, we would like to configure the two shards. For doing so, just use
sc-mongodb::shard in the node's run_list and define a unique mongodb['shard_name']
for each of these two nodes, say "shard1" and "shard2".

Then configure a node to act as a config server - by using the sc-mongodb::configserver

And finally, you need to configure the mongos. This can be done by using the
sc-mongodb::mongos recipe. The mongos needs some special configuration, as these
mongos are actually doing the configuration of the whole sharded cluster.
Most importantly you need to define what collections should be sharded by setting the
attribute mongodb['sharded_collections']:

  "mongodb": {
    "sharded_collections": {
      "test.addressbook": "name",
      "mydatabase.calendar": "date"

Now mongos will automatically enable sharding for the "test" and the "mydatabase"
database. Also, the "addressbook" and the "calendar" collection will be sharded,
with sharding key "name" resp. "date".
In the context of a sharding cluster always keep in mind to use a single role
which is added to all members of the cluster to identify all member nodes.
Also, shard names are important to distinguish the different shards.
This is esp. important when you want to replicate shards.

Sharding + Replication

The setup is not much different from the one described above. All you have to do is add the
sc-mongodb::replicaset recipe to all shard nodes, and make sure that all shard
nodes which should be in the same replicaset have the same shard name.

For more details, you can find a tutorial for Sharding + Replication in the wiki.

MMS Agent

This cookbook also includes support for
MongoDB Monitoring System (MMS)
agent. MMS is a hosted monitoring service, provided by MongoDB, Inc. Once
the small agent program is installed on the MongoDB host, it
automatically collects the metrics and uploads them to the MMS server.
The graphs of these metrics are shown on the web page. It helps a lot
for tackling MongoDB related problems, so MMS is the baseline for all
production MongoDB deployments.

To setup MMS, simply set your keys in
node['mongodb']['mms_agent']['api_key'] and then add the
sc-mongodb::mms_monitoring_agent recipe to your run list. Your current keys
should be available at your MMS Settings page.

The agent install and configurations is also available via a custom resource for
wrapper cookbooks. This allows for further customization outside of this

mongodb_agent 'monitoring' do
  config {} # Key and value pairs that will be in the config file
  group 'group' # Group to own the config file
  package_url 'package_url' # Download URL of the agent package
  user 'user' # User to own the config file

User Management

--NOTE:-- Using the sc-mongodb::user_management is not secure since passwords are stored plain
text in your node attributes. Please concider using a wrapper recipe with encrypted data bags
when using this cookbook in production.

An optional recipe is sc-mongodb::user_management which will enable authentication in
the configuration file by default and create any users in the node['mongodb']['users'].
The users array expects a hash of username, password, roles, and database. Roles should be
an array of roles the user should have on the database given.

By default, authentication is not required on the database. This can be overridden by setting
the node['mongodb']['config']['auth'] attribute to true in the chef json.

If the auth configuration is true, it will try to create the node['mongodb']['admin'] user, or
update them if they already exist. Before using on a new database, ensure you're overwriting
the node['mongodb']['authentication']['username'] and node['mongodb']['authentication']['password'] to
something besides their default values.

To update the admin username or password after already having deployed the recipe with authentication
as required, simply change node['mongodb']['admin']['password'] to the new password while keeping the
value of node['mongodb']['authentication']['password'] the old value. After the recipe runs successfully,
be sure to change the latter variable to the new password so that subsequent attempts to authenticate will

There's also a user resource which has the actions :add, :modify and :delete. If modify is
used on a user that doesn't exist, it will be added. If add is used on a user that exists, it
will be modified.

If using this recipe with replication and sharding, ensure that the node['mongodb']['key_file_content']
is set. All nodes must have the same key file in order for the replica set to initialize successfully
when authentication is required. For mongos instances, set node['mongodb']['mongos_create_admin'] to
true to force the creation of the admin user on mongos instances.


This project exists thanks to all the people who contribute.


Thank you to all our backers!


Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

sc-mongodb Cookbook CHANGELOG

5.1.19 - 2023-10-26

5.1.18 - 2023-10-26

5.1.17 - 2023-10-03

5.1.16 - 2023-10-03

5.1.15 - 2023-06-01

  • Add support for Rocky Linux

5.1.14 - 2023-05-17

5.1.13 - 2023-05-03

5.1.12 - 2023-04-07

Standardise files with files in sous-chefs/repo-management

5.1.11 - 2023-04-01

5.1.10 - 2023-04-01

5.1.9 - 2023-04-01

Standardise files with files in sous-chefs/repo-management

5.1.8 - 2023-03-20

Standardise files with files in sous-chefs/repo-management

5.1.7 - 2023-03-15

Standardise files with files in sous-chefs/repo-management

5.1.6 - 2023-02-23

Standardise files with files in sous-chefs/repo-management

5.1.5 - 2023-02-16

5.1.4 - 2023-02-16

Standardise files with files in sous-chefs/repo-management

Standardise files with files in sous-chefs/repo-management

5.1.3 - 2023-02-14

5.1.2 - 2022-12-11

Standardise files with files in sous-chefs/repo-management

Standardise files with files in sous-chefs/repo-management

5.1.1 - 2022-02-17

  • Standardise files with files in sous-chefs/repo-management

5.1.0 - 2022-02-10

  • Use chef_gem for replicaset recipe

5.0.1 - 2022-02-08

  • Remove delivery folder

5.0.0 - 2022-01-07

  • Require Chef >= 15.3 for unified_mode
  • resolved cookstyle error: resources/agent.rb:1:1 refactor: Chef/Deprecations/ResourceWithoutUnifiedTrue
  • resolved cookstyle error: resources/user.rb:1:1 refactor: Chef/Deprecations/ResourceWithoutUnifiedTrue

4.1.3 - 2022-01-06

  • resolved regression in custom resource names (#272)

4.1.2 - 2021-08-30

  • Standardise files with files in sous-chefs/repo-management

4.1.1 - 2021-06-01

  • resolved cookstyle error: definitions/mongodb.rb:53:12 convention: Style/RedundantParentheses
  • resolved cookstyle error: libraries/mongodb_config_helpers.rb:21:5 warning: ChefDeprecations/UseYamlDump
  • resolved cookstyle error: libraries/user.rb:144:1 convention: Layout/TrailingWhitespace
  • resolved cookstyle error: libraries/user.rb:144:15 convention: Style/RedundantBegin
  • resolved cookstyle error: libraries/user.rb:145:13 convention: Layout/IndentationWidth
  • resolved cookstyle error: libraries/user.rb:146:17 convention: Layout/IndentationConsistency
  • resolved cookstyle error: libraries/user.rb:147:17 convention: Layout/IndentationConsistency
  • resolved cookstyle error: libraries/user.rb:149:17 convention: Layout/IndentationConsistency
  • resolved cookstyle error: libraries/user.rb:166:1 convention: Layout/TrailingWhitespace
  • resolved cookstyle error: libraries/user.rb:167:1 convention: Layout/EmptyLines
  • resolved cookstyle error: libraries/user.rb:168:15 convention: Layout/IndentationConsistency
  • resolved cookstyle error: libraries/user.rb:168:17 convention: Layout/IndentationConsistency
  • resolved cookstyle error: libraries/user.rb:169:15 convention: Layout/IndentationConsistency
  • resolved cookstyle error: libraries/user.rb:169:17 convention: Layout/IndentationConsistency
  • Resolve cookstyle issues
  • Comment out ChefSpec until defintions are converted to custom resources
  • Disable platforms that do not currently work
  • Remove testing on EL6


  • resolved cookstyle error: recipes/mongodb_org_repo.rb:31:53 convention: Layout/TrailingWhitespace
  • resolved cookstyle error: recipes/mongodb_org_repo.rb:31:54 refactor: ChefModernize/FoodcriticComments


  • Minimum Chef version 14
  • resolved cookstyle error: libraries/user.rb:116:15 refactor: ChefCorrectness/ChefApplicationFatal
  • resolved cookstyle error: libraries/user.rb:138:11 refactor: ChefCorrectness/ChefApplicationFatal
  • resolved cookstyle error: libraries/user.rb:172:13 refactor: ChefCorrectness/ChefApplicationFatal
  • resolved cookstyle error: libraries/user.rb:212:13 refactor: ChefCorrectness/ChefApplicationFatal
  • resolved cookstyle error: libraries/user.rb:222:15 refactor: ChefCorrectness/ChefApplicationFatal
  • resolved cookstyle error: metadata.rb:11:1 refactor: ChefModernize/UnnecessaryDependsChef14


  • Update CI tooling to actions
  • mongodb.rb (cluster_up_to_date?): optimize
  • Fix packages version pin for Debian
  • Fix user creation error with MongoDB 4.x
  • Simplify the platform checks
  • Remove specs for EOL platforms
  • Remove deprecated long_description metadata
  • Remove if respond_to? usage in metadata.rb
  • Remove the ChefSpec converge report


  • custom resource user resource
  • update CI tooling


  • Fixes issue where on debain based systems mongo is not updated if version is increased
  • Correct attribute usage (#186)
  • Fix Invalid Keyfile Option (#191)
  • Fix for issue where mongo would not upgrade on debian based systems (#181)
  • Use pgp keyfiles for debian packages (#193)

v1.0.1 Changes

  • Refactor replicaset configuration

v1.0.0 Changes (Released 2017-05-23)

WARNING: This is a rewrite that contains many backwards incompatable changes. Many attributes have changed defaults and/or the attribute key itself.

  • Drop support for 10gen repo and default to mongo-org repo install
  • Remove Chef 10 and 11 support
  • Update Mongo default version to 3.2.10
  • Drop support for Mongo < 3.0
  • Convert all test-kitchen verification to inspec
  • Change node['mongodb']['config'] to have mongos and mongod keys before actual config setting
  • Update apt and yum repo
  • Update MMS agent install to deb/rpm packages and add mongodb_agent resource
  • Fixup relicaset and shard helpers

v0.18.1 Changes

  • Fix cookbook name in attributes file

v0.18.0 Changes

  • Rename cookbook from mongodb to sc-mongodb (no attribute changes, should be 100% compatable with mongodb cookbook on supermarket)

NOTE v0.18.0 is the same as v0.17.0 with the exception of the cookbook name. All attributes have keped the mongodb namespace while the cookbook has been renamed sc-mongodb

v0.17.0 Changes

  • Add ability to use ipaddress instead of fqdn in replicaset
  • fix creating user bug for custom host and port
  • Add a new install method 'none' that doesn't install.
  • Add NUMA support to debian-mongodb upstart script
  • Moved the ulimit commands to the start function
  • fix for bug #348 - broken sharding
  • Get rid of chef_gem
  • Excluded Amazon Linux from using systemctl
  • pessimistically allow 1.X mongo gem
  • add custom repo support
  • Moved the running of the sysconfig_file above the NUMA support
  • replace deprecated recipe
  • bug fix in member_config for having_id > 255
  • User management in replicasets / sharding
  • Force rs.reconfig when there are no old members
  • Packager Options Attribute

v0.16.3 Changes (release never tagged, rolled into v0.17.0 release)

  • remove old runit dependency
  • fix user/group attribute variables for newer versions of EL and Fedora

v0.16.2 (Release Tue Nov 4 11:48:54 PST 2014)

  • start doing even patches = release, odd = dev.
  • removed unmaintained freebsd support file
  • pass --force-yes to apt to bypass issue with package/config conflict #305
  • bumped mms_agent version for monitoring and backup #312
  • added user management/auth support, and patches #313, #317
  • fix patches on logpath #310
  • allow changing mongos service name #319
  • update upstart config for debian #323
  • added fixes for installation prereqs, sasl
  • fix systemd usecase for redhat (#352, #350)


  • remove old mms_agent.rb and mms-agent.rb in favor of new mms_*_agent.rb
  • Update mms_*_agent.rb to use template instead of ruby-block, nothing, but call restart
  • DEPRECATE '10gen_repo' for 'mongodb_org_repo' #287
  • node['mongodb']['install_method'] can now be '10gen' (DEPRECATE) or 'mongodb_org'
  • allow `node['mongodb']['config']['logpath'] to be nil for syslog #288


  • BREAKING CHANGE - drop support for Ruby < 1.9, Chef < 11
  • cookbook dependency change

    • yum >= 3.0
    • remove <= limit for all other dep
  • update to Berkshelf 3

  • 280 fix install for centos (missing build-essentials)

v0.15.2 End of Ruby 1.8, Chef 10 support

  • update test-kitchen for mongos
  • update MMS version
  • update rubocop
  • minor typo fixes


  • 'potentially' BREAKING CHANGES, cookbook dependency pinned

    • yum < 3.0
    • runit < 1.5
    • python < 1.4.5
  • DEPRECATION: explicitly drop support for 'unsupported' platforms

    • must be freebsd, rhel, fedora, debian
  • DEPRECATION: recipe mms-agent.rb/mms_agent.rb

    • see #261 for new-recipes
  • use node.set to make sure is_* attributes are available for search

  • 'key_file' -> 'key_file_content'

  • allow pinning for gems, pip packages

  • 261 new mms agent recipe based on new packaging in upstream

  • 256 Allow mms_agent to be run as non-root user

    • replSet is not set automatically


  • DEPRECATION: backward compatability for dbconfig variables in node['mongodb']

    • use node['mongodb']['config'][variable] = value


  • Final 0.14 release
  • move node['mongodb']['config']['configsrv'] auto update to the top
  • Drop using Chef.Version as it is not rc/beta compatible
  • installs gem bson_ext


  • Rubocop (cherry pick of #220)


  • Automatically install bson_ext gem
  • Add check/protection for empty shard
  • Force node['mongodb']['config']['configsrv'] == true when set as configserver


  • try to autoconfigure 'configsrv' from configserver_nodes
  • remove include 'mongodb::default' from definition
  • allow chef-run without restarting mongo
  • comment cleanup


  • Split out install into separate recipe
  • Adds more testing
  • Fixes mms-agent installation/runtime
  • Preliminary Work being done to convert completely to Resource style
  • patches to Replicaset
  • patches to fix upstart service
  • patches to configserver install

v0.13.2, RELEASED

  • add support for chef_gem on newer versions of chef

v0.13.1, RELEASED

  • Add keyfileSupport

v0.13.0, RELEASED

  • Bunch of stuff...


Initial release of the cookbooks for the chef configuration management system developed at edelight GmbH. With this first release we publish the mongodb cookbook we use for our systems. This cookbook helps you to configure single node mongodb instances as well as more complicated cluster setups (including sharding and replication).

Collaborator Number Metric

5.1.19 passed this metric

Contributing File Metric

5.1.19 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must contain a file

Cookstyle Metric

5.1.19 passed this metric

No Binaries Metric

5.1.19 passed this metric

Testing File Metric

5.1.19 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must contain a file

Version Tag Metric

5.1.19 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must include a tag that matches this cookbook version number