k8shelld

package
v0.29.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 1, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppStatusToProto

func AppStatusToProto(u *AppStatus) *k8shelldv1.AppStatus

func LogTypeFromProto

func LogTypeFromProto(logType k8shelldv1.LogType) string

func LogTypeToProto

func LogTypeToProto(logType string) k8shelldv1.LogType

func SystemInfoToProto

func SystemInfoToProto(si *SystemInfo) *k8shelldv1.SystemInfoResponse

Types

type ApiServer

type ApiServer struct {
	Enabled bool   `yaml:"enabled"`
	Address string `yaml:"address"`
}

ApiServer holds the API server address and enable flag.

type AppRuntimeStatus

type AppRuntimeStatus string

AppRuntimeStatus represents the lifecycle status reported by AppManager.

const (
	AppStatusUnknown      AppRuntimeStatus = "-"
	AppStatusNotInstalled AppRuntimeStatus = "NOT-INSTALLED"
	AppStatusInstalling   AppRuntimeStatus = "INSTALLING"
	AppStatusNotStarted   AppRuntimeStatus = "STOPPED"
	AppStatusPending      AppRuntimeStatus = "PENDING"
	AppStatusRunning      AppRuntimeStatus = "RUNNING"
	AppStatusInvalid      AppRuntimeStatus = "INVALID"
)

func (AppRuntimeStatus) IsValid

func (s AppRuntimeStatus) IsValid() bool

func (AppRuntimeStatus) String

func (s AppRuntimeStatus) String() string

type AppStatus

type AppStatus struct {
	Name     string           `json:"name"`
	Status   AppRuntimeStatus `json:"status"`
	Version  string           `json:"version"`
	Port     int              `json:"port"`
	PID      int              `json:"pid"`
	Age      string           `json:"age"`
	Restarts int              `json:"restarts"`
	Protocol string           `json:"protocol"`
}

AppStatus represents the current status of an application

func AppStatusFromProto

func AppStatusFromProto(u *k8shelldv1.AppStatus) *AppStatus

type BufferedReadWriter

type BufferedReadWriter interface {
	io.ReadWriter
	ReadBufferSize() (int, error)
	Stderr() io.Writer
}

BufferedReadWriter is an interface that is used to read and write data with buffer size checking and stderr support.

type CommandHandler

type CommandHandler func(ctx context.Context, command string) (string, error)

CommandHandler defines the signature for processing incoming commands. It receives the command string and returns the reply string (or an error).

type Config

type Config struct {
	System           System           `yaml:"system"`
	SaToken          SaToken          `yaml:"saToken"`
	TerminateOrphans TerminateOrphans `yaml:"terminateOrphans"`
	ReapZombies      ReapZombies      `yaml:"reapZombies"`
	Shells           Shells           `yaml:"shells,omitempty"`
}

Config is the root structure of k8shelld's config.yaml.

type ConnCounters

type ConnCounters struct {
	// contains filtered or unexported fields
}

ConnCounters holds counters for bytes sent and received.

func (*ConnCounters) AddIn

func (c *ConnCounters) AddIn(n int)

AddIn adds to the incoming byte counter.

func (*ConnCounters) AddOut

func (c *ConnCounters) AddOut(n int)

AddOut adds to the outgoing byte counter.

func (*ConnCounters) Snapshot

func (c *ConnCounters) Snapshot() (in, out int64)

Snapshot returns the current values of the incoming and outgoing byte counters.

type ContextKey

type ContextKey string

ContextKey is an unexported type for context keys in this package, preventing collisions with keys defined in other packages.

const TokenContextKey ContextKey = "token"

type DockerUsage

type DockerUsage struct {
	SocketPath            string `json:"socketPath"`            // path to dockerd socket
	APIVersion            string `json:"apiVersion"`            // dockerd API version
	DockerRootDir         string `json:"dockerRootDir"`         // Docker root directory (DockerRootDir)
	ImagesBytes           uint64 `json:"imagesBytes"`           // total size of all images
	ContainersBytes       uint64 `json:"containersBytes"`       // writable layer only (SizeRw)
	ContainersRootFsBytes uint64 `json:"containersRootFsBytes"` // includes image + writable (SizeRootFs)
	VolumesBytes          uint64 `json:"volumesBytes"`          // total size of all volumes
	BuildCacheBytes       uint64 `json:"buildCacheBytes"`       // total size of build cache
	TotalBytes            uint64 `json:"totalBytes"`            // images + containers(writable) + volumes + build cache
	DeclaredSize          uint64 `json:"declaredSize"`          // size declared for Docker from the blueprint
}

