diff --git a/docs/tutorial.md b/docs/tutorial.md index a082af4b..d06c9aef 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -15,7 +15,11 @@ Through the process, you'll inspect the Kubernetes resources created, verify the For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju). +:warning: When using a Multipass VM, make sure to replace `127.0.0.1` IP addresses with the +VM IP in steps that assume you're running locally. To get the IP address of the +Multipass instance run ```multipass info my-juju-vm```. ### Shell into the Multipass VM +> NOTE: If you're working locally, you don't need to do this step. To be able to work inside the Multipass VM first you need to log in with the following command: ```bash @@ -27,7 +31,7 @@ multipass shell my-juju-vm To manage resources effectively and to separate this tutorial's workload from your usual work, create a new model in the MicroK8s controller using the following command: -```bash +``` juju add-model indico-tutorial ``` @@ -39,7 +43,7 @@ Redis is deployed twice because one is for the broker and the other for the cach Deploy the charms: -```bash +``` juju deploy postgresql-k8s --trust juju deploy redis-k8s redis-broker --channel=latest/edge juju deploy redis-k8s redis-cache --channel=latest/edge @@ -48,14 +52,14 @@ juju deploy indico To see the pod created by the Indico charm, run `kubectl get pods -n indico-tutorial`, where the namespace is the name of the Juju model. The output is similar to the following: -```bash +``` NAME READY STATUS RESTARTS AGE indico-0 3/3 Running 0 6h4m ``` Run [`juju status`](https://juju.is/docs/olm/juju-status) to see the current status of the deployment. In the Unit list, you can see that Indico is waiting: -```bash +``` indico/0* waiting idle 10.1.74.70 Waiting for redis-broker availability ``` @@ -65,20 +69,20 @@ This means that Indico charm isn't integrated with Redis yet. Provide integration between Indico and Redis by running the following [`juju integrate`](https://juju.is/docs/juju/juju-integrate) commands: -```bash +``` juju integrate indico:redis-broker redis-broker juju integrate indico:redis-cache redis-cache ``` Run `juju status` to see that the message has changed: -```bash +``` indico/0* waiting idle 10.1.74.70 Waiting for database availability ``` Provide integration between Indico and PostgreSQL: -```bash +``` juju integrate indico postgresql-k8s:database ``` @@ -86,7 +90,7 @@ Note: `database` is the name of the integration. This is needed because establis Enable PostgreSQL extensions: -```bash +``` juju config postgresql-k8s plugin_pg_trgm_enable=true plugin_unaccent_enable=true ``` @@ -95,7 +99,7 @@ Run `juju status` and wait until the Application status is `Active` as the follo Optional: run `juju status --relations --watch 5s` to watch the status every 5 seconds with the Relations section. -```bash +``` App Version Status Scale Charm Channel Rev Address Exposed Message indico 3.3 active 1 indico 182 10.152.183.68 no ``` @@ -112,27 +116,27 @@ See more details in [Adding the Ingress Relation to a Charm](https://charmhub.io Enable the ingress on MicroK8s first: -```bash +``` sudo microk8s enable ingress ``` Deploy the charm NGINX Ingress Integrator: -```bash +``` juju deploy nginx-ingress-integrator ``` To check if RBAC is enabled run the following command: -```bash +``` microk8s status | grep rbac ``` If it is enabled, then the output should be like the following: -```bash +``` rbac # (core) Role-Based Access Control for authorisation ``` If the output is empty then RBAC is not enabled. -If your cluster has RBAC enabled, you'll be prompted to run the following (If you are working inside the Multipass VM, chances are you have RBAC enabled): -```bash +If your cluster has RBAC enabled, you'll be prompted to run the following: +``` juju trust nginx-ingress-integrator --scope cluster ``` @@ -140,20 +144,20 @@ Run `juju status` to verify the deployment. Provide integration between Indico and NGINX Ingress Integrator: -```bash +``` juju integrate indico nginx-ingress-integrator ``` To see the Ingress resource created, run `kubectl get ingress` on a namespace named for the Juju model you've deployed the Indico charm into. The output is similar to the following: -```bash +``` NAME CLASS HOSTS ADDRESS PORTS AGE indico-local-ingress public indico.local 127.0.0.1 80 2d ``` Run `juju status` to see the same Ingress IP in the `nginx-ingress-integrator` message: -```bash +``` nginx-ingress-integrator active 1 nginx-ingress-integrator stable 45 10.152.183.233 no Ingress IP(s): 127.0.0.1 ``` @@ -163,28 +167,12 @@ Usually a charm default hostname is the application name but since Indico requir If you are deploying to a local machine you need to add the `127.0.0.1` to the `/etc/hosts` file. The default hostname for the Indico application is `indico.local`. To resolve it to your Ingress IP, edit [`/etc/hosts`](https://manpages.ubuntu.com/manpages/kinetic/man5/hosts.5.html) file and add the following line accordingly: -```bash +``` 127.0.0.1 indico.local ``` Optional: run `echo "127.0.0.1 indico.local" >> /etc/hosts` to redirect the output of the command `echo` to the end of the file `/etc/hosts`. -If you are using a Multipass instance you need to forward the request from your local to the Multipass instance. -First get the Multipass instances IP address. Since the indico is served on the local address of the Multipass VM we need to use the ip address of the VM. To get the IP address of a Multipass instance run the following command: - -```bash -ip -4 -j route get 2.2.2.2 | jq -r '.[] | .prefsrc' -``` -The result should be something like this: -```bash -10.131.49.76 -``` - -Add the IP address to the `/etc/hosts` file: - -```bash -echo "10.131.49.76 indico.local" | sudo tee -a /etc/hosts -``` After that, visit `http://indico.local` in a browser and you'll be presented with a screen to create an initial admin account. @@ -194,13 +182,13 @@ After that, visit `http://indico.local` in a browser and you'll be presented wit Well done! You've successfully completed the Indico tutorial. To remove the model environment you created during this tutorial, use the following command. -```bash +``` juju destroy-model indico-tutorial --no-prompt --destroy-storage=true ``` -To remove the Multipass instance you created for this tutorial, use the following command. +If you used Multipass, to remove the Multipass instance you created for this tutorial, use the following command. -```bash +``` multipass delete --purge my-juju-vm ``` -Finally, remove the `10.131.49.76 indico.local` line from the `/etc/hosts` file. +Finally, remove the `127.0.0.1 indico.local` line from the `/etc/hosts` file.