client

package
v0.6.6 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2024 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrMissingIDMappings gets returned if user namespace unsharing is selected
	// but no IDMappings being provided.
	ErrMissingIDMappings = errors.New("unsharing user namespace selected but no IDMappings provided")

	// ErrUnsupported gets returned if the server does not the feature.
	ErrUnsupported = errors.New("feature not supported by this conmon-rs version")
)

Functions

func DialLongSocket 

func DialLongSocket(network, path string) (*net.UnixConn, error)

DialLongSocket is a wrapper around net.DialUnix. Its purpose is to allow for an arbitrarily long socket. It does so by opening the parent directory of path, and using the `/proc/self/fd` entry of that parent (which is a symlink to the actual parent) to construct the path to the socket. It assumes a valid path, as well as a file name that doesn't exceed the unix max socket length.

Types

type AttachConfig 

type AttachConfig struct {
	// ID of the container.
	ID string

	// Path of the attach socket.
	SocketPath string

	// ExecSession ID, if this is an attach for an Exec.
	ExecSession string

	// Whether a terminal was setup for the command this is attaching to.
	Tty bool

	// Whether stdout/stderr should continue to be processed after stdin is closed.
	StopAfterStdinEOF bool

	// Whether the container supports stdin or not.
	ContainerStdin bool

	// Whether the output is passed through the caller's std streams, rather than
	// ones created for the attach session.
	Passthrough bool

	// Channel of resize events.
	Resize <-chan resize.TerminalSize

	// The standard streams for this attach session.
	Streams AttachStreams

	// A closure to be run before the streams are attached.
	// This could be used to start a container.
	PreAttachFunc func() error

	// A closure to be run after the streams are attached.
	// This could be used to notify callers the streams have been attached.
	PostAttachFunc func() error

	// The keys that indicate the attach session should be detached.
	DetachKeys []byte
}

AttachConfig is the configuration for running the Attach method.

type AttachStreams 

type AttachStreams struct {
	// Standard input stream, can be nil.
	Stdin *In

	// Standard output stream, can be nil.
	Stdout *Out

	// Standard error stream, can be nil.
	Stderr *Out
}

AttachStreams are the stdio streams for the AttachConfig.

type CgroupManager 

type CgroupManager proto.Conmon_CgroupManager

CgroupManager is the enum for all available cgroup managers. 

const (
	// CgroupManagerSystemd specifies to use systemd to create and manage
	// cgroups.
	CgroupManagerSystemd CgroupManager = CgroupManager(proto.Conmon_CgroupManager_systemd)

	// CgroupManagerCgroupfs specifies to use the cgroup filesystem to create
	// and manage cgroups.
	CgroupManagerCgroupfs CgroupManager = CgroupManager(proto.Conmon_CgroupManager_cgroupfs)

	// CgroupManagerPerCommand opts-in to the new CgroupManager option specified at the command level.
	//
	// Set `ConmonServerConfig.CgroupManager` to `CgroupManagerPerCommand` to use
	// the CgroupManager specified in the command config (e.g. CreateContainerConfig).
	CgroupManagerPerCommand CgroupManager = CgroupManager(0xffff)
)

type ConmonClient 

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

ConmonClient is the main client structure of this package.

func New 

func New(config *ConmonServerConfig) (client *ConmonClient, retErr error)

New creates a new conmon server, starts it and connects a new client to it.

If a server is already started with the same `ServerRunDir` specified the client connects to the existing server instead. Note: Other options from the `ConmonServerConfig` will be ignored and the settings of the existing server will remain unchanged.

func (*ConmonClient) AttachContainer 

func (c *ConmonClient) AttachContainer(ctx context.Context, cfg *AttachConfig) error

AttachContainer can be used to attach to a running container.

func (*ConmonClient) CreateContainer 

func (c *ConmonClient) CreateContainer(
	ctx context.Context, cfg *CreateContainerConfig,
) (*CreateContainerResponse, error)

CreateContainer can be used to create a new running container instance.

func (*ConmonClient) CreateNamespaces added in v0.5.0 

func (c *ConmonClient) CreateNamespaces(
	ctx context.Context, cfg *CreateNamespacesConfig,
) (*CreateNamespacesResponse, error)

CreateNamespaces can be used to create a new set of unshared namespaces by bind mounting it to the local filesystem.