type IdentityInfo

type IdentityInfo struct {
	Username     string   `json:"username"`
	Name         string   `json:"name,omitempty"`
	Email        string   `json:"email,omitempty"`
	UID          uint32   `json:"uid"`
	GID          uint32   `json:"gid"`
	Shell        string   `json:"shell,omitempty"`
	Sudo         bool     `json:"sudo"`
	Roles        []string `json:"roles,omitempty"`
	Organization string   `json:"organization,omitempty"`
	Source       string   `json:"source,omitempty"`
	ExpiresAt    string   `json:"expiresAt"`
}

IdentityInfo contains the human-readable JWT identity claims for the workspace user.

type K8shelld

type K8shelld struct {
	// contains filtered or unexported fields
}

K8shelld is a client for the k8shelld gRPC service.

func NewClient

func NewClient(
	cfg gapi.ClientConfig,
	counters *ConnCounters,
	connectionID string,
	sessionClient *session.Client,
) (*K8shelld, error)

NewClient constructs a K8shelld client using the provided gRPC config. All sub-service clients are initialised on the shared connection. Pass a non-nil sessionClient to enable session recording.

func (*K8shelld) AcquireSession

func (c *K8shelld) AcquireSession(ctx context.Context, sessionId string) (*k8shelldv1.AcquireSessionResponse, error)

AcquireSession attempts to acquire an existing shell session for attachment

func (*K8shelld) Close

func (c *K8shelld) Close() error

Close closes the underlying gRPC connection and releases associated resources.

func (*K8shelld) GetAppLogs

func (wc *K8shelld) GetAppLogs(ctx context.Context, appName string) (string, error)

GetAppLogs returns the full log output for the named application as a single string.

func (*K8shelld) GetAppLogsStream

func (wc *K8shelld) GetAppLogsStream(ctx context.Context, appName string) (io.ReadCloser, error)

GetAppLogsStream retrieves a stream of logs for the specified application from the k8shelld service and returns it as an io.ReadCloser. The caller is responsible for closing the stream when done.

func (*K8shelld) GetCWD

func (c *K8shelld) GetCWD(ctx context.Context, shellId string) (string, error)

GetCWD retrieves the current working directory for a shell session.

func (*K8shelld) GetSystemInfo

func (c *K8shelld) GetSystemInfo(ctx context.Context) (*SystemInfo, error)

GetSystemInfo returns system-level information from the k8shelld agent.

func (*K8shelld) Handshake

func (c *K8shelld) Handshake(ctx context.Context, userToken string) (*k8shelldv1.HandshakeResponse, error)

Handshake performs a handshake with the k8shelld service to establish a session. The caller's identity JWT (user.UserToken) is sent so the server can verify it matches the workspace identity token.

func (*K8shelld) InstallApp

func (wc *K8shelld) InstallApp(ctx context.Context, appName string) error

InstallApp installs the named application on the remote k8shelld agent.

func (*K8shelld) ListApps

func (wc *K8shelld) ListApps(ctx context.Context) ([]*AppStatus, error)

ListApps returns all applications known to the k8shelld agent.

func (*K8shelld) ResizeTerminal

func (c *K8shelld) ResizeTerminal(ctx context.Context, sessionId string, width, height uint32) error

ResizeTerminal sends a terminal resize event to the running shell session and, if session recording is active, records the resize with the correct time offset.

func (*K8shelld) RunCommandProcessor

func (k *K8shelld) RunCommandProcessor(ctx context.Context, handler CommandHandler) error

RunCommandProcessor subscribes to the server-side command stream and dispatches each incoming command to handler, sending the reply back on the same stream. Blocks until ctx is cancelled, the stream closes, or a transport error occurs.

