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 GetLogsPageOptions
- 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) GetLogsPage(ctx context.Context, opts GetLogsPageOptions) (*LogPage, 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 LogPage
- 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 GetLogsPageOptions ¶ added in v0.45.0
type GetLogsPageOptions struct {
Component string // filter by component (empty = all)
Level string // filter by level (empty = all)
BeforeID int64 // return entries older than this id (0 = start from the most recent entry)
Limit int32 // max entries to return
}
GetLogsPageOptions configures a GetLogsPage call.
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) GetLogsPage ¶ added in v0.45.0
GetLogsPage returns one page of k8shelld daemon logs strictly older than opts.BeforeID, for "load more" / infinite-scroll style backward pagination independent of StreamSystemLogs's live tail. Pass the ID of the oldest entry currently held by the caller (from StreamSystemLogs's initial backlog, or from the previous GetLogsPage response) as opts.BeforeID to fetch the page before it.
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 LogPage ¶ added in v0.45.0
type LogPage struct {
Entries []LogStreamEntry // oldest matching entry first
HasMore bool // true if older entries remain in the buffer beyond this page
}
LogPage is one page of k8shelld daemon logs returned by GetLogsPage.
type LogStreamEntry ¶ added in v0.44.0
type LogStreamEntry struct {
ID int64 // Stable, monotonically increasing sequence id of this entry
Time string
Component string
Level string
Message string
}
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.