summaryrefslogtreecommitdiffstats
path: root/ansible_collections/community/mongodb/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'ansible_collections/community/mongodb/README.md')
-rw-r--r--ansible_collections/community/mongodb/README.md246
1 files changed, 246 insertions, 0 deletions
diff --git a/ansible_collections/community/mongodb/README.md b/ansible_collections/community/mongodb/README.md
new file mode 100644
index 000000000..cd86c4322
--- /dev/null
+++ b/ansible_collections/community/mongodb/README.md
@@ -0,0 +1,246 @@
+# MongoDB Version and PyMongoDB Version Compatibility
+
+- This collection is tested against the most recent two minor MongoDB releases, currently 5.0.X and 6.0.X.
+- ~This collection is tested against PyMongo version 3.12.X and latest.~ PyMongo 3.12.X dropped on 11.04.2023. Now PyMongo latest only.
+- This collection will not run against any MongoDB version lower than 4.0. You can set *strict_compatibility* to false to override this behaviour but don't expect 100% success. It might be a better approach to use an older release of this collection (1.3.4 or earlier) if you're using an old MongoDB version (3.6 or earlier).
+- Compatibility may be maintained for older software versions but is not guaranteed. Please upgrade your PyMongo driver version if you encounter difficulties with older versions.
+- ~Support for PyMongo versions less than 4.X will be dropped in the future.~ [Drop support for pymongo < 4.0?](https://github.com/ansible-collections/community.mongodb/issues/457) - Support for Pymongo < 4.0 now dropped from collection version 1.5.0
+
+# Mongodb Collection
+|Category|Status|
+|---|---|
+|Github CI|![CI](https://github.com/ansible-collections/community.mongodb/workflows/CI/badge.svg)|
+|Codecov|[![Codecov](https://img.shields.io/codecov/c/github/ansible-collections/community.mongodb)](https://codecov.io/gh/ansible-collections/community.mongodb)|
+|CI Roles|![CI_roles](https://github.com/ansible-collections/community.mongodb/workflows/CI_roles/badge.svg)|
+|AutomatingMongoDBWithAnsible|[![CI-basic](https://github.com/rhysmeister/AutomatingMongoDBWithAnsible/actions/workflows/CI-basic.yml/badge.svg)](https://github.com/rhysmeister/AutomatingMongoDBWithAnsible/actions/workflows/CI-basic.yml)|
+|AutomatingMongoDBWithAnsible|[![CI-etc](https://github.com/rhysmeister/AutomatingMongoDBWithAnsible/actions/workflows/CI-etc.yml/badge.svg)](https://github.com/rhysmeister/AutomatingMongoDBWithAnsible/actions/workflows/CI-etc.yml)|
+|AutomatingMongoDBWithAnsible|[![CI-resync](https://github.com/rhysmeister/AutomatingMongoDBWithAnsible/actions/workflows/CI-resync.yml/badge.svg)](https://github.com/rhysmeister/AutomatingMongoDBWithAnsible/actions/workflows/CI-resync.yml)|
+|AutomatingMongoDBWithAnsible|[![CI-upgrade-downgrade](https://github.com/rhysmeister/AutomatingMongoDBWithAnsible/actions/workflows/CI-upgrade-downgrade.yml/badge.svg)](https://github.com/rhysmeister/AutomatingMongoDBWithAnsible/actions/workflows/CI-upgrade-downgrade.yml)|
+|Latest Build|![Build & Publish Collection](https://github.com/ansible-collections/community.mongodb/workflows/Build%20&%20Publish%20Collection/badge.svg)|
+
+This collection called `mongodb` aims at providing all Ansible modules allowing to interact with MongoDB.
+The modules present in Ansible 2.9 are included in this collection and will benefit from the evolutions and quality requirements from this collection.
+
+As this is an independent collection, it can be released on its own release cadence.
+
+If you like this collection please give us a rating on [Ansible Galaxy](https://galaxy.ansible.com/community/mongodb).
+
+## Collection contents
+
+### Roles
+
+These roles prepare servers with Debian-based and RHEL-based distributions to run MongoDB. These roles should not be used to manage MongoDB instances that have been previously installed or configured through other means.
+
+- `community.mongodb.mongodb_linux`: A simple role to configure Linux Operating System settings, as advised in the [MongoDB Production Notes](https://docs.mongodb.com/manual/administration/production-notes/).
+- `community.mongodb.mongodb_selinux`: Configure SELinux for MongoDB.
+
+- `community.mongodb.mongodb_repository`: Configures a package repository for MongoDB on Debian and RedHat based platforms.
+- `community.mongodb.mongodb_install`: Install MongoDB packages on Debian and RedHat based platforms. This role, unlike all other roles, provides for installing specific versions of mongodb-org packages. Other roles merely validate that mongodb-org is installed/present; they do not install particular versions.
+
+These roles manage configuring and starting various MongoDB services.
+
+- `community.mongodb.mongodb_mongod`: Configure the `mongod` service (includes populating `mongod.conf`) which is a MongoDB replicaset or standalone server.
+- `community.mongodb.mongodb_mongos`: Configure the `mongos` service (includes populating `mongos.conf`) which only runs in a sharded MongoDB cluster.
+- `community.mongodb.mongodb_config`: Configure the CSRS Config Server Replicaset for a MongoDB sharded cluster. The CSRS is a special-purpose instance of `mongod` that hosts the `config` database for the sharded cluster. For standalone installations, please use the `mongodb_mongod` role instead.
+- `community.mongodb.mongodb_auth`: Configure auth on MongoDB servers. NB: The other MongoDB server config roles (`mongodb_mongod`, `mongodb_mongos`, `mongodb_config`) do not configure auth. Use this role in conjunction with the other roles.
+
+### Plugins
+
+#### Lookup Plugins
+- `community.mongodb.mongodb`: A lookup plugin that gets info from a collection using the MongoDB `find()` function.
+
+#### Cache Plugins
+- `community.mongodb.mongodb`: A cache plugin that stores the host fact cache records in MongoDB.
+
+#### Modules
+
+These modules are for any MongoDB cluster (standalone, replicaset, or sharded):
+
+- `community.mongodb.mongodb_index`: Creates or drops indexes on MongoDB collections.
+- `community.mongodb.mongodb_info`: Gather information about MongoDB instance.
+- `community.mongodb.mongodb_monitoring`: Manages the [free monitoring](https://docs.mongodb.com/manual/administration/free-monitoring/) feature.
+- `community.mongodb.mongodb_oplog`: [Resizes](https://docs.mongodb.com/manual/tutorial/change-oplog-size) the MongoDB oplog (MongoDB 3.6+ only).
+- `community.mongodb.mongodb_parameter`: Change an administrative parameter on a MongoDB server.
+- `community.mongodb.mongodb_role`: Manage [MongoDB Roles](https://www.mongodb.com/docs/upcoming/tutorial/manage-users-and-roles/).
+- `community.mongodb.mongodb_schema`: Manages MongoDB Document Schema Validators.
+- `community.mongodb.mongodb_shell`: Run commands via the MongoDB shell.
+- `community.mongodb.mongodb_shutdown`: Cleans up all database resources and then terminates the mongod/mongos process.
+- `community.mongodb.mongodb_user`: Adds or removes a user from a MongoDB database.
+
+These modules are only useful for replicaset (or sharded) MongoDB clusters:
+
+- `community.mongodb.mongodb_maintenance`: Enables or disables [maintenance](https://docs.mongodb.com/manual/reference/command/replSetMaintenance/) mode for a secondary member.
+- `community.mongodb.mongodb_replicaset`: Initialises a MongoDB replicaset.
+- `community.mongodb.mongodb_status`: Validates the status of the replicaset.
+- `community.mongodb.mongodb_stepdown`: [Step down](https://docs.mongodb.com/manual/reference/command/replSetStepDown/) the MongoDB node from a PRIMARY state.
+
+These modules are only useful for sharded MongoDB clusters:
+
+- `community.mongodb.mongodb_balancer`: Manages the MongoDB Sharded Cluster Balancer.
+- `community.mongodb.mongodb_shard`: Add or remove shards from a MongoDB Cluster.
+- `community.mongodb.mongodb_shard_tag`: Manage Shard Tags.
+- `community.mongodb.mongodb_shard_zone`: Manage Shard Zones.
+
+
+## community.mongodb Role Tags
+
+### General role tags
+
+These tags are applicable across all roles.
+
+|tags|comment|
+|----|-------|
+|mongodb|Tasks specific to MongoDB.|
+|debian|Tasks specific to Debian Family Operating Systems.|
+|redhat|Tasks specific to RedHat Family Operating Systems.|
+|pip|Tasks working with pip.|
+|vars|Tasks that load variables.|
+|pkg|Tasks that install packages.|
+|debug|Tasks that output debugging info.|
+|service|Tasks dealing with system services.|
+|setup|Tasks that are mainly executed during initial deployment.|
+|ci|Tasks that are specific to the community.mongodb CI code.|
+|linux|Tasks affecting Linux OS settings.|
+
+### Role Specific Tags
+
+These tags apply to the specific roles as indicated.
+
+|role|tag|comment|
+|----|---|-------|
+|mongodb_auth|admin_user|Tasks that work with the MongoDB Administrator user.|
+|mongodb_auth|app_user|Tasks that work with MongoDB app users.|
+
+## Running the integration and unit tests
+
+* Requirements
+ * [Python 3.5+](https://www.python.org/)
+ * [pip](https://pypi.org/project/pip/)
+ * [virtualenv](https://virtualenv.pypa.io/en/latest/) or [pipenv](https://pypi.org/project/pipenv/) if you prefer.
+ * [git](https://git-scm.com/)
+ * [docker](https://www.docker.com/)
+
+* Useful Links
+ * [Pip & Virtual Environments](https://docs.python-guide.org/dev/virtualenvs/)
+ * [Ansible Integration Tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html)
+
+The ansible-test tool requires a specific directory hierarchy to function correctly so please follow carefully.
+
+* Create the required directory structure. N-B. The ansible-test tool requires this format.
+
+```bash
+mkdir -p git/ansible_collections/community
+cd git/ansible_collections/community
+```
+
+# Usage Examples
+
+The following links provide various exampels for how the community.mongodb roles and modules can be used in real projects.
+
+* https://github.com/rhysmeister/AutomatingMongoDBWithAnsible (no longer maintained)
+* https://github.com/superset1/Ansible_role_mongodb
+* https://github.com/ansible-collections/community.mongodb/tree/master/roles/ROLENAME/molecule (replace ROLENAME, some full examples that we use in our testing)
+
+* Clone the required projects.
+
+```bash
+git clone https://github.com/ansible-collections/community.mongodb.git ./mongodb
+git clone https://github.com/ansible-collections/community.general.git ./general
+```
+
+* Create and activate a virtual environment.
+
+```bash
+virtualenv venv
+source venv/bin/activate
+```
+
+* Change to the project directory.
+
+```bash
+cd mongodb
+```
+
+* Install the devel branch of ansible-base.
+
+```bash
+pip install https://github.com/ansible/ansible/archive/devel.tar.gz --disable-pip-version-check
+```
+
+* Run integration tests for the mongodb_shard module.
+
+```bash
+ansible-test integration --docker default -v --color --python 3.6 mongodb_shard
+```
+
+* Run integration tests for the mongodb_status module.
+
+```bash
+ansible-test integration --docker default -v --color --python 3.6 mongodb_status
+```
+
+* Run integration tests for the mongodb_oplog module.
+
+```bash
+ansible-test integration --docker ubuntu1804 -v --color --python 3.6 mongodb_oplog
+```
+
+* Run tests for everything in the collection.
+
+```bash
+ansible-test integration --docker default -v --color --python 3.6
+```
+
+* Run the units tests
+
+```bash
+ansible-test units --docker default -v --color --python 3.6
+```
+
+## Release Notes
+
+Needs improvement but the general process for issuing a new release to Ansible Galaxy is as follows...
+
+- View commits since last release and copy text for release notes
+
+```bash
+git log 1.3.0..HEAD
+git log 1.3.0..HEAD --oneline
+```
+
+- Create a new branch
+- Update galaxy.yml with version and any other appropriate info
+- Update changelogs/changelog.yaml
+- Update CHANGELOG.rst
+- Create a pull request
+- Review and merge when happy
+- Tag release on the master branch
+
+```bash
+git tag <release>
+git push --tags
+```
+
+Automation will bundle the release and push to Galaxy. Should take around 10-15 minutes.
+
+## GitHub workflow
+
+* Maintainers would be members of this GitHub Repo
+* Branch protections could be used to enforce 1 (or 2) reviews from relevant maintainers [CODEOWNERS](.github/CODEOWNERS)
+
+## Contributing
+
+Any contribution is welcome and we only ask contributors to:
+* Provide *at least* integration tests for any contribution.
+* Create an issue for any significant contribution that would change a large portion of the codebase.
+* Unless there's a very good reason for it, i.e. it's a bug, we aim not to change default behaviour.
+
+## Stargazers over time
+
+[![Stargazers over time](https://starchart.cc/ansible-collections/community.mongodb.svg)](https://starchart.cc/ansible-collections/community.mongodb)
+
+## License
+
+GNU General Public License v3.0 or later
+
+See LICENSING to see the full text.