From e5513e2ea45d93b5a9234e6fa1c6a70b68e801b9 Mon Sep 17 00:00:00 2001 From: Scott Leggett Date: Wed, 16 Nov 2022 13:54:53 +0800 Subject: [PATCH] chore: update README with ssh-token --- README.md | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 434bc3b4..b258c4e0 100644 --- a/README.md +++ b/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.