Skip to content

Commit

Permalink
[upload-charm-docs] sync with Discourse (#207)
Browse files Browse the repository at this point in the history
  • Loading branch information
@deusebio
deusebio authored Jul 12, 2023
1 parent f2ea153 commit 82d0f37
Show file tree
Hide file tree
Showing 5 changed files with 51 additions and 50 deletions.
29 changes: 15 additions & 14 deletions docs/tutorial/t-deploy-mongodb.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ This is part of the [Charmed MongoDB Tutorial](/t/charmed-mongodb-tutorial/8061)

## Deploy

To deploy Charmed MongoDB, all you need to do is run the following command, which will fetch the charm from [Charmhub](https://charmhub.io/mongodb?channel=dpe/edge) and deploy it to your model:
To deploy Charmed MongoDB, all you need to do is run the following command, which will fetch the charm from [Charmhub](https://charmhub.io/mongodb?channel=5/edge) and deploy it to your model:
```shell
juju deploy mongodb --channel dpe/edge
juju deploy mongodb --channel 5/edge
```

Juju will now fetch Charmed MongoDB and begin deploying it to the LXD cloud. This process can take several minutes depending on how provisioned (RAM, CPU,etc) your machine is. You can track the progress by running:
Expand All @@ -20,20 +20,20 @@ Model Controller Cloud/Region Version SLA Timestamp
tutorial overlord localhost/localhost 2.9.37 unsupported 11:24:30Z
App Version Status Scale Charm Channel Rev Exposed Message
mongodb active 1 mongodb dpe/edge 96 no
mongodb active 1 mongodb 5/edge 96 no
Unit Workload Agent Machine Public address Ports Message
mongodb/0* active idle 0 10.23.62.156 27017/tcp
Machine State Address Inst id Series AZ Message
0 started 10.23.62.156 juju-d35d30-0 focal Running
0 started 10.23.62.156 juju-d35d30-0 jammy Running
```
To exit the screen with `juju status --watch 1s`, enter `Ctrl+c`.

## Access MongoDB
> **!** *Disclaimer: this part of the tutorial accesses MongoDB via the `admin` user. **Do not** directly interface with the admin user in a production environment. In a production environment [always create a separate user](https://www.mongodb.com/docs/manual/tutorial/create-users/) and connect to MongoDB with that user instead. Later in the section covering Relations we will cover how to access MongoDB without the admin user.*
The first action most users take after installing MongoDB is accessing MongoDB. The easiest way to do this is via the MongoDB shell, with `mongosh`. You can read more about the MongoDB shell [here](https://www.mongodb.com/docs/mongodb-shell/). For this part of the Tutorial we will access MongoDB via `mongosh`. Fortunately there is no need to install the Mongo shell, as `mongosh` is already installed on the units hosting the Charmed MongoDB application.
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](https://www.mongodb.com/docs/mongodb-shell/). 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](https://www.mongodb.com/docs/manual/reference/connection-string/). The URI for MongoDB contains information which is used to authenticate us to the database. We use a URI of the format:
Expand All @@ -45,7 +45,7 @@ Connecting via the URI requires that you know the values for `username`, `passwo

**Retrieving the username:** In this case, we are using the `admin` user to connect to MongoDB. Use `admin` as the username:
```shell
export DB_USERNAME="admin"
export DB_USERNAME="operator"
```

**Retrieving the password:** The password can be retrieved by running the `get-password` action on the Charmed MongoDB application:
Expand All @@ -58,16 +58,16 @@ unit-mongodb-0:
UnitId: mongodb/0
id: "2"
results:
admin-password: <password>
password: <password>
status: completed
timing:
completed: 2022-12-02 11:30:01 +0000 UTC
enqueued: 2022-12-02 11:29:57 +0000 UTC
started: 2022-12-02 11:30:01 +0000 UTC
```
Use the password under the result: `admin-password`:
Use the password under the result: `password`:
```shell
export DB_PASSWORD=$(juju run-action mongodb/leader get-password --wait | grep admin-password| awk '{print $2}')
export DB_PASSWORD=$(juju run-action mongodb/leader get-password --wait | grep password| awk '{print $2}')
```

**Retrieving the hosts:** The hosts are the units hosting the MongoDB application. The host’s IP address can be found with `juju status`:
Expand All @@ -82,7 +82,7 @@ Unit Workload Agent Machine Public address Ports Message
mongodb/0* active idle 0 <host IP> 27017/tcp Primary

Machine State Address Inst id Series AZ Message
0 started 10.23.62.156 juju-d35d30-0 focal Running
0 started 10.23.62.156 juju-d35d30-0 jammy Running

```
Set the variable `HOST_IP` to the IP address for `mongodb/0`:
Expand All @@ -101,7 +101,7 @@ export REPL_SET_NAME="mongodb"
```

### Generate the MongoDB URI
Now that we have the necessary fields to connect to the URI, we can connect to MongoDB with `mongosh` via the URI. We can create the URI with:
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:
```shell
export URI=mongodb://$DB_USERNAME:$DB_PASSWORD@$HOST_IP/$DB_NAME?replicaSet=$REPL_SET_NAME
```
Expand All @@ -111,15 +111,16 @@ echo $URI
```

### Connect via MongoDB URI
As said earlier, `mongosh` is already installed in Charmed MongoDB. To access the unit hosting Charmed MongoDB, ssh into it:
As said earlier, `mongo` is already installed in Charmed MongoDB as `charmed-mongodb.mongo`. To access the unit hosting Charmed MongoDB, ssh into it:
```shell
juju ssh mongodb/0
```
*Note if at any point you'd like to leave the unit hosting Charmed MongoDB, enter* `exit`.

While `ssh`d into `mongodb/0`, we can access `mongosh`, using the URI that we saved in the step [Generate the MongoDB URI](#generate-the-mongodb-uri).
While `ssh`d into `mongodb/0`, we can access `mongo`, using the URI that we saved in the step [Generate the MongoDB URI](#generate-the-mongodb-uri).

```shell
mongosh <saved URI>
charmed-mongodb.mongo <saved URI>
```

You should now see:
Expand Down
16 changes: 8 additions & 8 deletions docs/tutorial/t-enable-security.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Before enabling TLS on Charmed MongoDB we must first deploy the `TLS-certificate
juju deploy tls-certificates-operator --channel=edge
```

Wait until the `tls-certificates-operator` is ready to be configured. When it is ready to be configured `watch -c juju status --color`. Will show:
Wait until the `tls-certificates-operator` is ready to be configured. When it is ready to be configured `juju status --watch 1s`. Will show:
```
Model Controller Cloud/Region Version SLA Timestamp
tutorial overlord localhost/localhost 2.9.37 unsupported 09:24:12Z
Expand All @@ -29,9 +29,9 @@ mongodb/1 active idle 1 10.23.62.55 27017/tc
tls-certificates-operator/0* blocked idle 3 10.23.62.8 Configuration options missing: ['certificate', 'ca-certificate']
Machine State Address Inst id Series AZ Message
0 started 10.23.62.156 juju-d35d30-0 focal Running
1 started 10.23.62.55 juju-d35d30-1 focal Running
3 started 10.23.62.8 juju-d35d30-3 focal Running
0 started 10.23.62.156 juju-d35d30-0 jammy Running
1 started 10.23.62.55 juju-d35d30-1 jammy Running
3 started 10.23.62.8 juju-d35d30-3 jammy Running
```

Now we can configure the TLS certificates. Configure the `tls-certificates-operator` to use self signed certificates:
Expand All @@ -41,7 +41,7 @@ juju config tls-certificates-operator generate-self-signed-certificates="true" c
*Note: this tutorial uses [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate); self-signed certificates should not be used in a production cluster.*

### Enable TLS
After configuring the certificates `watch -c juju status --color` will show the status of `tls-certificates-operator` as active. To enable TLS on Charmed MongoDB, relate the two applications:
After configuring the certificates `juju status --watch 1s` will show the status of `tls-certificates-operator` as active. To enable TLS on Charmed MongoDB, relate the two applications:
```shell
juju relate tls-certificates-operator mongodb
```
Expand All @@ -56,14 +56,14 @@ Now ssh into `mongodb/0`:
```
juju ssh mongodb/0
```
After `ssh`ing into `mongodb/0`, we are now in the unit that is hosting Charmed MongoDB. Once TLS has been enabled we will need to change how we connect to MongoDB. Specifically we will need to specify the TLS CA file along with the TLS Certificate file. These are on the units hosting the Charmed MongoDB application in the folder `/etc/mongodb/`. If you enter: `ls /etc/mongodb/external*` you should see the external certificate file and the external CA file:
After `ssh`ing into `mongodb/0`, we are now in the unit that is hosting Charmed MongoDB. Once TLS has been enabled we will need to change how we connect to MongoDB. Specifically we will need to specify the TLS CA file along with the TLS Certificate file. These are on the units hosting the Charmed MongoDB application in the folder `/var/snap/charmed-mongodb/common/etc/mongod`. If you enter: `ls /var/snap/charmed-mongodb/common/etc/mongod/external*` you should see the external certificate file and the external CA file:
```shell
/etc/mongodb/external-ca.crt /etc/mongodb/external-cert.pem
/var/snap/charmed-mongodb/common/etc/mongod/external-ca.crt /var/snap/charmed-mongodb/common/etc/mongod/external-cert.pem
```

As before, we will connect to MongoDB via the saved MongoDB URI. Connect using the saved URI and the following TLS options:
```shell
mongosh mongodb://$DB_USERNAME:$DB_PASSWORD@$HOST_IP/$DB_NAME?replicaSet=$REPL_SET_NAME --tls --tlsCAFile /etc/mongodb/external-ca.crt --tlsCertificateKeyFile /etc/mongodb/external-cert.pem
charmed-mongodb.mongo mongodb://$DB_USERNAME:$DB_PASSWORD@$HOST_IP/$DB_NAME?replicaSet=$REPL_SET_NAME --tls --tlsCAFile /var/snap/charmed-mongodb/common/etc/mongod/external-ca.crt --tlsCertificateKeyFile /var/snap/charmed-mongodb/common/etc/mongod/external-cert.pem
```

Congratulations, you've now connected to MongoDB with TLS. Now exit the MongoDB shell by typing:
Expand Down
16 changes: 8 additions & 8 deletions docs/tutorial/t-manage-passwords.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,14 @@ unit-mongodb-0:
UnitId: mongodb/0
id: "2"
results:
admin-password: <password>
password: <password>
status: completed
timing:
completed: 2022-12-02 11:30:01 +0000 UTC
enqueued: 2022-12-02 11:29:57 +0000 UTC
started: 2022-12-02 11:30:01 +0000 UTC
```
The admin password is under the result: `admin-password`.
The admin password is under the result: `password`.


### Rotate the admin password
Expand All @@ -38,18 +38,18 @@ unit-mongodb-0:
UnitId: mongodb/0
id: "4"
results:
admin-password: <new password>
password: <new password>
status: completed
timing:
completed: 2022-12-02 14:53:30 +0000 UTC
enqueued: 2022-12-02 14:53:25 +0000 UTC
started: 2022-12-02 14:53:28 +0000 UTC
```
The admin password is under the result: `admin-password`. It should be different from your previous password.
The admin password is under the result: `password`. It should be different from your previous password.

*Note when you change the admin password you will also need to update the admin password the in MongoDB URI; as the old password will no longer be valid.* Update the DB password used in the URI and update the URI:
```shell
export DB_PASSWORD=$(juju run-action mongodb/leader get-password --wait | grep admin-password| awk '{print $2}')
export DB_PASSWORD=$(juju run-action mongodb/leader get-password --wait | grep password| awk '{print $2}')
export URI=mongodb://$DB_USERNAME:$DB_PASSWORD@$HOST_IP/$DB_NAME?replicaSet=$REPL_SET_NAME
```

Expand All @@ -64,17 +64,17 @@ unit-mongodb-0:
UnitId: mongodb/0
id: "4"
results:
admin-password: <password>
password: <password>
status: completed
timing:
completed: 2022-12-02 14:53:30 +0000 UTC
enqueued: 2022-12-02 14:53:25 +0000 UTC
started: 2022-12-02 14:53:28 +0000 UTC
```
The admin password under the result: `admin-password` should match whatever you passed in when you entered the command.
The admin password under the result: `password` should match whatever you passed in when you entered the command.

*Note that when you change the admin password you will also need to update the admin password in the MongoDB URI, as the old password will no longer be valid.* To update the DB password used in the URI:
```shell
export DB_PASSWORD=$(juju run-action mongodb/leader get-password --wait | grep admin-password| awk '{print $2}')
export DB_PASSWORD=$(juju run-action mongodb/leader get-password --wait | grep password| awk '{print $2}')
export URI=mongodb://$DB_USERNAME:$DB_PASSWORD@$HOST_IP/$DB_NAME?replicaSet=$REPL_SET_NAME
```
18 changes: 9 additions & 9 deletions docs/tutorial/t-managing-units.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,12 @@ mongodb/1 active idle 1 10.23.62.55 27017/tcp
mongodb/2 active idle 2 10.23.62.243 27017/tcp
Machine State Address Inst id Series AZ Message
0 started 10.23.62.156 juju-d35d30-0 focal Running
1 started 10.23.62.55 juju-d35d30-1 focal Running
2 started 10.23.62.243 juju-d35d30-2 focal Running
0 started 10.23.62.156 juju-d35d30-0 jammy Running
1 started 10.23.62.55 juju-d35d30-1 jammy Running
2 started 10.23.62.243 juju-d35d30-2 jammy Running
```

You can trust that Charmed MongoDB added these replicas correctly. But if you wanted to verify the replicas got added correctly you could connect to MongoDB via `mongosh`. Since your replica set has 2 additional hosts you will need to update the hosts in your URI. You can retrieve these host IPs with:
You can trust that Charmed MongoDB added these replicas correctly. But if you wanted to verify the replicas got added correctly you could connect to MongoDB via `charmed-mongodb.mongo`. Since your replica set has 2 additional hosts you will need to update the hosts in your URI. You can retrieve these host IPs with:
```shell
export HOST_IP_1=$(juju run --unit mongodb/1 -- hostname -I | xargs)
export HOST_IP_2=$(juju run --unit mongodb/2 -- hostname -I | xargs)
Expand All @@ -50,14 +50,14 @@ Now view and save the output of the URI:
echo $URI
```

Like earlier we access `mongosh` by `ssh`ing into one of the Charmed MongoDB hosts:
Like earlier we access `mongo` by `ssh`ing into one of the Charmed MongoDB hosts:
```shell
juju ssh mongodb/0
```

While `ssh`d into `mongodb/0`, we can access `mongosh`, using our new URI that we saved above.
While `ssh`d into `mongodb/0`, we can access `mongo` with `charmed-mongodb.mongo`, using our new URI that we saved above.
```shell
mongosh <saved URI>
charmed-mongodb.mongo <saved URI>
```

Now type `rs.status()` and you should see your replica set configuration. It should look something like this:
Expand Down Expand Up @@ -206,8 +206,8 @@ mongodb/0* active idle 0 10.23.62.156 27017/tcp Primary
mongodb/1 active idle 1 10.23.62.55 27017/tcp
Machine State Address Inst id Series AZ Message
0 started 10.23.62.156 juju-d35d30-0 focal Running
1 started 10.23.62.55 juju-d35d30-1 focal Running
0 started 10.23.62.156 juju-d35d30-0 jammy Running
1 started 10.23.62.55 juju-d35d30-1 jammy Running
```

Expand Down
22 changes: 11 additions & 11 deletions docs/tutorial/t-relate-mongodb.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ juju deploy data-integrator --channel edge --config database-name=test-database
```
The expected output:
```
Located charm "data-integrator" in charm-hub, revision 3
Deploying "data-integrator" from charm-hub charm "data-integrator", revision 3 in channel edge on jammy
Located charm "data-integrator" in charm-hub...
Deploying "data-integrator" from charm-hub charm "data-integrator"...
```

### Relate to MongoDB
Expand All @@ -31,16 +31,16 @@ tutorial overlord localhost/localhost 2.9.37 unsupported 10:32:09Z
App Version Status Scale Charm Channel Rev Exposed Message
data-integrator active 1 data-integrator edge 3 no
mongodb active 2 mongodb dpe/edge 96 no
mongodb active 2 mongodb 5/edge 96 no
Unit Workload Agent Machine Public address Ports Message
data-integrator/0* active idle 5 10.23.62.216 received mongodb credentials
mongodb/0* active idle 0 10.23.62.156 27017/tcp
mongodb/1 active idle 1 10.23.62.55 27017/tcp Primary
Machine State Address Inst id Series AZ Message
0 started 10.23.62.156 juju-d35d30-0 focal Running
1 started 10.23.62.55 juju-d35d30-1 focal Running
0 started 10.23.62.156 juju-d35d30-0 jammy Running
1 started 10.23.62.55 juju-d35d30-1 jammy Running
5 started 10.23.62.216 juju-d35d30-5 jammy Running
```
To retrieve information such as the username, password, and database. Enter:
Expand Down Expand Up @@ -74,12 +74,12 @@ Notice that in the previous step when you typed `juju run-action data-integrator
```shell
juju ssh mongodb/0
```
Then access `mongosh` with the URI that you copied above:
Then access `mongo` with the URI that you copied above:

```shell
mongosh "<uri copied from juju run-action data-integrator/leader get-credentials --wait>"
charmed-mongodb.mongo "<uri copied from juju run-action data-integrator/leader get-credentials --wait>"
```
*Note: be sure you wrap the URI in `"` with no trailing whitespace*.
***Note: be sure you wrap the URI in `"` with no trailing whitespace*.**

You will now be in the mongo shell as the user created for this relation. When you relate two applications Charmed MongoDB automatically sets up a user and database for you. Enter `db.getName()` into the MongoDB shell, this will output:
```shell
Expand Down Expand Up @@ -122,9 +122,9 @@ juju remove-relation mongodb data-integrator
Now try again to connect to the same URI you just used in [Access the related database](#access-the-related-database):
```shell
juju ssh mongodb/0
mongosh "<uri copied from juju run-action data-integrator/leader get-credentials --wait>"
charmed-mongodb.mongo "<uri copied from juju run-action data-integrator/leader get-credentials --wait>"
```
*Note: be sure you wrap the URI in `"` with no trailing whitespace*.
***Note: be sure you wrap the URI in `"` with no trailing whitespace*.**

This will output an error message:
```
Expand Down Expand Up @@ -157,7 +157,7 @@ Save the result listed with `uris:`.
You can connect to the database with this new URI:
```shell
juju ssh mongodb/0
mongosh "<uri copied from juju run-action data-integrator/leader get-credentials --wait>"
charmed-mongodb.mongo "<uri copied from juju run-action data-integrator/leader get-credentials --wait>"
```
*Note: be sure you wrap the URI in `"` with no trailing whitespace*.

Expand Down

0 comments on commit 82d0f37

Please sign in to comment.