Documentation
¶
Index ¶
- func AppStatusToProto(u *AppStatus) *k8shelldv1.AppStatus
- func LogLevelFromProto(level k8shelldv1.LogLevel) string
- func LogLevelToProto(level string) k8shelldv1.LogLevel
- func LogTypeFromProto(logType k8shelldv1.LogType) string
- func LogTypeToProto(logType string) k8shelldv1.LogType
- func SystemInfoToProto(si *SystemInfo) *k8shelldv1.SystemInfoResponse
- type ApiServer
- type AppRuntimeStatus
- type AppStatus
- type BufferedReadWriter
- type Config
- type ConnCounters
- type DockerUsage
- type IdentityInfo
- type K8shelld
- func (c *K8shelld) AcquireSession(ctx context.Context, sessionId string) (*k8shelldv1.AcquireSessionResponse, error)
- func (c *K8shelld) Close() error
- func (wc *K8shelld) GetAppLogs(ctx context.Context, appName string) (string, error)
- func (wc *K8shelld) GetAppLogsStream(ctx context.Context, appName string) (io.ReadCloser, error)
- func (c *K8shelld) GetCWD(ctx context.Context, shellId string) (string, error)
- func (c *K8shelld) GetSystemInfo(ctx context.Context) (*SystemInfo, error)
- func (c *K8shelld) Handshake(ctx context.Context) (*k8shelldv1.HandshakeResponse, error)
- func (wc *K8shelld) InstallApp(ctx context.Context, appName string) error
- func (wc *K8shelld) ListApps(ctx context.Context) ([]*AppStatus, error)
- func (c *K8shelld) ListSessions(ctx context.Context) (*k8shelldv1.ListSessionsResponse, error)
- func (c *K8shelld) ResizeTerminal(ctx context.Context, sessionId string, width, height uint32) error
- func (c *K8shelld) RunExec(ctx context.Context, userToken string, asUser string, ...) (int32, error)
- func (c *K8shelld) RunPortForward(ctx context.Context, userToken string, upstream BufferedReadWriter, ...) error
- func (c *K8shelld) RunSFTP(ctx context.Context, userToken string, asUser string, ...) (int32, error)
- func (c *K8shelld) RunShell(ctx context.Context, userToken string, asUser string, rw BufferedReadWriter, ...) error
- func (c *K8shelld) RunUnixSocket(ctx context.Context, upstream BufferedReadWriter, unixSocketId string, ...) error
- func (wc *K8shelld) StartApp(ctx context.Context, appName string) error
- func (wc *K8shelld) StopApp(ctx context.Context, appName string) error
- func (c *K8shelld) StreamSystemLogs(ctx context.Context, opts StreamSystemLogsOptions, ...) error
- type LogStreamEntry
- type MountUsage
- type NotifyPtyNameFunc
- type ReapZombies
- type Recorder
- func NewExecRecorder(ctx context.Context, client sessionv1.RecordingServiceClient, ...) *Recorder
- func NewSftpRecorder(ctx context.Context, client sessionv1.RecordingServiceClient, ...) *Recorder
- func NewShellRecorder(ctx context.Context, client sessionv1.RecordingServiceClient, ...) *Recorder
- func NewTcpipRecorder(ctx context.Context, client sessionv1.RecordingServiceClient, ...) *Recorder
- type RecordingAdapter
- type SaToken
- type Shells
- type SplashInfo
- type StreamSystemLogsOptions
- type System
- type SystemInfo
- type SystemUsage
- type TerminateOrphans
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppStatusToProto ¶
func AppStatusToProto(u *AppStatus) *k8shelldv1.AppStatus
func LogLevelFromProto ¶ added in v0.44.0
func LogLevelFromProto(level k8shelldv1.LogLevel) string
LogLevelFromProto converts a proto LogLevel to the daemon's log level string. LOG_LEVEL_UNSPECIFIED (and any unrecognized value) maps to "" (no filter).
func LogLevelToProto ¶ added in v0.44.0
func LogLevelToProto(level string) k8shelldv1.LogLevel
LogLevelToProto converts a daemon log level string ("debug", "info", "warn", "error", "fatal") to its proto enum value. An empty or unrecognized level maps to LOG_LEVEL_UNSPECIFIED (no filter).
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 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 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 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 ¶
Close closes the underlying gRPC connection and releases associated resources.
func (*K8shelld) GetAppLogs ¶
GetAppLogs returns the full log output for the named application as a single string.
func (*K8shelld) GetAppLogsStream ¶
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) 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) (*k8shelldv1.HandshakeResponse, error)
Handshake performs a handshake with the k8shelld service to establish a session.
func (*K8shelld) InstallApp ¶
InstallApp installs the named application on the remote k8shelld agent.
func (*K8shelld) ListSessions ¶ added in v0.44.0
func (c *K8shelld) ListSessions(ctx context.Context) (*k8shelldv1.ListSessionsResponse, error)
ListSessions lists shell sessions on the pod that are currently available to be acquired for attachment (see AcquireSession).
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) 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, 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) StreamSystemLogs ¶ added in v0.44.0
func (c *K8shelld) StreamSystemLogs(ctx context.Context, opts StreamSystemLogsOptions, onEntry func(LogStreamEntry) error) error
StreamSystemLogs streams k8shelld daemon logs (the same logs shown by `kbox logs`), invoking onEntry once per log entry. With Follow=false it returns after the currently buffered entries are delivered; with Follow=true it blocks, delivering new entries as they are produced, until the stream ends or ctx is canceled.
type LogStreamEntry ¶ added in v0.44.0
LogStreamEntry is a single k8shelld daemon log entry received via StreamSystemLogs.
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 ¶
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 ¶
ObserveInput enqueues an input (client→service) 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.
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 StreamSystemLogsOptions ¶ added in v0.44.0
type StreamSystemLogsOptions struct {
Component string // filter by component (empty = all)
Level string // filter by level (empty = all)
Follow bool // keep streaming new entries as they arrive
LastN int32 // start from the last N buffered entries (0 = from the start of the buffer)
}
StreamSystemLogsOptions configures a StreamSystemLogs call.
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.