Documentation

mongodb_user - Adds or removes a user from a MongoDB database.

Synopsis

  • Adds or removes a user from a MongoDB database.

Requirements

The below requirements are needed on the host that executes this module.

  • pymongo

Parameters

Parameter
Choices/Defaults
Comments
database
required
The name of the database to add/remove the user from
login_database
(added in 2.0)
The database where login credentials are stored
login_host
Default:
localhost
The host running the database
login_password
The password used to authenticate with
login_port
Default:
27017
The port to connect to
login_user
The username used to authenticate with
name
required
The name of the user to add or remove

aliases: user
password
The password to use for the user
replica_set
(added in 1.6)
Replica set to connect to (automatically connects to primary for writes)
roles
(added in 1.3)
Default:
readWrite
The database user roles valid values could either be one or more of the following strings: 'read', 'readWrite', 'dbAdmin', 'userAdmin', 'clusterAdmin', 'readAnyDatabase', 'readWriteAnyDatabase', 'userAdminAnyDatabase', 'dbAdminAnyDatabase'
Or the following dictionary '{ db: DATABASE_NAME, role: ROLE_NAME }'.
This param requires pymongo 2.5+. If it is a string, mongodb 2.4+ is also required. If it is a dictionary, mongo 2.6+ is required.
ssl
(added in 1.8)
Whether to use an SSL connection when connecting to the database
ssl_cert_reqs
(added in 2.2)
    Choices:
  • CERT_REQUIRED ←
  • CERT_OPTIONAL
  • CERT_NONE
Specifies whether a certificate is required from the other side of the connection, and whether it will be validated if provided.
state
    Choices:
  • present ←
  • absent
The database user state
update_password
(added in 2.1)
    Choices:
  • always ←
  • on_create
always will update passwords if they differ. on_create will only set the password for newly created users.

Notes

Note

Examples

# Create 'burgers' database user with name 'bob' and password '12345'.
- mongodb_user:
    database: burgers
    name: bob
    password: 12345
    state: present

# Create a database user via SSL (MongoDB must be compiled with the SSL option and configured properly)
- mongodb_user:
    database: burgers
    name: bob
    password: 12345
    state: present
    ssl: True

# Delete 'burgers' database user with name 'bob'.
- mongodb_user:
    database: burgers
    name: bob
    state: absent

# Define more users with various specific roles (if not defined, no roles is assigned, and the user will be added via pre mongo 2.2 style)
- mongodb_user:
    database: burgers
    name: ben
    password: 12345
    roles: read
    state: present
- mongodb_user:
    database: burgers
    name: jim
    password: 12345
    roles: readWrite,dbAdmin,userAdmin
    state: present
- mongodb_user:
    database: burgers
    name: joe
    password: 12345
    roles: readWriteAnyDatabase
    state: present

# add a user to database in a replica set, the primary server is automatically discovered and written to
- mongodb_user:
    database: burgers
    name: bob
    replica_set: belcher
    password: 12345
    roles: readWriteAnyDatabase
    state: present

# add a user 'oplog_reader' with read only access to the 'local' database on the replica_set 'belcher'. This is useful for oplog access (MONGO_OPLOG_URL).
# please notice the credentials must be added to the 'admin' database because the 'local' database is not syncronized and can't receive user credentials
# To login with such user, the connection string should be MONGO_OPLOG_URL="mongodb://oplog_reader:oplog_reader_password@server1,server2/local?authSource=admin"
# This syntax requires mongodb 2.6+ and pymongo 2.5+
- mongodb_user:
    login_user: root
    login_password: root_password
    database: admin
    user: oplog_reader
    password: oplog_reader_password
    state: present
    replica_set: belcher
    roles:
      - db: local
        role: read

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key
Returned
Description
user
string
success
The name of the user to add or remove.



Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Author

  • Elliott Foster (@elliotttf)
  • Julien Thebault (@lujeni)

Hint

If you notice any issues in this documentation you can edit this document to improve it.