Update README for ssh-token service

README.md

@@ -1,38 +1,35 @@
-# Lagoon SSH Portal
+# Lagoon SSH services
 
 [![Release](https://github.com/uselagoon/lagoon-ssh-portal/actions/workflows/release.yaml/badge.svg)](https://github.com/uselagoon/lagoon-ssh-portal/actions/workflows/release.yaml)
 [![Coverage](https://coveralls.io/repos/github/uselagoon/lagoon-ssh-portal/badge.svg?branch=main)](https://coveralls.io/github/uselagoon/lagoon-ssh-portal?branch=main)
 [![Go Report Card](https://goreportcard.com/badge/github.com/uselagoon/lagoon-ssh-portal)](https://goreportcard.com/report/github.com/uselagoon/lagoon-ssh-portal)
 
-This is a cluster-local SSH service for [Lagoon](https://github.com/uselagoon/lagoon).
+This repository contains three related SSH services for [Lagoon](https://github.com/uselagoon/lagoon).
 
-## Architecture
+## SSH Portal
 
-The Lagoon SSH portal is implemented as a pair of services: `ssh-portal-api`, and `ssh-portal`.
-These two services communicate over a backend messaging system.
-Currently the message system used is [NATS](https://nats.io/).
+`ssh-portal` is a cluster-local SSH service which enables SSH access to running workloads in a Lagoon Remote.
+To perform authentication it communicates back to `ssh-portal-api` running in Lagoon Core, which responds with a true/false if the SSH key is valid for the requested Lagoon environment.
 
-There may be many instances of `ssh-portal` in many remote clusters communicating back to the `ssh-portal-api` in the core cluster.
+`ssh-portal` implements shell access with service and container selection [as described in the Lagoon documentation](https://docs.lagoon.sh/using-lagoon-advanced/ssh/#ssh-into-a-pod), but it does not implement token generation.
+Unlike the existing Lagoon SSH service, `ssh-portal` _only_ provides access to Lagoon environments running in the local cluster.
 
-### SSH Portal API
+## SSH Portal API
 
-`ssh-portal-api` is part of Lagoon Core, and serves requests from the `ssh-portal` service, which may be in a remote cluster.
+`ssh-portal-api` is part of Lagoon Core, and serves authentication and authorization queries from `ssh-portal` services running in a Lagoon Remote.
 
-`ssh-portal-api` is explicitly _not_ a public API and makes no guarantees about compatiblity.
+`ssh-portal-api` is explicitly _not_ a public API and makes no guarantees about compatibility.
 It is _only_ designed to cater to the requirements of `ssh-portal`.
 
-### SSH Portal
+## SSH Token
 
-`ssh-portal` is part of Lagoon Remote, and implements an SSH server which connects incoming SSH sessions with pods running in the cluster.
-To perform authentication it communicates back to `ssh-portal-api` running in Lagoon Core, which responds with a true/false if the SSH key is valid for the requested Lagoon environment.
+`ssh-token` is part of Lagoon Core, and it serves JWT token generation requests.
 
-`ssh-portal` implements shell access with service and container selection [as described in the Lagoon documentation](https://docs.lagoon.sh/using-lagoon-advanced/ssh/#ssh-into-a-pod), but it does not implement token generation.
-
-Unlike the existing Lagoon SSH service, `ssh-portal` _only_ provides access to Lagoon environments running in the local cluster.
+This service does not provide shell access.
+Instead, it authenticates users by SSH key and returns a user access token which can then be used to authenticate to the Lagoon API.
 
 ## Administration and Troubleshooting
 
-If a user gets an error from `ssh-portal` it may not contain much detail for security reasons.
-However it _will_ contain a Session ID (SID).
-The SID is logged by the `ssh-portal`, and is also passed to the `ssh-portal-api` and logged there too.
-This helps to correlate error messages in `ssh-portal` and `ssh-portal-api` logs with user connection errors.
+If a user gets an error from a Lagoon SSH service it may not contain much detail for security reasons.
+However it _will_ contain a Session ID (SID) which is logged alongside any other log messages produced by the SSH services.
+This helps to correlate error messages in service logs to reported user connection errors.