Skip to content
Snippets Groups Projects

Initial web terminal design doc

Merged Andrew Fontaine requested to merge afontaine/web-terminal-design-doc into master
+ 42
20
@@ -6,7 +6,7 @@ Epic: <https://gitlab.com/groups/gitlab-org/-/epics/11015>
Issue: <https://gitlab.com/gitlab-org/gitlab/-/issues/418264>
- As a user of a Kubernetes cluster that is connected to GitLab using the GitLab
agent, I would like to interact with the cluster via a terminal interface.
agent, I would like to interact with the cluster via a web terminal interface.
## Personas
@@ -16,8 +16,20 @@ Issue: <https://gitlab.com/gitlab-org/gitlab/-/issues/418264>
## User experience goal
- An agent administrator can manipulate a Kubernetes cluster that is conneected
via the GitLab agent with a terminal interface within GitLab.
- An agent administrator can manipulate a Kubernetes cluster that is connected
via the GitLab agent with a web terminal interface within GitLab.
- Users with user access may also reach the agent in a future iteration.
- The web terminal includes some commonly used tools to help with
- debugging workloads
- managing a cluster
- The user is restricted in the cluster by regular Kubernetes RBAC
The above functionality works without setting up any extra applications or tokens, but the agent for Kubernetes
Installing the suite of command line tools necessary to interact with the
kubernetes cluster can be hard or impossible in some environments. Corporate
machines may restrict access, and many mobile terminals available are
limited in what tools are available.
## Proposal
@@ -26,46 +38,53 @@ Issue: <https://gitlab.com/gitlab-org/gitlab/-/issues/418264>
```mermaid
sequenceDiagram
actor U as User
participant G as GitLab
participant F as GitLab FE
participant G as GitLab BE
participant S as KAS
participant A as Agent
participant K as Kubernetes Cluster
U->>G: Select `Terminal` Tab
U->>F: Select `Terminal` Tab
U->>F: Press `Launch` Button
F-)G: Request shell image
G-)A: Deploy shell image pod
A-)+K: Deploy shell image pod
create participant P as Pod
K->>P: Deploy Pod
K->>A: Pod created
A->>G: Pod created
G->>F: Pod created
loop Poll for status
G->>+A: Get pod status
F->>+A: Get pod status
A->>+K: Get pod status
K->>-A: Return status
A->>-G: Return status
A->>-F: Return status
end
Note over G,A: When Pod status is Ready
Note over F,A: When Pod status is Ready
G-)A: Pod Attach
F-)A: Pod Attach
A-)K: Pod Attach
K-)P: Pod Attach
P->>G: WebSocket established
P->>F: WebSocket established
loop User entering commands
U->G: kubectl get pods --all-namespaces
G->P: kubectl get pods --all-namespaces
P->G: NAMESPACE NAME...
U->F: kubectl get pods --all-namespaces
F->P: kubectl get pods --all-namespaces
P->F: NAMESPACE NAME...
end
U->>G: exit
G->>P: exit
P->>G: Websocket disconnected
U->>F: exit
F->>P: exit
P->>F: Websocket disconnected
G-)A: delete Pod
F-)A: delete Pod
A-)K: delete Pod
destroy P
K-xP: delete Pod
K-)A: Pod deleted
A-)G: Pod deleted
A-)F: Pod deleted
```
### GitLab side
@@ -74,6 +93,9 @@ GitLab adds an API endpoint that applies a Kubernetes manifest to the cluster to
create a pod that uses the same service account as the agent to give users
access to the cluster API. This endpoint MAY return before the pod is `status: ready`.
The GitLab backend should be able to fetch the namespace and SA from the
agent/KAS to use in the manifest.
API Request and Response:
```rest
@@ -128,11 +150,11 @@ sending a `DELETE` to the `k8s-proxy` to clean up the resource. However, this is
not guaranteed, and so the agent should make a best effort to clean up these
pods once their status is `Completed`.
## Future iterations
- Implementing user imersonation (**PREMIUM**)
- Custom namespace and service account permissions (**ULTIMATE**)
- Custom container, namespace, and service account permissions (**ULTIMATE**)
- Workspaces support (**PREMIUM**)
## GitLab links
Loading