If a namespace is not selected by the CreateNamespacesConfig, then the server will fallback to the host namespace and still create the bind mount to it. All namespaces are mounted to /var/run/[ipc,pid,net,user,uts]ns/$POD_ID, whereas the POD_ID is being used from the CreateNamespacesConfig as well.

UID and GID mappings are required if unsharing of the user namespace is requested.

func (*ConmonClient) ExecSyncContainer 

func (c *ConmonClient) ExecSyncContainer(ctx context.Context, cfg *ExecSyncConfig) (*ExecContainerResult, error)

ExecSyncContainer can be used to execute a command within a running container.

func (*ConmonClient) PID 

func (c *ConmonClient) PID() uint32

PID returns the server process ID.

func (*ConmonClient) RemoteFDs added in v0.6.0 

func (c *ConmonClient) RemoteFDs(ctx context.Context) (*RemoteFDs, error)

RemoteFDs can be used start and connect to the remote fd socket.

func (*ConmonClient) ReopenLogContainer 

func (c *ConmonClient) ReopenLogContainer(ctx context.Context, cfg *ReopenLogContainerConfig) error

ReopenLogContainer can be used to rotate all configured container log drivers.

func (*ConmonClient) SetWindowSizeContainer 

func (c *ConmonClient) SetWindowSizeContainer(ctx context.Context, cfg *SetWindowSizeContainerConfig) error

SetWindowSizeContainer can be used to change the window size of a running container.

func (*ConmonClient) Shutdown 

func (c *ConmonClient) Shutdown() error

Shutdown kill the server via SIGINT. Waits up to 10 seconds for the server PID to be removed from the system.

func (*ConmonClient) Version 

func (c *ConmonClient) Version(
	ctx context.Context, cfg *VersionConfig,
) (*VersionResponse, error)

Version can be used to retrieve all available version information.

type ConmonServerConfig 

type ConmonServerConfig struct {
	// ClientLogger can be set to use a custom logger rather than the
	// logrus.StandardLogger.
	ClientLogger *logrus.Logger

	// ConmonServerPath is the binary path to the conmon server.
	ConmonServerPath string

	// LogLevel of the server to be used.
	// Can be "trace", "debug", "info", "warn", "error" or "off".
	LogLevel LogLevel

	// LogDriver is the possible server logging driver.
	// Can be "stdout" or "systemd".
	LogDriver LogDriver

	// Runtime is the binary path of the OCI runtime to use to operate on the
	// containers.
	Runtime string

	// RuntimeRoot is the root directory used by the OCI runtime to operate on
	// containers.
	RuntimeRoot string

	// ServerRunDir is the path of the directory for the server to hold files
	// at runtime.
	ServerRunDir string

	// Stdout is the standard output stream of the server when the log driver
	// "stdout" is being used (can be nil).
	Stdout io.WriteCloser

	// Stderr is the standard error stream of the server when the log driver
	// "stdout" is being used (can be nil).
	Stderr io.WriteCloser

	// CgroupManager can be use to select the cgroup manager.
	CgroupManager CgroupManager

	// Tracing can be used to enable OpenTelemetry tracing.
	Tracing *Tracing
}

ConmonServerConfig is the configuration for the conmon server instance.

func NewConmonServerConfig 

func NewConmonServerConfig(
	runtime, runtimeRoot, serverRunDir string,
) *ConmonServerConfig

NewConmonServerConfig creates a new ConmonServerConfig instance for the required arguments. Optional arguments are pointing to their corresponding default values.

type ContainerLogDriver added in v0.4.0 

type ContainerLogDriver struct {
	// Type defines the log driver variant.
	Type LogDriverType

	// Path specifies the filesystem path of the log driver.
	Path string

	// MaxSize is the maximum amount of bytes to be written before rotation.
	// 0 translates to an unlimited size.
	MaxSize uint64
}

ContainerLogDriver specifies a selected logging mechanism.

type CreateContainerConfig 

