Get a Charmed MongoDB up and running
This is part of the Charmed MongoDB 5 K8s Tutorial. Please refer to this page for more information and the overview of the content.
Deploy
To deploy Charmed MongoDB K8s, all you need to do is run the following command, which will fetch the charm from Charmhub and deploy it to your model:
juju deploy mongodb-k8s --channel 5/edge
Juju will now fetch Charmed MongoDB and begin deploying it to the Kubernetes cloud. This process can take several minutes depending on how provisioned (RAM, CPU,etc) your machine is. You can track the progress by running:
watch -n 1 -c juju status
This command is useful for checking the status of Charmed MongoDB and gathering information about the pods hosting Charmed MongoDB. Some of the helpful information it displays include IP addresses, ports, state, etc. The command updates the status of Charmed MongoDB every second and as the application starts you can watch the status and messages of Charmed MongoDB change. Wait until the application is ready - when it is ready, watch -n 1 -c juju status will show:
Model Controller Cloud/Region Version SLA Timestamp
tutorial overlord microk8s/localhost 3.1.6 unsupported 15:33:40Z
App Version Status Scale Charm Channel Rev Address Exposed Message
mongodb-k8s active 1 mongodb-k8s 5/edge 27 10.152.183.20 no
Unit Workload Agent Address Ports Message
mongodb-k8s/0* active idle 10.1.42.137
Model Controller Cloud/Region Version SLA Timestamp
tutorial overlord microk8s/localhost 3.1.6 unsupported 15:33:41Z
To exit the screen with watch -n 1 -c juju status, run Ctrl+c.
You can also add --color parameter to the command. watch -n 1 -c juju status --color
Access MongoDB
! Disclaimer: this part of the tutorial accesses MongoDB via the
operatoruser, theoperatoruser is our admin user in Charmed MongoDB. Do not directly interface with theoperatoruser in a production environment. In a production environment always create a separate user and connect to MongoDB with that user instead. Later in the section covering Relations we will cover how to access MongoDB without theoperatoruser.
The first action most users take after installing MongoDB is accessing MongoDB. The easiest way to do this is via the MongoDB shell, with mongo. You can read more about the MongoDB shell here. For this part of the Tutorial we will access MongoDB via mongo. Fortunately there is no need to install the Mongo shell, as mongo is already installed on the units hosting the Charmed MongoDB application as charmed-mongodb.mongo.
MongoDB URI
Connecting to the database requires a Uniform Resource Identifier (URI), MongoDB expects a MongoDB specific URI. The URI for MongoDB contains information which is used to authenticate us to the database. We use a URI of the format:
mongo://<username>:<password>@<hosts>/<database name>?replicaSet=<replica set name>
Connecting via the URI requires that you know the values for username, password, hosts, database name, and the replica set name. We will show you how to retrieve the necessary fields and set them to environment variables.
Retrieving the username: In this case, we are using the operator user to connect to MongoDB. Use operator as the username:
export DB_USERNAME="operator"
Retrieving the password: The password can be retrieved by running the get-password action on the Charmed MongoDB application:
juju run mongodb-k8s/leader get-password
Running the command should output:
Running operation 1 with 1 task
- task 2 on unit-mongodb-k8s-0
Waiting for task 2...
password: INIsjvJmDsuaPY2Rta0fPzas0zVKO5AJ
Use the value of password under the result: password:
export DB_PASSWORD=$(juju run mongodb-k8s/leader get-password | grep password | awk '{print $2}')
Retrieving the hosts: In this case we are connecting to mongo inside mongodb-k8s/0
Set the variable HOST_IP to the IP address to mongodb-k8s-0.mongodb-k8s-endpoints:
export HOST_IP="mongodb-k8s-0.mongodb-k8s-endpoints"
Retrieving the database name: In this case we are connecting to the admin database. Use admin as the database name. Once we access the database via the MongoDB URI, we will create a test-db database to store data.
export DB_NAME="admin"
Retrieving the replica set name: The replica set name is the name of the application on Juju hosting MongoDB. The application name in this tutorial is mongodb-k8s. Use mongodb-k8s as the replica set name.
export REPL_SET_NAME="mongodb-k8s"
Generate the MongoDB URI
Now that we have the necessary fields to connect to the URI, we can connect to MongoDB with charmed-mongodb.mongo via the URI. We can create the URI with:
export URI=mongodb://$DB_USERNAME:$DB_PASSWORD@$HOST_IP:27017/$DB_NAME?replicaSet=$REPL_SET_NAME
Now view and save the output of the URI:
echo $URI
Connect via MongoDB URI
As said earlier, mongo is already installed in Charmed MongoDB K8s as mongo. To access the unit hosting Charmed MongoDB K8S, ssh into it pod:
juju ssh --container=mongod mongodb-k8s/0
Note if at any point you’d like to leave the unit hosting Charmed MongoDB K8S, type: exit.
While ssh’d into mongodb-k8s/0 unit, we can access mongo, using the URI that we saved in the step Generate the MongoDB URI.
mongo <URI>
You should now see:
Percona Server for MongoDB shell version v5.0.15-13
connecting to: mongodb://mongodb-k8s-0.mongodb-k8s-endpoints:27017/admin?compressors=disabled&gssapiServiceName=mongodb&replicaSet=mongodb-k8s
Implicit session: session { "id" : UUID("c695ac7d-9da6-4693-920d-bca4f2925feb") }
Percona Server for MongoDB server version: v5.0.15-13
================
Warning: the "mongo" shell has been superseded by "mongosh",
which delivers improved usability and compatibility.The "mongo" shell has been deprecated and will be removed in
an upcoming release.
For installation instructions, see
https://docs.mongodb.com/mongodb-shell/install/
================
---
The server generated these startup warnings when booting:
2023-05-12T12:31:55.774+00:00: Using the XFS filesystem is strongly recommended with the WiredTiger storage engine. See http://dochub.mongodb.org/core/prodnotes-filesystem
---
mongodb-k8s:PRIMARY>
You can now interact with MongoDB directly using any MongoDB commands. For example entering show dbs should output something like:
admin 0.000GB
config 0.000GB
local 0.000GB
Now that we have access to MongoDB we can create a database named test-db. To create this database type:
use test-db
Now lets create a user called testUser with read/write access to the database test-db that we just created. Type:
db.createUser({
user: "testUser",
pwd: "password",
roles: [
{ role: "readWrite", db: "test-db" }
]
})
You can verify that you added the user correctly by running the command show users into the mongo shell. This will output:
Successfully added user: {
"user" : "testUser",
"roles" : [
{
"role" : "readWrite",
"db" : "test-db"
}
]
}
Feel free to test out any other MongoDB commands. When you’re ready to leave the MongoDB shell you can just type exit. Once you’ve typed exit you will be back in the host of the mongodb-k8s/0 unit.
Exit this host by once again typing exit. Now you will be in your original shell where you first started the tutorial; here you can interact with Juju and Kubernetes.
Note: if you accidentally exit one more time you will leave your terminal session and all of the environment variables used in the URI will be removed. If this happens redefine these variables as described in the section that describes how to create the MongoDB URI.