From 6c054655654038bd0e410b14b1c3c926b0e81ebe Mon Sep 17 00:00:00 2001
From: Kian Parvin <46668016+kian99@users.noreply.github.com>
Date: Tue, 28 May 2024 10:10:27 +0200
Subject: [PATCH] Add cli tools explanation doc (#44)

* Add cli tools explanation doc

* PR comments
---
 TODO.md                   |  5 +--
 explanation/cli_tools.rst | 71 +++++++++++++++++++++++++++++++++++++++
 explanation/index.rst     |  3 +-
 3 files changed, 75 insertions(+), 4 deletions(-)
 create mode 100644 explanation/cli_tools.rst

diff --git a/TODO.md b/TODO.md
index 9111c7c..43675cf 100644
--- a/TODO.md
+++ b/TODO.md
@@ -3,9 +3,9 @@
 The following document describes missing JAAS documentation as well as any docs that need to be modernized.
 
 ## Missing Docs
-- Deploy JAAS tutorial (including going all the way to adding a controller, model and application)
+- ~~Deploy JAAS tutorial~~ (completed in deploy_jimm_microk8s.rst)
 - JAAS architecture
-- Explain the difference between Juju, JAAS and jimmctl CLI tools.
+- ~~Explain the difference between Juju, JAAS and jimmctl CLI tools.~~ (completed in cli_tools.rst)
 - Auth doc explaining JIMM's authentication and authorization.
 - How to enable/deploy/use the dashboard.
 - JAAS Limitations - potentially (As an example, cross-controller relations don't work with JAAS currently)
@@ -15,6 +15,7 @@ The following document describes missing JAAS documentation as well as any docs
 - How to migrate existing Juju controllers and models to JAAS.
 - How to bootstrap JAAS with an admin user and create user permissions.
 - How to migrate models between Juju controllers in JAAS.
+- Documentation on the jaas cli extension snap.
 
 ## Docs requiring changes
 - how-to/add_controller (possibly merge add_controller_no_dns into the original)
diff --git a/explanation/cli_tools.rst b/explanation/cli_tools.rst
new file mode 100644
index 0000000..74c400d
--- /dev/null
+++ b/explanation/cli_tools.rst
@@ -0,0 +1,71 @@
+Understanding ``juju`` vs ``jaas`` vs ``jimmctl``
+=================================================
+
+This document aims to explain the differences between the various CLI tools you may encounter when using Juju and JAAS.
+
+=======
+Summary
+=======
+
+.. list-table::
+   :widths: 25 25 25 25
+   :header-rows: 0
+
+   * - 
+     - ``juju``
+     - ``jaas``
+     - ``jimmctl``
+   * - Purpose
+     - Used to interact with Juju/JIMM controllers
+     - A plugin to add more commands to the Juju CLI
+     - A tool for admins of the JIMM server
+   * - Installation Link
+     - `juju <https://snapcraft.io/juju>`__
+     - `jaas <https://snapcraft.io/jaas>`__
+     - `jimmctl <https://snapcraft.io/jimmctl>`__
+   * - Use
+     - ``juju <command>``
+     - ``juju jaas -h`` and ``juju <command>``
+     - ``jimmctl <command>``
+
+``juju``
+========
+
+The Juju ecosystem introduces the Juju CLI as the first way a user can interact with their Juju environment.
+
+The Juju CLI is provided as `a Snap <https://snapcraft.io/juju>`__ and allows you to communicate with a Juju controller.  
+
+More information on the Juju CLI is available `here <https://juju.is/docs/juju/juju-client>`__.  
+A full list of the Juju CLI commands is available `here <https://juju.is/docs/juju/juju-cli-commands>`__
+
+The Juju CLI shares the same name as the Juju project so it's helpful to understand via context or via the explicit use of 
+``juju`` when we are talking about the Juju CLI versus the Juju project.
+
+``jaas``
+========
+
+The JAAS ecosystem introduces the JIMM controller. A special controller that sits in front of your Juju controllers 
+and acts as an authorisation gateway and aggregator.
+
+Interacting with the JIMM controller is done in the same fashion as Juju controllers, i.e. one uses the Juju CLI.  
+However, JIMM offers some extra functionality and that is where ``jaas`` comes in.
+
+The ``jaas`` CLI tool acts as a plugin for the Juju CLI. It is distributed as `a Snap <https://snapcraft.io/jaas>`__.  
+When you install both the Juju and JAAS snaps, they automatically connect via 
+Snapcraft's `content-interface <https://snapcraft.io/docs/content-interface>`__ enabling new commands on the Juju CLI.
+
+To view a list of all the newly available commands run ``juju jaas -h``.
+
+These commands are intended to be used by all users of JAAS, giving you more capability with Juju.  
+
+``jimmctl``
+===========
+
+As mentioned above, at the centre of the JAAS ecosystem is the JIMM controller. The ``jimmctl`` CLI tool is intended for administrators
+of JIMM, to be used to debug permission issues, add controllers, access audit logs, etc.
+
+The ``jimmctl`` tool is also distributed as `a Snap <https://snapcraft.io/jimmctl>`__.  
+Use of the ``jimmctl`` tool requires that you are logged into the JIMM controller with the Juju CLI and that your user has administrator
+permissions on the controller. At this point you can run ``jimmctl`` to interact with the system.
+
+Try running ``jimmctl list-controllers`` to see which controllers are connected to JIMM.
diff --git a/explanation/index.rst b/explanation/index.rst
index 7f53bc8..542115e 100644
--- a/explanation/index.rst
+++ b/explanation/index.rst
@@ -8,8 +8,7 @@ Explanation
    JAAS overview <jaas_overview>
    JAAS tags <jaas_tags>
    JAAS security <jaas_security_scope>
-
-- `Candid`_ - authentication server
+   CLI Tools <cli_tools>
 
 - JIMM - Juju Intelligent Model Manager