stepshell — A secure terminal for Kubernetes pods…

Pitch

Description

Comments

About this project

stepshell is an authenticated web terminal that allows users to open a shell into any running Kubernetes pod as themselves, not as a shared account. It utilizes the cluster's RBAC for authorization, ensuring minimal complexity without sacrificing security. Ideal for environments using Argo Workflows, it simplifies debugging and operational tasks.

Overview

stepshell is a secure, authenticated web terminal designed specifically for Kubernetes pods. It enhances Kubernetes' Role-Based Access Control (RBAC) by allowing users to shell into pods using their own identity, providing a robust audit trail without compromising security or usability. This tool addresses the limitations of conventional web terminals, which often force users to choose between functionality and security.

Key Features

Features and Benefits

Feature	Description
🔐 Real Per-User Identity	Utilizes OIDC authentication followed by Kubernetes impersonation to ensure that only authorized users can access pod resources, maintaining a clear audit record in the API server logs.
🐚 Support for Shell-Less Images	For distroless pods that lack a shell, stepshell allows for the attachment of an ephemeral debug container, enabling access to the pod's processes and filesystem.
🔗 Deep-Linkable Access	Create direct links to specific pods and commands, which can be integrated into dashboards or other UI solutions, improving accessibility and efficiency.
📦 Standalone Binary	A single Go binary that contains the entire web interface, eliminating the need for an external database. Session management is performed through encrypted cookies.
🧩 Optional Argo Workflows Integration	With `--argo.enabled`, users can browse workflows, and re-run steps with breakpoints, making debugging significantly easier within Argo Workflows.

Argo Workflows Support

When integrated with Argo Workflows, stepshell enhances the user experience by providing intuitive control over workflow processes. Users can pause and debug workflows directly, which is a functionality often neglected in other solutions.

stepshell workflow view with per-step shell and breakpoint

Architecture

stepshell operates in a simple, effective architecture that avoids complexity:

browser ──HTTPS──► stepshell ──impersonated REST/WebSocket──► kube-apiserver
 xterm.js           OIDC + AES-GCM cookie                      RBAC decides
d```

The absence of a database simplifies deployment and usage, while maintaining high security via encrypted sessions. 

## Security Considerations

With stepshell, each session utilizes AES-256-GCM cookies to ensure secure communication. Impersonation allows users to act on their own behalf, with permissions governed strictly by Kubernetes RBAC settings. 

### Development and Deployment

Developers can quickly set up a local instance for testing purposes or deploy the application in a Kubernetes environment using Helm with robust configuration options.  

### Example Commands

To deploy stepshell in a Kubernetes environment:
```bash
helm install stepshell ./charts/stepshell \
  --set baseURL=https://stepshell.example.com \
  --set oidc.issuer=https://dex.example.com \
  --set oidc.clientID=stepshell \
  --set oidc.clientSecret=<secret> \
  --set argo.uiURL=https://argo-workflows.example.com \
  --set ingress.enabled=true \
  --set-json 'rbac.allowedGroups=["your-oidc-group"]'

Conclusion

stepshell provides a seamless balance between security and usability for accessing Kubernetes pods, catering to both developers and DevOps teams alike. With its focus on authentication, real user identity, and ease of integration, it stands out as an essential tool for Kubernetes administrators and users who need reliable terminal access.