From 82d0f37a0f247ddd1272d984e3c5223aa6698972 Mon Sep 17 00:00:00 2001 From: deusebio Date: Wed, 12 Jul 2023 13:05:33 +0200 Subject: [PATCH] [upload-charm-docs] sync with Discourse (#207) --- docs/tutorial/t-deploy-mongodb.md | 29 +++++++++++++++-------------- docs/tutorial/t-enable-security.md | 16 ++++++++-------- docs/tutorial/t-manage-passwords.md | 16 ++++++++-------- docs/tutorial/t-managing-units.md | 18 +++++++++--------- docs/tutorial/t-relate-mongodb.md | 22 +++++++++++----------- 5 files changed, 51 insertions(+), 50 deletions(-) diff --git a/docs/tutorial/t-deploy-mongodb.md b/docs/tutorial/t-deploy-mongodb.md index 4d8ac8157..8f4ddadec 100644 --- a/docs/tutorial/t-deploy-mongodb.md +++ b/docs/tutorial/t-deploy-mongodb.md @@ -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: @@ -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: @@ -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: @@ -58,16 +58,16 @@ unit-mongodb-0: UnitId: mongodb/0 id: "2" results: - admin-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`: @@ -82,7 +82,7 @@ Unit Workload Agent Machine Public address Ports Message mongodb/0* active idle 0 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`: @@ -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 ``` @@ -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 +charmed-mongodb.mongo ``` You should now see: diff --git a/docs/tutorial/t-enable-security.md b/docs/tutorial/t-enable-security.md index eac4aef3a..0673c1517 100644 --- a/docs/tutorial/t-enable-security.md +++ b/docs/tutorial/t-enable-security.md @@ -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 @@ -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: @@ -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 ``` @@ -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: diff --git a/docs/tutorial/t-manage-passwords.md b/docs/tutorial/t-manage-passwords.md index d7ea599c3..a1bfce424 100644 --- a/docs/tutorial/t-manage-passwords.md +++ b/docs/tutorial/t-manage-passwords.md @@ -17,14 +17,14 @@ unit-mongodb-0: UnitId: mongodb/0 id: "2" results: - admin-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 @@ -38,18 +38,18 @@ unit-mongodb-0: UnitId: mongodb/0 id: "4" results: - admin-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 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 ``` @@ -64,17 +64,17 @@ unit-mongodb-0: UnitId: mongodb/0 id: "4" results: - admin-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 ``` \ No newline at end of file diff --git a/docs/tutorial/t-managing-units.md b/docs/tutorial/t-managing-units.md index e1aa339b5..7397dfb0a 100644 --- a/docs/tutorial/t-managing-units.md +++ b/docs/tutorial/t-managing-units.md @@ -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) @@ -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 +charmed-mongodb.mongo ``` Now type `rs.status()` and you should see your replica set configuration. It should look something like this: @@ -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 ``` diff --git a/docs/tutorial/t-relate-mongodb.md b/docs/tutorial/t-relate-mongodb.md index e2d0d5237..acb869410 100644 --- a/docs/tutorial/t-relate-mongodb.md +++ b/docs/tutorial/t-relate-mongodb.md @@ -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 @@ -31,7 +31,7 @@ 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 @@ -39,8 +39,8 @@ 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: @@ -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 "" +charmed-mongodb.mongo "" ``` -*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 @@ -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 "" +charmed-mongodb.mongo "" ``` -*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: ``` @@ -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 "" +charmed-mongodb.mongo "" ``` *Note: be sure you wrap the URI in `"` with no trailing whitespace*.