-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #135 from uselagoon/update-readme
Update README for ssh-token service
- Loading branch information
Showing
1 changed file
with
17 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,38 +1,35 @@ | ||
| # Lagoon SSH Portal | ||
| # Lagoon SSH services | ||
|
|
||
| [](https://github.com/uselagoon/lagoon-ssh-portal/actions/workflows/release.yaml) | ||
| [](https://coveralls.io/github/uselagoon/lagoon-ssh-portal?branch=main) | ||
| [](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. |