'new: docs/tutorial/t-overview.md,docs/how-to/h-manage-passwords.md,d…

…ocs/reference/r-requirements.md,docs/explanation/e-users.md,docs/tutorial/t-enable-security.md,docs/how-to/h-manage-units.md,docs/index.md,docs/how-to/h-create-and-list-backups.md,docs/how-to/h-view-metrics.md,docs/reference/r-overview.md,docs/tutorial/t-deploy-mongodb.md,docs/how-to/h-restore-backup.md,docs/tutorial/t-cleanup-environment.md,docs/tutorial/t-managing-units.md,docs/tutorial/t-relate-mongodb.md,docs/tutorial/t-manage-passwords.md,docs/how-to/h-configure-s3.md,docs/how-to/h-enable-encryption.md,docs/how-to/h-migrate-cluster-via-restore.md,docs/tutorial/t-environment-setup.md' (#199)

Co-authored-by: upload-charms-docs-bot <upload-charms-docs-bot@users.noreply.github.com>

docs/explanation/e-users.md

@@ -0,0 +1,19 @@
+## Internal users explanations:
+
+The operator uses the following internal DB users:
+
+* `operator` - the user that charm.py uses to manage database/cluster.
+* `monitor` - the user for [COS integration](https://charmhub.io/mongodb/docs/h-view-metrics).
+* `backup` - the user to [perform/list/restore backups](https://charmhub.io/mongodb/docs/h-create-and-list-backups).
+
+The full list of internal users is available in charm [source code](https://github.com/canonical/mongodb-operator/blob/main/src/charm.py). The full dump of internal users (on the newly installed charm):
+
+```shell
+mongodb:PRIMARY> db.system.users.find()
+
+{ "_id" : "admin.operator", "userId" : UUID("40057ebb-1ab0-4534-afcf-1c01d0d23f7d"), "user" : "operator", "db" : "admin", "credentials" : { "SCRAM-SHA-256" : { "iterationCount" : 15000, "salt" : "JPTkW0Rpvm7ajlOw0dxs2icyWRhx+TC5VnthLQ==", "storedKey" : "A47RNOFNb/FZQvqnGRR4DLTMk43xdnmSZotZ33ehn/M=", "serverKey" : "weAbYuS8poCB8aaDeWy1l7iFLJH85ozN0HjW6I4gxOQ=" } }, "roles" : [ { "role" : "userAdminAnyDatabase", "db" : "admin" }, { "role" : "clusterAdmin", "db" : "admin" }, { "role" : "readWriteAnyDatabase", "db" : "admin" } ] }
+{ "_id" : "admin.monitor", "userId" : UUID("c0e215a6-e2db-483e-a11b-244fac46d3e6"), "user" : "monitor", "db" : "admin", "credentials" : { "SCRAM-SHA-256" : { "iterationCount" : 15000, "salt" : "jOcAgMd7fc+62y2RrqBH5vr4UHPi7N8qJEGvIg==", "storedKey" : "Cx8ozkCp5pKG34wLpcrZxuz9H/hdHrBGdxoRUadDVSI=", "serverKey" : "C8plW72KIbn/VRDD9l8dJ18XKuevu80DVzGGIRhFRxw=" } }, "roles" : [ { "role" : "read", "db" : "local" }, { "role" : "explainRole", "db" : "admin" }, { "role" : "clusterMonitor", "db" : "admin" } ] }
+{ "_id" : "admin.backup", "userId" : UUID("71816eb4-d51a-4437-b9d9-012fd66bf463"), "user" : "backup", "db" : "admin", "credentials" : { "SCRAM-SHA-256" : { "iterationCount" : 15000, "salt" : "SU/q8qPMjUlJSqzM1EmZkfFFusN4TsOa2M+E4Q==", "storedKey" : "Aw3t0gTW6A0E3+SlB6kK8UVQUXq1/rpUiCFo5oTeCAw=", "serverKey" : "xXRcVUNeiAgDGTMZU+BFexo7Y/yhpFRf7j8BjS4DFBI=" } }, "roles" : [ { "role" : "backup", "db" : "admin" }, { "role" : "pbmAnyAction", "db" : "admin" }, { "role" : "readWrite", "db" : "admin" }, { "role" : "clusterMonitor", "db" : "admin" }, { "role" : "restore", "db" : "admin" } ] }
+```
+**Note**: it is forbidden to use/manage described above users! They are dedicated to the operators logic!
+Please use [data-integrator](https://charmhub.io/postgresql/docs/t-integrations) charm to generate/manage/remove an external credentials.

docs/how-to/h-configure-s3.md

@@ -0,0 +1,24 @@
+Configuring S3-storage requires that you have a replica set with at least three-nodes deployed and access to S3 storage.
+  If you don't have a three node replica set read the [Managing Units How-To for K8s charm](/t/charmed-mongodb-k8s-tutorial-managing-your-units/10611) 
+
+Once you have a three-node replica set deployed, you can configure your settings for S3. Configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator).  Deploy and configure the s3-integrator charm:
+```
+juju deploy s3-integrator
+juju run s3-integrator/leader sync-s3-credentials access-key=<access-key-here> secret-key=<secret-key-here>
+juju config s3-integrator \
+    path="mongodb-vm/demo" \
+    region="us-west-2" \
+    bucket="pbm-test-bucket-1"
+```
+The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your s3 storage. 
+
+To pass these configurations to Charmed MongoDB, relate the two applications:
+```
+juju relate s3-integrator mongodb-k8s
+```
+
+You can also update your configuration options after relating:
+```
+juju config s3-integrator \
+    endpoint=<endpoint>
+```

docs/how-to/h-create-and-list-backups.md

@@ -0,0 +1,14 @@
+Creating and listing backups requires that you:
+* [Have a replica set with at least three-nodes deployed](/t/charmed-mongodb-k8s-tutorial-managing-your-units/10611)
+* Access to S3 storage
+* [Have configured settings for S3 storage](/t/charmed-mongodb-k8s-how-to-configuring-settings-for-s3/11692)
+
+Once you have a three-node replicaset that has configurations set for S3 storage, check that Charmed MongoDB is `active` and `idle` with `juju status`. Once Charmed MongoDB is `active` and `idle`, you can create your first backup with the `create-backup` command:
+```
+juju run mongodb-k8s/leader create-backup
+```
+
+You can list your available, failed, and in progress backups by running the `list-backups` command:
+```
+juju run mongodb-k8s/leader list-backups
+```

docs/how-to/h-enable-encryption.md

@@ -0,0 +1,43 @@
+# How to enable encryption
+**Note**:
+
+> The TLS settings here are for self-signed-certificates which are not recommended for production clusters, the tls-certificates-operator charm offers a variety of configurations, read more on the TLS charm here.
+
+## Enable TLS
+```shell
+# deploy the TLS charm 
+juju deploy tls-certificates-operator --channel=stable
+# add the necessary configurations for TLS
+juju config tls-certificates-operator generate-self-signed-certificates="true" ca-common-name="Test CA" 
+# to enable TLS relate the two applications 
+juju relate mongodb-k8s tls-certificates-operator
+```
+## Manage keys
+Updates to private keys for certificate signing requests (CSR) can be made via the set-tls-private-key action. Note passing keys to external/internal keys should only be done with base64 -w0 not cat. With three replicas this schema should be followed
+* Generate a shared internal key
+```shell
+openssl genrsa -out internal-key.pem 3072
+```
+* generate external keys for each unit
+```shell
+openssl genrsa -out external-key-0.pem 3072
+openssl genrsa -out external-key-1.pem 3072
+openssl genrsa -out external-key-2.pem 3072
+```
+* apply both private keys on each unit, shared internal key will be allied only on juju leader
+```shell
+juju run mongodb-k8s/0 set-tls-private-key "external-key=$(base64 -w0 external-key-0.pem)"  "internal-key=$(base64 -w0 internal-key.pem)"
+juju run mongodb-k8s/1 set-tls-private-key "external-key=$(base64 -w0 external-key-1.pem)"  "internal-key=$(base64 -w0 internal-key.pem)"
+juju run mongodb-k8s/2 set-tls-private-key "external-key=$(base64 -w0 external-key-2.pem)"  "internal-key=$(base64 -w0 internal-key.pem)"
+```
+* updates can also be done with auto-generated keys with
+```shell
+juju run mongodb/0 set-tls-private-key
+juju run mongodb/1 set-tls-private-key
+juju run mongodb/2 set-tls-private-key
+```
+
+## Disable TLS remove the relation
+```shell
+juju remove-relation mongodb tls-certificates-operator
+```

docs/how-to/h-manage-passwords.md

@@ -0,0 +1,27 @@
+# How to manage passwords
+## Internal operator user
+
+The operator user is used internally by the Charmed MongoDB Operator, the `set-password` action can be used to rotate its password.
+
+* To set a specific password for the operator user
+
+```shell
+juju run mongodb-k8s/leader set-password password=<password>
+```
+where <password> is the password you want to set
+
+* To randomly generate a password for the operator user
+
+```shell
+juju run mongodb-k8s/leader set-password
+```
+
+## Rotate application passwords
+
+To rotate the passwords of users created for related applications, the relation should be removed and related again. That process will generate a new user and password for the application.
+
+```shell
+juju remove-relation <application> mongodb-k8s
+juju add-relation <application> mongodb-k8s
+```
+where <application> is the name of your application

docs/how-to/h-manage-units.md

@@ -0,0 +1,17 @@
+# How to manage related applications
+
+## New `mongodb_client` interface:
+
+Relations to new applications are supported via the `mongodb_client` interface. To create a relation: 
+
+```shell
+juju relate mongodb-k8s <application>
+```
+where <application> is the name of your application
+
+To remove a relation:
+
+```shell
+juju remove-relation mongodb-k8s <application>
+```
+where <application> is the name of your application

docs/how-to/h-migrate-cluster-via-restore.md

@@ -0,0 +1,33 @@
+This is a How-To for restoring a backup that was made from the a *different* cluster, (i.e. cluster migration via restore). To perform a basic restore please reference the [Restore How-To](/t/charmed-mongodb-k8s-how-to-restore-a-backup/11694)
+
+Restoring a backup from a previous cluster to a current cluster requires that you:
+- Have a replica set with [at least three-nodes deployed](/t/charmed-mongodb-tutorial-managing-units/8620)
+- Access to S3 storage
+- [Have configured settings for S3 storage](/t/charmed-mongodb-k8s-tutorial-managing-your-units/10611)
+- Have the backups from the previous cluster in your S3-storage
+- Have the password from your previous cluster
+
+When you restore a backup from an old cluster, it will restore the password from the previous cluster to your current cluster. Set the password of your current cluster to the previous cluster’s password:
+```shell
+juju run mongodb-k8s/leader set-password password=<previous cluster password>
+```
+
+To view the available backups to restore you can enter the command `list-backups`: 
+```shell
+juju run mongodb-k8s/leader list-backups
+```
+
+This shows a list of the available backups (it is up to you to identify which `backup-id` corresponds to the previous-cluster):
+```shell
+    backups: |-
+      backup-id             | backup-type  | backup-status
+      ----------------------------------------------------
+      YYYY-MM-DDTHH:MM:SSZ  | logical      | finished
+```
+
+To restore your current cluster to the state of the previous cluster, run the `restore` command and pass the correct `backup-id` to the command:
+ ```shell
+juju run mongodb-k8s/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ
+```
+
+Your restore will then be in progress, once it is complete your cluster will represent the state of the previous cluster.

docs/how-to/h-restore-backup.md

@@ -0,0 +1,27 @@
+This is a How-To for performing a basic restore. To restore a backup that was made from the a *different* cluster, (i.e. cluster migration via restore), please reference the [Cluster Migration via Restore How-To K8s](/t/charmed-mongodb-k8s-how-to-cluster-migration-via-restore/11697):
+
+Restoring from a backup requires that you:
+- [Have a replica set with at least three-nodes deployed](/t/charmed-mongodb-k8s-tutorial-managing-your-units/10611)
+- Access to S3 storage
+- [Have configured settings for S3 storage](/t/charmed-mongodb-k8s-how-to-configuring-settings-for-s3/11692) 
+- [Have existing backups in your S3-storage](/t/charmed-mongodb-k8s-how-to-how-to-create-and-list-backups/11689)
+
+To view the available backups to restore you can enter the command `list-backups`: 
+```shell
+juju run mongodb-k8s/leader list-backups
+```
+
+This should show your available backups 
+```shell
+    backups: |-
+      backup-id             | backup-type  | backup-status
+      ----------------------------------------------------
+      YYYY-MM-DDTHH:MM:SSZ  | logical      | finished 
+```
+
+To restore a backup from that list, run the `restore` command and pass the `backup-id` to restore:
+ ```shell
+juju action mongodb-k8s/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ
+```
+
+Your restore will then be in progress.

docs/how-to/h-view-metrics.md

@@ -0,0 +1,61 @@
+## Viewing Metrics
+
+You can view Charmed MongoDB's metrics in two ways: by querying the metric endpoint directly or by viewing them in grafana.
+
+### Querying the metric endpoint
+
+Charmed MongoDB comes with [MongoDB Exporter](https://github.com/percona/mongodb_exporter) and provides replication and cluster metrics. The metrics can be queried by accessing the `http://<unit-ip>:9216/metrics` endpoint. To quickly view them you can do the following:
+
+1. First identify the unit which you would like to query by entering `juju status`. Choose a unit to gather metrics from and copy its "Address"
+
+2. Then `curl` the metrics endpoint for your unit of interest with `curl http://<unit-ip>:9216/metrics` this should show a long set of metrics.
+
+### Accessing metrics with grafana
+
+Charmed MongoDB provides integration with the [Canonical Observability Stack](https://charmhub.io/topics/canonical-observability-stack) - which allows you to view the metrics in a GUI. To view the GUI:
+
+1. Deploy cos-lite bundle in a Kubernetes environment. This can be done by following the [deployment tutorial](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s). Wait for the cos-lite bundle to become active and idle, by viewing `juju status`
+
+2. Switch back to your model which hosts Charmed MongoDB and consume the offers from the COS bundle
+
+```
+
+juju switch <model with Charmed MongoDB K8s>
+
+juju consume <k8s-controller-name>:admin/cos.prometheus-scrape
+
+juju consume <k8s-controller-name>:admin/cos.alertmanager-karma-dashboard
+
+juju consume <k8s-controller-name>:admin/cos.grafana-dashboards
+
+juju consume <k8s-controller-name>:admin/cos.loki-logging
+
+juju consume <k8s-controller-name>:admin/cos.prometheus-receive-remote-write
+
+```
+
+3. Now relate Charmed MongoDB to the applications within the cos bundle:
+
+```
+
+juju relate mongodb-k8s prometheus-scrape
+
+juju relate mongodb-k8s loki-logging
+
+juju relate mongodb-k8s grafana-dashboards
+
+```
+
+4. Watch `juju status` and wait for the model to become idle
+
+5. To view the dashboard we need to find the URL of grafana along with the password for the dashboard. Switch to the k8s model hosting the COS-lite bundle and show all applications
+
+```
+
+juju switch <model with cos bundle>
+
+juju status
+
+```
+
+under the report of juju status, the IP address of the grafana GUI should be listed as the "Address" for the application `grafana`. Copy this address and navigate to it in your browser. In your browser you should see a login. Use the username `admin`, to retrieve the password go back to your terminal and run the action: `juju run-action grafana/0 get-admin-password --wait` - use this password to access the grafana Dashboard.

docs/index.md

@@ -0,0 +1,64 @@
+# Charmed MongoDB K8s Documentation
+
+## Overview
+[MongoDB](https://github.com/mongodb/mongo) is a popular NoSQL database application. It stores its data with JSON-like documents creating a flexible user experience with easy-to-use data aggregation for data analytics. In addition, it is a distributed database, so vertical and horizontal scaling come naturally.
+
+Applications like MongoDB must be managed and operated in production environments. This means that MongoDB application administrators and analysts who run workloads in various infrastructures should be able to automate tasks for repeatable operational work. Technologies such as software operators encapsulate the knowledge, wisdom and expertise of a real-world operations team and codify it into a computer program that helps to operate complex server applications like MongoDB and other databases. Canonical has developed an open-source operator called Charmed MongoDB for this purpose.
+
+[The Charmed MongoDB Kubernetes (K8s)](https://charmhub.io/mongodb-k8s?channel=5/edge) operator deploys and operates MongoDB in multi-cloud environments using Kubernetes. Software operators are principally associated with Kubernetes, an open-source container orchestration system that facilitates the deployment and operation of complex server applications. As a concept, however, they can be applied equally to application and infrastructure operations on platforms beyond Kubernetes. They are especially popular on Kubernetes because they can help to reduce the complexity of operations on this powerful but complex platform.
+
+Charmed MongoDB (K8s Operator) is an enhanced, open source and fully-compatible drop-in replacement for the MongoDB Community Edition with advanced MongoDB enterprise features. It simplifies the deployment, scaling, design and management of MongoDB in production in a reliable way. In addition, you can use the operator to manage your MongoDB clusters with automation capabilities. It also offers replication, TLS, password rotation, easy-to-use application integration, backup, restore, and monitoring.
+
+Aside from a Kubernetes operator, Canonical developed another operator called [Charmed MongoDB (VM operator)](https://charmhub.io/mongodb?channel=5/edge) that operates on physical, Virtual Machines (VM) and a wide range of cloud and cloud-like environments, including AWS, Azure, OpenStack and VMWare.
+
+## Software and releases
+
+Charmed MongoDB (K8s Operator) uses the [Charmed MongoDB snap package](https://snapcraft.io/charmed-mongodb), which offers more features than the MongoDB Community version, such as backup and restores, monitoring and security features.
+
+To see the Charmed MongoDB features and releases, visit our [Github Releases](https://github.com/canonical/mongodb-k8s-operator/releases) and [ Release Notes](https://discourse.charmhub.io/t/release-notes-charmed-mongodb-5-k8s-operator/10040) page.
+
+## Charm version, environment and OS
+
+A charm version is a combination of both the application version and / (slash) the channel, e.g. `5/stable`, `5/candidate`, `5/edge`. The channels are ordered from the most stable to the least stable, candidate, and edge. More risky channels like edge are always implicitly available. So, if the candidate is listed, you can pull the candidate and edge. When stable is listed, all three are available.
+
+You can deploy the charm a stand-alone machine or cloud and cloud-like environments, including AWS, Azure, OpenStack and VMWare.
+
+The upper portion of this page describes the Operating System (OS) where the charm can run. For example, 5/stable is compatible and should run on a machine with Ubuntu 22.04 OS.
+
+#### Supported architectures
+
+*The charm should be running on architectures that support AVX* 
+
+To check your architecture please execute 
+```bash
+grep avx /proc/cpuinfo
+```
+
+or  
+```bash 
+grep avx2 /proc/cpuinfo
+```
+
+#### Supported Juju versions
+
+At the current moment the MongoDB K8S charm supports Juju 2.9.43 and Juju 3.1.5
+
+#### Security, Bugs and feature request
+
+If you find a bug in this operator or want to request a specific feature, here are the useful links:
+
+* Raise the issue or feature request in the [Canonical Github
+](https://github.com/canonical/mongodb-operator/issues)
+* Meet the community and chat with us if there are issues and feature requests in our [Mattermost Channel](https://chat.charmhub.io/charmhub/channels/data-platform).
+
+#### Contributing
+
+Please see the[ Juju SDK docs](https://juju.is/docs/sdk) for guidelines on enhancements to this charm following best practice guidelines, and[ CONTRIBUTING.md](https://github.com/canonical/mongodb-operator/blob/main/CONTRIBUTING.md) for developer guidance.
+
+#### Licence statement
+
+The Charmed MongoDB Operator is free software, distributed under the [Apache Software License, version 2.0](https://github.com/canonical/mongodb-operator/blob/main/LICENSE). It installs and operates Percona Server for MongoDB, which is licensed under the Server Side Public License (SSPL) version 1.
+
+#### Trademark Notice
+
+“MongoDB” is a trademark or registered trademark of MongoDB, Inc. Other trademarks are property of their respective owners. Charmed MongoDB is not sponsored, endorsed, or affiliated with MongoDB, Inc.

docs/reference/r-overview.md

@@ -0,0 +1,2 @@
+* [Configurations](https://charmhub.io/mongodb-k8s/configure?channel=5/edge)
+* [Actions](https://charmhub.io/mongodb-k8s/actions?channel=5/edge)

docs/reference/r-requirements.md

@@ -0,0 +1,9 @@
+## Minimum requirements
+
+Before we start, make sure your machine meets the following requirements:
+
+* Ubuntu 20.04 (focal) or later.
+* at least 8GB of RAM.
+* at least 2 CPU cores.
+* At least 20GB of available storage. For production deployment: at least 60GB of available storage on each host.
+* Access to the internet for downloading the required snaps and charms.