func (*K8shelld) RunExec

func (c *K8shelld) RunExec(
	ctx context.Context,
	userToken string,
	asUser string,
	upstream BufferedReadWriter,
	execID string,
	command string,
	shellBinary string,
	envVars []string,
	signalChan <-chan string,
	enableRecording bool,
) (int32, error)

RunExec runs command via the remote exec service, bridging stdin/stdout/stderr through upstream. signalChan may be used to forward OS signals (e.g. SIGINT) to the remote process. Returns the process exit code together with any transport error.

func (*K8shelld) RunPortForward

func (c *K8shelld) RunPortForward(
	ctx context.Context,
	userToken string,
	upstream BufferedReadWriter,
	portForwardID string,
	sourceIP string,
	sourcePort uint32,
	destinationIP string,
	destinationPort uint32,
	enableRecording bool,
) error

RunPortForward sets up a port forward over gRPC and bridges it with the upstream channel.

func (*K8shelld) RunSFTP

func (c *K8shelld) RunSFTP(
	ctx context.Context,
	userToken string,
	asUser string,
	upstream BufferedReadWriter,
	sessionID string,
	command string,
	envVars []string,
	enableRecording bool,
) (int32, error)

RunSFTP runs an SFTP subsystem session over gRPC, bridging the channel through upstream. SFTP is executed as a server-side binary (sftp-server) via the exec endpoint, but recorded using the SFTP recording service (pcap format) with both traffic directions captured. Returns the process exit code and any transport error.

func (*K8shelld) RunShell

func (c *K8shelld) RunShell(
	ctx context.Context,
	userToken string,
	asUser string,
	rw BufferedReadWriter,
	sessionId string,
	envVars []string,
	width, height uint32,
	usePty bool,
	lockId string,
	detachOnClose bool,
	showInitScriptStatus bool,
	enableRecording bool,
	notifyPtyName NotifyPtyNameFunc,
) error

RunShell creates a PTY shell session over gRPC and bridges it with the BufferedReadWriter. onStart is called once the server sends the ShellStartResponse; it receives the PTY device name (e.g. "/dev/pts/3") or an empty string when no PTY was allocated. onStart may be nil.

func (*K8shelld) RunUnixSocket

func (c *K8shelld) RunUnixSocket(
	ctx context.Context,
	userToken string,
	upstream BufferedReadWriter,
	unixSocketId string,
	socketPath string,
	mode string,
) error

RunUnixSocket creates a Unix socket connection over gRPC and bridges it with the RW channel.

func (*K8shelld) StartApp

func (wc *K8shelld) StartApp(ctx context.Context, appName string) error

StartApp starts the named application on the remote k8shelld agent.

func (*K8shelld) StopApp

func (wc *K8shelld) StopApp(ctx context.Context, appName string) error

StopApp stops the named application on the remote k8shelld agent.

type MountUsage

type MountUsage struct {
	MountPoint     string   `json:"mountPoint"`             // path where mounted
	Source         string   `json:"source"`                 // device or source of the mount
	FSType         string   `json:"fsType"`                 // filesystem type (e.g., ext4, tmpfs)
	Options        []string `json:"options"`                // mount options (e.g., ro, rw)
	ReadOnly       bool     `json:"readOnly"`               // is the mount read-only
	IsLikelyTemp   bool     `json:"isLikelyTemp,omitempty"` // overlay/tmpfs/etc.
	TotalBytes     uint64   `json:"totalBytes"`             // total size of the filesystem
	UsedBytes      uint64   `json:"usedBytes"`              // used bytes on the filesystem
	FreeBytes      uint64   `json:"freeBytes"`              // free bytes on the filesystem
	AvailableBytes uint64   `json:"availableBytes"`         // available bytes to non-root users
	TotalInodes    uint64   `json:"totalInodes"`            // total inodes on the filesystem
	FreeInodes     uint64   `json:"freeInodes"`             // free inodes on the filesystem
	DeclaredSize   uint64   `json:"declaredSize"`           // size declared for this mount from the blueprint
}

MountUsage represents the usage statistics for a mounted filesystem