type CreateContainerConfig struct {
	// ID is the container identifier.
	ID string

	// BundlePath is the path to the filesystem bundle.
	BundlePath string

	// Terminal indicates if a tty should be used or not.
	Terminal bool

	// Stdin indicates if stdin should be available or not.
	Stdin bool

	// ExitPaths is a slice of paths to write the exit statuses.
	ExitPaths []string

	// OOMExitPaths is a slice of files that should be created if the given container is OOM killed.
	OOMExitPaths []string

	// LogDrivers is a slice of selected log drivers.
	LogDrivers []ContainerLogDriver

	// CleanupCmd is the command that will be executed once the container exits
	CleanupCmd []string

	// GlobalArgs are the additional arguments passed to the create runtime call
	// before the command. e.g: crun --runtime-arg create
	GlobalArgs []string

	// CommandArgs are the additional arguments passed to the create runtime call
	// after the command. e.g: crun create --runtime-opt
	CommandArgs []string

	// EnvVars are the environment variables passed to the create runtime call.
	EnvVars map[string]string

	// CgroupManager can be use to select the cgroup manager.
	//
	// To use this option set `ConmonServerConfig.CgroupManager` to `CgroupManagerPerCommand`.
	CgroupManager CgroupManager

	// AdditionalFDs can be used to pass additional file descriptors to the container.
	AdditionalFDs []RemoteFD

	// LeakFDs can be used to keep file descriptors open as long as the container is running.
	LeakFDs []RemoteFD
}

CreateContainerConfig is the configuration for calling the CreateContainer method.

type CreateContainerResponse 

type CreateContainerResponse struct {
	// PID is the container process identifier.
	PID uint32

	// NamespacesPath is the base path where the namespaces are mounted.
	NamespacesPath string
}

CreateContainerResponse is the response of the CreateContainer method.

type CreateNamespacesConfig added in v0.6.0 

type CreateNamespacesConfig struct {
	// Namespaces are the list of namespaces to unshare.
	Namespaces []Namespace

	// IDMappings are the user and group ID mappings when unsharing the user
	// namespace.
	IDMappings *idtools.IDMappings

	// BasePath is the root path for storing the namespaces.
	// Defaults to "/var/run" if unset.
	BasePath string

	// PodID is the unique identifier of the pod.
	PodID string
}

CreateNamespacesConfig is the configuration for calling the CreateNamespaces method.

type CreateNamespacesResponse added in v0.6.0 

type CreateNamespacesResponse struct {
	Namespaces []*NamespacesResponse
}

CreateNamespacesResponse is the response of the CreateNamespaces method.

type ExecContainerResult 

type ExecContainerResult struct {
	// ExitCode specifies the returned exit status.
	ExitCode int32

	// Stdout contains the stdout stream result.
	Stdout []byte

	// Stderr contains the stderr stream result.
	Stderr []byte

	// TimedOut is true if the command timed out.
	TimedOut bool
}

ExecContainerResult is the result for calling the ExecSyncContainer method.

type ExecSyncConfig 

type ExecSyncConfig struct {
	// ID is the container identifier.
	ID string

	// Command is a slice of command line arguments.
	Command []string

	// Timeout is the maximum time the command can run in seconds.
	Timeout uint64

	// Terminal specifies if a tty should be used.
	Terminal bool

	// EnvVars are the environment variables passed to the exec runtime call.
	EnvVars map[string]string

	// CgroupManager can be use to select the cgroup manager.
	//
	// To use this option set `ConmonServerConfig.CgroupManager` to `CgroupManagerPerCommand`.
	CgroupManager CgroupManager
}

ExecSyncConfig is the configuration for calling the ExecSyncContainer method.

type In 

type In struct {
	// Wraps an io.ReadCloser
	io.ReadCloser
}

In defines an input stream.

type LogDriver 

type LogDriver string

LogDriver is the enum for all available server log drivers. 

const (
	// LogDriverStdout is the log driver printing to stdio.
	LogDriverStdout LogDriver = "stdout"

	// LogDriverSystemd is the log driver printing to systemd journald.
	LogDriverSystemd LogDriver = "systemd"
)

type LogDriverType 

type LogDriverType int

LogDriverType specifies available log drivers. 

const (
	// LogDriverTypeContainerRuntimeInterface is the Kubernetes CRI logger
	// type.
	LogDriverTypeContainerRuntimeInterface LogDriverType = iota
	LogDriverTypeJSONLogger                LogDriverType = iota
)

type LogLevel added in v0.4.0 

type LogLevel string

LogLevel is the enum for all available server log levels. 

const (
	// LogLevelTrace is the log level printing only "trace" messages.
	LogLevelTrace LogLevel = "trace"

	// LogLevelDebug is the log level printing only "debug" messages.
	LogLevelDebug LogLevel = "debug"

	// LogLevelInfo is the log level printing only "info" messages.
	LogLevelInfo LogLevel = "info"

	// LogLevelWarn is the log level printing only "warn" messages.
	LogLevelWarn LogLevel = "warn"

	// LogLevelError is the log level printing only "error" messages.
	LogLevelError LogLevel = "error"

	// LogLevelOff is the log level printing no messages.
	LogLevelOff LogLevel = "off"
)

