diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt index 42a0221..26c482d 100644 --- a/.custom_wordlist.txt +++ b/.custom_wordlist.txt @@ -36,16 +36,20 @@ juju Juju K8s Keystore +Kratos Kubeflow Kubernetes Launchpad ldap LDAP LTS +MacOS Makefile Matrix Mattermost +MicroK MicroK8s +Multipass MyST namespace namespaces @@ -63,6 +67,7 @@ OLM OpenFGA OpenID OpenLDAP +Ory Permalink PostgreSQL pre @@ -74,18 +79,22 @@ reStructuredText roadmap RTD Skype +Snapcraft SSH subdirectories subfolders subtree Terraform TLS +Traefik Ubuntu UbuntuSSO UI URI UUID VM +VM's +VMs webhook Websocket Xbox diff --git a/TODO.md b/TODO.md index 43675cf..2d3cd24 100644 --- a/TODO.md +++ b/TODO.md @@ -6,7 +6,7 @@ The following document describes missing JAAS documentation as well as any docs - ~~Deploy JAAS tutorial~~ (completed in deploy_jimm_microk8s.rst) - JAAS architecture - ~~Explain the difference between Juju, JAAS and jimmctl CLI tools.~~ (completed in cli_tools.rst) -- Auth doc explaining JIMM's authentication and authorization. +- Auth doc explaining JIMM's authentication and authorisation. - How to enable/deploy/use the dashboard. - JAAS Limitations - potentially (As an example, cross-controller relations don't work with JAAS currently) - Relating JIMM and COS stack - general observability. diff --git a/explanation/cli_tools.rst b/explanation/cli_tools.rst index 74c400d..8ff9492 100644 --- a/explanation/cli_tools.rst +++ b/explanation/cli_tools.rst @@ -20,9 +20,9 @@ Summary - A plugin to add more commands to the Juju CLI - A tool for admins of the JIMM server * - Installation Link - - `juju `__ - - `jaas `__ - - `jimmctl `__ + - `Snap package `__ + - `Snap package `__ + - `Snap package `__ * - Use - ``juju `` - ``juju jaas -h`` and ``juju `` @@ -52,7 +52,7 @@ However, JIMM offers some extra functionality and that is where ``jaas`` comes i The ``jaas`` CLI tool acts as a plugin for the Juju CLI. It is distributed as `a Snap `__. When you install both the Juju and JAAS snaps, they automatically connect via -Snapcraft's `content-interface `__ enabling new commands on the Juju CLI. +`content-interface `__ enabling new commands on the Juju CLI. To view a list of all the newly available commands run ``juju jaas -h``. diff --git a/tutorial/deploy_jimm_microk8s.rst b/tutorial/deploy_jimm_microk8s.rst index ab74faf..60a118b 100644 --- a/tutorial/deploy_jimm_microk8s.rst +++ b/tutorial/deploy_jimm_microk8s.rst @@ -17,7 +17,7 @@ For this tutorial you will need the following: Setup Multipass (Optional) -------------------------- -Multipass is a tool to launch Ubuntu VMs from Windows, Linux and MacOS. The remainder of this guide can be run from within a multipass VM to avoid affecting the host machine. +Multipass is a tool to launch Ubuntu VMs from Windows, Linux and MacOS. The remainder of this guide can be run from within a Multipass VM to avoid affecting the host machine. Start by running the following commands to install and start a Multipass VM, the optional section will define the VM's memory/CPU/disk usage. @@ -44,10 +44,10 @@ Now we can install our dependencies, note that Juju 3+ only works with a strictl sudo snap install juju --channel=3.5/stable Once you have the Juju CLI installed, you will need to bootstrap a Juju controller to your cloud. -We will be using Microk8s as our cloud. The Juju documentation has detailed instructions on how to bootstrap a controller +We will be using MicroK8s as our cloud. The Juju documentation has detailed instructions on how to bootstrap a controller for various clouds and machine types. -To begin, run the following commands to setup Microk8s. +To begin, run the following commands to setup MicroK8s. .. code:: bash @@ -92,7 +92,7 @@ Watch the deployment by running: juju status --watch 1s Eventually all application should reach an ``active`` state except for the ``kratos-external-idp-integrator`` application. This application allows you to connect your identity platform -to an external identity provider like Google, Github, Microsoft, etc. This is necessary because the identity provider only acts as an identity broker. +to an external identity provider like Google, GitHub, Microsoft, etc. This is necessary because the identity provider only acts as an identity broker. We recommend using the following `how-to `__ and choosing your preferred identity provider. Note that you can temporarily skip this step and return to it later, JIMM can still run without integrating the identity bundle to an external identity provider but login to JIMM will not work. @@ -110,10 +110,10 @@ Deploy JIMM ----------- Now we will deploy JIMM and its dependencies into a new model. Let's first explore however what JIMM's dependencies are and what they are used for. -- OpenFGA: The OpenFGA charm provides authorization, defining who is allowed to access what. -- PostgreSQL: PostgreSQL is JIMM's database of choice and stores persistent state. This Postgres instance is used by both JIMM and OpenFGA. -- Vault: The Vault charm is used for storing sensitive user secrets. JIMM can be configured to store in plain-text in Postgres but this is not recommended for a production environment. -- Ingress: There are various charms that provide ingress into a K8s cluster. JIMM supports `traefik-k8s `__ and `nginx-ingress-integrator `__, this tutorial will use the latter. +- OpenFGA: The OpenFGA charm provides authorisation, defining who is allowed to access what. +- PostgreSQL: PostgreSQL is JIMM's database of choice and stores persistent state. This PostgreSQL instance is used by both JIMM and OpenFGA. +- Vault: The Vault charm is used for storing sensitive user secrets. JIMM can be configured to store in plain-text in PostgreSQL but this is not recommended for a production environment. +- Ingress: There are various charms that provide ingress into a K8s cluster. JIMM supports `Traefik Ingress `__ and `Nginx Ingress Integrator `__, this tutorial will use the latter. .. note:: In a production environment you may want to structure your deployment slightly differently. @@ -150,7 +150,7 @@ Move onto the next step to initialise Vault. Initialise Vault ---------------- -The Vault charm has documentation on how to initiliaze it `here `__. But an abridged version of the steps are provided here. +The Vault charm has documentation on how to initialise it `here `__. But an abridged version of the steps are provided here. Install the Vault CLI client and the ``yq`` tool. @@ -240,7 +240,7 @@ Run the following commands: # A final redirect URL for login, normally set to the URL of the Juju dashboard. juju config jimm final-redirect-url="http://test-jimm.localhost/auth/whoami" -Note that the public and private key pairs must be generated by the `go macaroon bakery repo `__. +Note that the public and private key pairs must be generated by the `go macaroon bakery repository `__. To do this briefly run the following command, ensuring you have the ``go`` tool installed: .. code:: bash @@ -258,7 +258,7 @@ These values are only used internally between JIMM and Juju controllers. } At this point you can run ``juju status`` and you should observe JIMM is active. -Navigate to `http://test-jimm.localhost/debug/info `__ to verify your JIMM deployment. +Navigate to ``http://test-jimm.localhost/debug/info`` to verify your JIMM deployment. Using Your JIMM Deployment -------------------------- diff --git a/tutorial/index.rst b/tutorial/index.rst index d1bcb5e..4f4b655 100644 --- a/tutorial/index.rst +++ b/tutorial/index.rst @@ -8,4 +8,4 @@ This is a collection of tutorials covering JAAS. JAAS Basics Group and access management - Deploy JIMM on Microk8s + Deploy JIMM on MicroK8s