type NotifyPtyNameFunc

type NotifyPtyNameFunc func(ptyName string)

type ReapZombies

type ReapZombies struct {
	Enabled bool `yaml:"enabled"`
}

ReapZombies represents the configuration for the reap-zombies feature.

type Recorder

type Recorder struct {
	// contains filtered or unexported fields
}

Recorder owns a single gRPC client-streaming session to the recording service. All exported methods are safe to call from multiple goroutines. A nil Recorder is safe to use — all methods are no-ops.

func NewExecRecorder

func NewExecRecorder(
	ctx context.Context,
	client sessionv1.RecordingServiceClient,
	sessionID, connectionID, userToken, command string,
	startedAt time.Time,
	log *zerolog.Logger,
) *Recorder

NewExecRecorder opens an exec-channel streaming session to the recording service and starts a background sender goroutine. The ExecRecordingHeader is sent as the first frame. Returns nil when client is nil.

func NewSftpRecorder

func NewSftpRecorder(
	ctx context.Context,
	client sessionv1.RecordingServiceClient,
	sessionID, connectionID, userToken string,
	startedAt time.Time,
	log *zerolog.Logger,
) *Recorder

NewSftpRecorder opens an SFTP-channel streaming session to the recording service and starts a background sender goroutine. The SftpRecordingHeader is sent as the first frame. Returns nil when client is nil.

func NewShellRecorder

func NewShellRecorder(
	ctx context.Context,
	client sessionv1.RecordingServiceClient,
	sessionID, connectionID, userToken string,
	width, height uint32,
	startedAt time.Time,
	log *zerolog.Logger,
) *Recorder

NewShellRecorder opens a shell-channel streaming session to the recording service and starts a background sender goroutine. The ShellRecordingHeader is sent as the first frame. Returns nil when client is nil (recording disabled), which all methods treat as a no-op.

func NewTcpipRecorder

func NewTcpipRecorder(
	ctx context.Context,
	client sessionv1.RecordingServiceClient,
	sessionID, connectionID, userToken string,
	srcHost string, srcPort uint32,
	dstHost string, dstPort uint32,
	startedAt time.Time,
	log *zerolog.Logger,
) *Recorder

NewTcpipRecorder opens a TCP/IP-channel streaming session to the recording service and starts a background sender goroutine. The TcpipRecordingHeader is sent as the first frame. Returns nil when client is nil.

func (*Recorder) Close

func (r *Recorder) Close()

Close signals the sender goroutine to drain any buffered frames and close the gRPC stream. Blocks until the stream is fully closed.

func (*Recorder) Observe

func (r *Recorder) Observe(data []byte, offset time.Duration)

Observe enqueues an output (service→client) frame. Non-blocking; frames are dropped if the internal channel is full to protect the SSH session goroutine.

func (*Recorder) ObserveInput

func (r *Recorder) ObserveInput(data []byte, offset time.Duration)

ObserveInput enqueues an input (client→service) frame. Non-blocking.

func (*Recorder) ObserveResize

func (r *Recorder) ObserveResize(width, height uint32, offset time.Duration)

ObserveResize enqueues a terminal resize frame. Non-blocking.

type RecordingAdapter

type RecordingAdapter struct {
	BufferedReadWriter
	// contains filtered or unexported fields
}

RecordingAdapter wraps a BufferedReadWriter and intercepts Write (and optionally Read) calls to forward bytes to recording observer functions. Both observers are called synchronously but must be non-blocking.

func NewBidirectionalRecordingAdapter

func NewBidirectionalRecordingAdapter(
	rw BufferedReadWriter,
	start time.Time,
	observeWrite func([]byte, time.Duration),
	observeRead func([]byte, time.Duration),
) *RecordingAdapter

NewBidirectionalRecordingAdapter wraps rw, forwarding written bytes to observeWrite and read bytes to observeRead, capturing both traffic directions.

func NewRecordingAdapter

func NewRecordingAdapter(rw BufferedReadWriter, start time.Time, observe func([]byte, time.Duration)) *RecordingAdapter