func FromLogrusLevel 

func FromLogrusLevel(level logrus.Level) LogLevel

FromLogrusLevel converts the logrus.Level to a conmon-rs server log level.

type Namespace added in v0.5.0 

type Namespace int

Namespace is the enum for all available namespaces. 

const (
	// NamespaceIPC is the reference to the IPC namespace.
	NamespaceIPC Namespace = iota

	// NamespacePID is the reference to the PID namespace.
	NamespacePID

	// NamespaceNet is the reference to the network namespace.
	NamespaceNet

	// NamespaceUser is the reference to the user namespace.
	NamespaceUser

	// NamespaceUTS is the reference to the UTS namespace.
	NamespaceUTS
)

type NamespacesResponse added in v0.5.0 

type NamespacesResponse struct {
	// Namespace is the type of namespace.
	Type Namespace

	// Path is the base path to the namespaces directory.
	Path string
}

NamespacesResponse is the response data for the CreateNamespacesResponse.

type Out 

type Out struct {
	// Wraps an io.WriteCloser
	io.WriteCloser
}

Out defines an output stream.

type RemoteFD added in v0.6.0 

type RemoteFD uint64

RemoteFD represents a file descriptor on the server, identified by a slot number.

func (RemoteFD) String added in v0.6.0 

func (r RemoteFD) String() string

type RemoteFDs added in v0.6.0 

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

RemoteFDs can be used to send file descriptors to the server.

func NewRemoteFDs added in v0.6.0 

func NewRemoteFDs(path string) (*RemoteFDs, error)

NewRemoteFDs connects to the fd socket at `path`.

func (*RemoteFDs) Close added in v0.6.0 

func (r *RemoteFDs) Close() error

Close the connection and unused remote file descriptors.

func (*RemoteFDs) Send added in v0.6.0 

func (r *RemoteFDs) Send(fds ...int) ([]RemoteFD, error)

Send file descriptors to the server.

type ReopenLogContainerConfig 

type ReopenLogContainerConfig struct {
	// ID is the container identifier.
	ID string
}

ReopenLogContainerConfig is the configuration for calling the ReopenLogContainer method.

type RequestWithMetadata added in v0.6.0 

type RequestWithMetadata interface {
	NewMetadata(n int32) (proto.Conmon_TextTextMapEntry_List, error)
}

type RequestWithMetadataOld added in v0.6.0 

type RequestWithMetadataOld interface {
	RequestWithMetadata
	SetMetadataOld(v []byte) error
}

type SetWindowSizeContainerConfig 

type SetWindowSizeContainerConfig struct {
	// ID specifies the container ID.
	ID string

	// Size is the new terminal size.
	Size *resize.TerminalSize
}

SetWindowSizeContainerConfig is the configuration for calling the SetWindowSizeContainer method.

type Tracing added in v0.4.0 

type Tracing struct {
	// Enabled tells the server to run with OpenTelemetry tracing.
	Enabled bool

	// Endpoint is the GRPC tracing endpoint for OLTP.
	// Defaults to "http://127.0.0.1:4317"
	Endpoint string

	// Tracer allows the client to create additional spans if set.
	Tracer trace.Tracer
}

Tracing is the structure for managing server-side OpenTelemetry tracing.

type VersionConfig added in v0.3.0 

type VersionConfig struct {
	// Verbose specifies verbose version output.
	Verbose bool
}

VersionConfig is the configuration for calling the Version method.

type VersionResponse 

type VersionResponse struct {
	// ProcessID is the PID of the server.
	ProcessID uint32

	// Version is the actual version string of the server.
	Version string

	// Tag is the git tag of the server, empty if no tag is available.
	Tag string

	// Commit is git commit SHA of the build.
	Commit string

	// BuildDate is the date of build.
	BuildDate string

	// Target is the build triple.
	Target string

	// RustVersion is the used Rust version.
	RustVersion string

	// CargoVersion is the used Cargo version.
	CargoVersion string

	// CargoTree is the used dependency tree.
	// Only set if request was in verbose mode.
	CargoTree string
}

VersionResponse is the response of the Version method.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.