Add JAAS diagram (#33)

* Add JAAS diagram (`.png` and `.xml`) Signed-off-by: Babak K. Shandiz <[email protected]> * Add `OIDC` to word list Signed-off-by: Babak K. Shandiz <[email protected]> * Add JAAS overview Signed-off-by: Babak K. Shandiz <[email protected]> * Add reference to JAAS overview Signed-off-by: Babak K. Shandiz <[email protected]> * Fix spelling error Signed-off-by: Babak K. Shandiz <[email protected]> * Update custom word list Signed-off-by: Babak K. Shandiz <[email protected]> * Fix spelling errors Signed-off-by: Babak K. Shandiz <[email protected]> --------- Signed-off-by: Babak K. Shandiz <[email protected]>
canonical · Apr 19, 2024 · 23a7a40 · 23a7a40
1 parent 9c01fa4
commit 23a7a40
Show file tree

Hide file tree

Showing 8 changed files with 210 additions and 33 deletions.
diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt
@@ -2,6 +2,7 @@ addons
 ADFS
 API
 APIs
+auditability
 aws
 balancer
 Candid
@@ -52,8 +53,11 @@ NFS
 Nginx
 NodePort
 ntp
+OAuth
+OAuth2
 observability
 OEM
+OIDC
 OLM
 OpenID
 OpenLDAP
@@ -72,6 +76,7 @@ SSH
 subdirectories
 subfolders
 subtree
+Terraform
 TLS
 Ubuntu
 UbuntuSSO
@@ -80,8 +85,6 @@ URI
 UUID
 VM
 webhook
+Websocket
 Xbox
-YAML
-Terraform
-OAuth
-OAuth2
+YAML
diff --git a/explanation/images/jaas.png b/explanation/images/jaas.png
diff --git a/explanation/images/jaas.xml b/explanation/images/jaas.xml
@@ -0,0 +1,139 @@
+<mxfile host="app.diagrams.net" modified="2024-04-10T11:32:02.695Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36" etag="lC1FTpHsNjcta-R7nc_D" version="23.1.5" type="device">
+  <diagram name="Page-1" id="EV_qxQZ5_PdJNHhAe8kb">
+    <mxGraphModel dx="2280" dy="735" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-23" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+          <mxGeometry x="240" y="280" width="320" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-10" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+          <mxGeometry x="60" y="40" width="160" height="180" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-21" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+          <mxGeometry x="-100" y="280" width="320" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-59" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-3" target="H8WSTWocPAUIBV2Nf5Ki-5">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-3" value="Juju Controller" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="80" y="160" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-5" value="Model" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="80" y="80" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-25" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-11" target="H8WSTWocPAUIBV2Nf5Ki-16">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-26" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-11" target="H8WSTWocPAUIBV2Nf5Ki-17">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-11" value="JIMM" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="80" y="320" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-13" value="Juju Dashboard" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="-80" y="400" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-14" value="Juju CLI" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="-70" y="460" width="110" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-15" value="Terraform&lt;br&gt;(Juju Terraform Provider)" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="-100" y="520" width="140" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-16" value="Authorisation (ReBAC)" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="-80" y="320" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-27" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-17" target="H8WSTWocPAUIBV2Nf5Ki-18">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-17" value="OIDC Provider&lt;br&gt;(Hydra)" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="260" y="320" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-18" value="IdP&lt;br&gt;(Kratos)" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="420" y="320" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-19" value="Cloud" style="text;strokeColor=none;align=center;fillColor=none;html=1;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="60" y="40" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-22" value="JAAS" style="text;strokeColor=none;align=center;fillColor=none;html=1;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-100" y="280" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-24" value="Authentication" style="text;strokeColor=none;align=center;fillColor=none;html=1;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="240" y="280" width="105" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-31" value="" style="shape=providedRequiredInterface;html=1;verticalLabelPosition=bottom;sketch=0;rotation=-180;" vertex="1" parent="1">
+          <mxGeometry x="60" y="410" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-42" value="" style="endArrow=none;html=1;rounded=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;entryPerimeter=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-13" target="H8WSTWocPAUIBV2Nf5Ki-31">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="115" y="520" as="sourcePoint" />
+            <mxPoint x="165" y="470" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-43" value="" style="shape=providedRequiredInterface;html=1;verticalLabelPosition=bottom;sketch=0;rotation=-180;" vertex="1" parent="1">
+          <mxGeometry x="60" y="470" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-44" value="" style="endArrow=none;html=1;rounded=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;entryPerimeter=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" target="H8WSTWocPAUIBV2Nf5Ki-43" source="H8WSTWocPAUIBV2Nf5Ki-14">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="80" y="480" as="sourcePoint" />
+            <mxPoint x="205" y="530" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-45" value="" style="shape=providedRequiredInterface;html=1;verticalLabelPosition=bottom;sketch=0;rotation=-180;" vertex="1" parent="1">
+          <mxGeometry x="60" y="530" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-46" value="" style="endArrow=none;html=1;rounded=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;entryPerimeter=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" target="H8WSTWocPAUIBV2Nf5Ki-45" source="H8WSTWocPAUIBV2Nf5Ki-15">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="80" y="540" as="sourcePoint" />
+            <mxPoint x="205" y="590" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-47" value="" style="endArrow=none;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;edgeStyle=orthogonalEdgeStyle;entryX=0.25;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-31" target="H8WSTWocPAUIBV2Nf5Ki-11">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="140" y="490" as="sourcePoint" />
+            <mxPoint x="120" y="400" as="targetPoint" />
+            <Array as="points">
+              <mxPoint x="110" y="420" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-50" value="" style="endArrow=none;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;edgeStyle=orthogonalEdgeStyle;entryX=0.75;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-45" target="H8WSTWocPAUIBV2Nf5Ki-11">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="89.75" y="614.75" as="sourcePoint" />
+            <mxPoint x="189.75" y="404.75" as="targetPoint" />
+            <Array as="points">
+              <mxPoint x="170" y="540" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-53" value="" style="endArrow=none;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-43" target="H8WSTWocPAUIBV2Nf5Ki-11">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="100" y="520" as="sourcePoint" />
+            <mxPoint x="150" y="470" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-54" value="" style="shape=providedRequiredInterface;html=1;verticalLabelPosition=bottom;sketch=0;rotation=-180;" vertex="1" parent="1">
+          <mxGeometry x="390" y="535" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-55" value="Juju Facades (interfaces)" style="text;strokeColor=none;align=center;fillColor=none;html=1;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="420" y="530" width="140" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-56" value="" style="shape=providedRequiredInterface;html=1;verticalLabelPosition=bottom;sketch=0;rotation=90;" vertex="1" parent="1">
+          <mxGeometry x="130" y="240" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-57" value="" style="endArrow=none;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;entryPerimeter=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-11" target="H8WSTWocPAUIBV2Nf5Ki-56">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="180" y="270" as="sourcePoint" />
+            <mxPoint x="230" y="220" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="H8WSTWocPAUIBV2Nf5Ki-58" value="" style="endArrow=none;html=1;rounded=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="H8WSTWocPAUIBV2Nf5Ki-56" target="H8WSTWocPAUIBV2Nf5Ki-3">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="59" y="270" as="sourcePoint" />
+            <mxPoint x="59" y="210" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/explanation/index.rst b/explanation/index.rst
@@ -5,6 +5,7 @@ Explanation
 .. toctree::
    :maxdepth: 1
 
+   JAAS overview <jaas_overview>
    JAAS tags <jaas_tags>
    JAAS security <jaas_security_scope>
 

diff --git a/explanation/jaas_overview.rst b/explanation/jaas_overview.rst
@@ -0,0 +1,34 @@
+JAAS Overview
+=============
+
+What is JAAS?
+-------------
+
+**JAAS** provides a single location to manage your Juju infrastructure by using the 
+Dashboard or using the same Juju CLI commands to create a high-level overview and 
+the ability to drill-in to the details when you need it.
+
+
+**JAAS** is useful for customers that do not want to maintain their own controllers
+in public clouds. Canonical's JAAS enables users to deploy their workloads
+in public clouds without the extra complexity and costs associated with running their
+own Juju controllers. JAAS is also useful for organisations 
+running their own Juju infrastructure giving them a single point of contact for 
+their entire real estate and, in combination with the Juju Dashboard, giving
+them a clear overview of their infrastructure.
+
+Architecture
+------------
+
+The diagram below shows an overall picture of JAAS architecture.
+
+.. image:: images/jaas.png
+
+As in the diagram JAAS consists of two main components: *Juju Intelligent Model Manager (JIMM)*
+and *ReBAC* Authorisation. Basically, JIMM implements a number of Juju facades and behaves as a
+*Juju Controller*, which under the hood proxies operations to underlying controllers. This enables
+other tools like Juju Dashboard or Juju CLI that expect a Juju Controller to communicate with, to
+seamlessly work with JIMM.
+
+For authentication of users or service accounts, JAAS requires an *OIDC Provider* that handles
+the standard OAuth flows including browser flow, device flow, and client credentials.
diff --git a/how-to/add_controller.rst b/how-to/add_controller.rst
@@ -46,7 +46,7 @@ Deploy controller
     +----------------------+----------------------+
     | Parameter            | Environment variable |
     +======================+======================+
-    | Controller nam       | $NAME                |
+    | Controller name      | $NAME                |
     +----------------------+----------------------+
     | Cloud                | $CLOUD               |
     +----------------------+----------------------+

diff --git a/how-to/add_controller_no_dns.rst b/how-to/add_controller_no_dns.rst
@@ -7,7 +7,7 @@ Introduction
 The :doc:`add_controller` doc is a full guide on how to setup a controller, provide it with a load balancer front-end and use the load-balancer to terminate TLS connections.
 This guide provides a simplified setup that shows how to get a controller up and running with JIMM without the need for a load-balancer and a DNS address.
 
-This guide is intended for testing and development purposes only as the Juju controller cannot be created in an HA (high availability) setup.
+This guide is intended for testing and development purposes only as the Juju controller cannot be created in an HA (high-availability) setup.
 
 Prerequisites
 -------------
@@ -16,27 +16,27 @@ For this tutorial you will need the following:
 
 - AWS credentials
 - Basic knowledge of juju
-- Admin access to a JIMM controller (see this tutorial). For this tutorial we will assume this JIMM is located at jimm.canonical.example.com
+- Admin access to a JIMM controller (see this tutorial). For this tutorial we will assume this JIMM is located at ``jimm.canonical.example.com``.
 
 Deploy controller
 -----------------
 
 1. First we will prepare some parameters for the new controller and export environment variables that we will use in this tutorial. 
 
-    The **controller name** is the name given to the controller both on the local system and within JIMM. For visibility this often includes the name of the JAAS system, the cloud, the cloud-region and some kind of unique identifier, for example jaas-aws-us-east-1-001. 
+    The **controller name** is the name given to the controller both on the local system and within JIMM. For visibility this often includes the name of the JAAS system, the cloud, the cloud-region and some kind of unique identifier, for example ``jaas-aws-us-east-1-001``. 
 
     The **cloud** is the cloud in which the controller is being bootstrapped. 
 
     The **cloud region** is the region in which the controller is being bootstrapped. 
 
-    The **Candid URL** is the URL of the candid server that is providing the centralized identity service for the JAAS system. 
+    The **Candid URL** is the URL of the candid server that is providing the centralised identity service for the JAAS system. 
 
     The **JIMM URL** is the URL of the JIMM system providing the JAAS service.
 
     +----------------------+----------------------+
     | Parameter            | Environment variable |
     +======================+======================+
-    | Controller nam       | $NAME                |
+    | Controller name      | $NAME                |
     +----------------------+----------------------+
     | Cloud                | $CLOUD               |
     +----------------------+----------------------+
@@ -56,12 +56,10 @@ Deploy controller
 
     ``juju switch controller``
 
-4.  Install the jaas snap that you download here (note that this will eventually change to be accessible from https://snapcraft.io/jimmctl):
-
-    https://drive.google.com/file/d/1LiOvVpVQ13V3x3l2PhgS2fTHDUtCEe7p/view?usp=sharing 
+4.  Install the JAAS snap that you download from `here <https://drive.google.com/file/d/1LiOvVpVQ13V3x3l2PhgS2fTHDUtCEe7p/view?usp=sharing>`_ (note that this will eventually change to be accessible from ``https://snapcraft.io/jimmctl``). 
 
 5. To add the bootstrapped controller to JIMM we need to create a controller-information document. To do this, run the following command:
-    The "--local" flag allows you to skip providing the DNS address of your Juju controller.
+    The ``--local`` flag allows you to skip providing the DNS address of your Juju controller.
 
     ``/snap/jaas/current/bin/jimmctl controller-info --local $NAME $NAME.yaml``
 
@@ -73,4 +71,6 @@ Deploy controller
 
     ``/snap/jaas/current/bin/jimmctl add-controller $NAME.yaml``
 
-Following these steps you added an AWS controller to your JIMM. You should now be able to add models in AWS: juju add-model test aws
+Following these steps you added an AWS controller to your JIMM. You should now be able to add models in AWS: 
+
+    ``juju add-model test aws``