NewRecordingAdapter wraps rw, forwarding written bytes to observe. start is the wall-clock session start time used to compute offsets.

func (*RecordingAdapter) Read

func (a *RecordingAdapter) Read(p []byte) (int, error)

Read intercepts input (client→service) bytes after reading from the underlying reader.

func (*RecordingAdapter) Stderr

func (a *RecordingAdapter) Stderr() io.Writer

Stderr returns a writer that also intercepts output through the write observer.

func (*RecordingAdapter) Write

func (a *RecordingAdapter) Write(p []byte) (int, error)

Write intercepts output (service→client) bytes before forwarding to the underlying writer.

type SaToken

type SaToken struct {
	// Enabled controls whether the SA token credential helper is active.
	Enabled bool `yaml:"enabled"`
	// CacheTokens controls whether retrieved tokens are cached to avoid redundant API server calls.
	CacheTokens bool `yaml:"cacheTokens"`
}

SaToken holds configuration for the Kubernetes credential helper that retrieves service account tokens via the API server for Kubernetes API access.

type Shells

type Shells struct {
	// DetachedTTL controls how long a PTY shell session with no attached
	// client is kept alive before the GC terminates it.
	// Accepts Go duration strings (e.g. "30m", "1h").
	// When empty the server falls back to its built-in default (30m).
	// Set to "0s" to disable automatic termination entirely.
	DetachedTTL string `yaml:"detachedTTL,omitempty"`

	// AllowUnlimittedTTL controls whether clients are allowed to set an unlimitted TTL for detached sessions.
	AllowUnlimittedTTL bool `yaml:"allowUnlimittedTTL"`

	// AllowSessionDetach controls whether clients are allowed to detach from PTY shell sessions.
	AllowSessionDetach bool `yaml:"allowSessionDetach"`
}

Shells holds shell session configuration.

type SplashInfo

type SplashInfo struct {
	Text string `json:"text"`
}

SplashInfo contains the rendered splash message text.

type System

type System struct {
	PProf      bool              `yaml:"pprof"`
	LogLevel   string            `yaml:"logLevel,omitempty"`
	ApiServer  ApiServer         `yaml:"apiServer"`
	GrpcConfig gapi.ServerConfig `yaml:"grpc"`
}

System represents the general system configuration.

type SystemInfo

type SystemInfo struct {
	Time       string       `json:"time"`                 // current system time
	System     *SystemUsage `json:"system"`               // system usage metrics
	Mounts     []MountUsage `json:"mounts"`               // list of mount usage statistics
	Docker     *DockerUsage `json:"docker,omitempty"`     // docker usage statistics
	Repository string       `json:"repository,omitempty"` // full repo URL, e.g. https://github.com/owner/repo
}

SystemInfo represents the overall system information

func ProtoToSystemInfo

func ProtoToSystemInfo(pb *k8shelldv1.SystemInfoResponse) *SystemInfo

type SystemUsage

type SystemUsage struct {
	Uptime             string  `json:"uptime"`             // time since last start
	CPUUsageMillicores float64 `json:"cpuUsageMillicores"` // CPU usage in millicores
	CPULimitMillicores float64 `json:"cpuLimitMillicores"` // CPU limit in millicores (from kube resource limits)
	MemoryUsageMiB     float64 `json:"memoryUsageMiB"`     // memory usage in MiB
	MemLimitMiB        float64 `json:"memLimitMiB"`        // memory limit in MiB (from kube resource limits)
	CPUAvg1Min         float64 `json:"cpuAvg1min"`         // load average over 1 minute
	CPUAvg5Min         float64 `json:"cpuAvg5min"`         // load average over 5 minutes
	CPUAvg15Min        float64 `json:"cpuAvg15min"`        // load average over 15 minutes
	Users              uint32  `json:"users"`              // number of logged-in users
}

SystemInfoMetrics represents the system info metrics

type TerminateOrphans

type TerminateOrphans struct {
	Enabled       bool     `yaml:"enabled"`
	CheckInterval int      `yaml:"checkInterval"`
	Exclude       []string `yaml:"exclude,omitempty"`
}

TerminateOrphans represents the configuration for the terminate-orphans feature.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL