kuberun

README

ContainerSSH Kubernetes Library

This library runs Kubernetes pods in integration with the sshserver library.

Note: This is a developer documentation.
The user documentation for ContainerSSH is located at containerssh.github.io.

How this library works

When a client successfully performs an SSH handshake this library creates a Pod in the specified Kubernetes cluster. This pod will run the command specified in IdleCommand. When the user opens a session channel this library runs an exec command against this container, allowing multiple parallel session channels to work on the same Pod.

Using this library

As this library is designed to be used exclusively with the sshserver library the API to use it is also very closely aligned. This backend doesn't implement a full SSH backend, instead it implements a network connection handler. This handler can be instantiated using the kuberun.New() method:

handler, err := kuberun.New(
    config,
    connectionID,
    client,
    logger,
)

The parameters are as follows:

• config is a struct of the kuberun.Config type.
• connectionID is an opaque ID for the connection.
• client is the net.TCPAddr of the client that connected.
• logger is the logger from the log library

Once the handler is created it will wait for a successful handshake:

sshConnection, err := handler.OnHandshakeSuccess("username-here")

This will launch a pod. Conversely, the handler.OnDisconnect() will destroy the pod.

The sshConnection can be used to create session channels and launch programs as described in the sshserver library.

Note: This library does not perform authentication. Instead, it will always sshserver.AuthResponseUnavailable.

Documentation

Index

• func CreateConnectionConfig(config Config) restclient.Config
• func New(client net.TCPAddr, connectionID string, config Config, logger log.Logger) (sshserver.NetworkConnectionHandler, error)
• func SetConfigFromKubeConfig(config *Config) (err error)
• type Config
• type ConnectionConfig
• type PodConfig
• type PushSizeQueue

Functions

func CreateConnectionConfig

func CreateConnectionConfig(config Config) restclient.Config

CreateConnectionConfig creates a Kubernetes REST client config from the kuberun config structure.

func New

func New(client net.TCPAddr, connectionID string, config Config, logger log.Logger) (sshserver.NetworkConnectionHandler, error)

func SetConfigFromKubeConfig

func SetConfigFromKubeConfig(config *Config) (err error)

SetConfigFromKubeConfig attempts to load the kubeconfig from the current users home directory and use it as a source for credentials. As ContainerSSH is intended to be run from an explicit config the use of this outside of test code is strongly discouraged and will not be supported.

Types

type Config

type Config struct {
	// Connection configures the connection to the Kubernetes cluster.
	Connection ConnectionConfig `json:"connection" yaml:"connection" comment:"Kubernetes configuration options"`
	// Pod contains the spec and specific settings for creating the pod.
	Pod PodConfig `json:"pod" yaml:"pod" comment:"Container configuration"`
	// Timeout specifies how long to wait for the Pod to come up.
	Timeout time.Duration `json:"timeout" yaml:"timeout" comment:"Timeout for pod creation" default:"60s"`
}

Config is the base configuration structure for kuberun

type ConnectionConfig

type ConnectionConfig struct {
	// Host is a host string, a host:port pair, or a URL to the Kubernetes apiserver. Defaults to kubernetes.default.svc.
	Host string `` /* 138-byte string literal not displayed */
	// APIPath is a sub-path that points to the API root. Defaults to /api
	APIPath string `json:"path" yaml:"path" comment:"APIPath is a sub-path that points to an API root." default:"/api"`

	// Username is the username for basic authentication.
	Username string `json:"username" yaml:"username" comment:"Username for basic authentication"`
	// Password is the password for basic authentication.
	Password string `json:"password" yaml:"password" comment:"Password for basic authentication"`

	// Insecure means that the server should be accessed without TLS verification. This is NOT recommended.
	Insecure bool `json:"insecure" yaml:"insecure" comment:"Server should be accessed without verifying the TLS certificate." default:"false"`
	// ServerName sets the server name to be set in the SNI and used by the client for TLS verification.
	ServerName string `` /* 152-byte string literal not displayed */

	// CertFile points to a file that contains the client certificate used for authentication.
	CertFile string `json:"certFile" yaml:"certFile" comment:"File containing client certificate for TLS client certificate authentication."`
	// KeyFile points to a file that contains the client key used for authentication.
	KeyFile string `json:"keyFile" yaml:"keyFile" comment:"File containing client key for TLS client certificate authentication"`
	// CAFile points to a file that contains the CA certificate for authentication.
	CAFile string `json:"cacertFile" yaml:"cacertFile" comment:"File containing trusted root certificates for the server"`

	// CertData contains a PEM-encoded certificate for TLS client certificate authentication.
	CertData string `json:"cert" yaml:"cert" comment:"PEM-encoded certificate for TLS client certificate authentication"`
	// KeyData contains a PEM-encoded client key for TLS client certificate authentication.
	KeyData string `json:"key" yaml:"key" comment:"PEM-encoded client key for TLS client certificate authentication"`
	// CAData contains a PEM-encoded trusted root certificates for the server.
	CAData string `json:"cacert" yaml:"cacert" comment:"PEM-encoded trusted root certificates for the server"`

	// BearerToken contains a bearer (service) token for authentication.
	BearerToken string `json:"bearerToken" yaml:"bearerToken" comment:"Bearer (service token) authentication"`
	// BearerTokenFile points to a file containing a bearer (service) token for authentication.
	// Set to /var/run/secrets/kubernetes.io/serviceaccount/token to use service token in a Kubernetes kubeConfigCluster.
	BearerTokenFile string `` /* 211-byte string literal not displayed */

	// QPS indicates the maximum QPS to the master from this client. Defaults to 5.
	QPS float32 `json:"qps" yaml:"qps" comment:"QPS indicates the maximum QPS to the master from this client." default:"5"`
	// Burst indicates the maximum burst for throttle.
	Burst int `json:"burst" yaml:"burst" comment:"Maximum burst for throttle." default:"10"`
	// Timeout indicates the timeout for client calls.
	Timeout time.Duration `json:"timeout" yaml:"timeout" comment:"Timeout"`
}

ConnectionConfig configures the connection to the Kubernetes cluster.

type PodConfig

type PodConfig struct {
	// Namespace is the namespace to run the pod in.
	Namespace string `json:"namespace" yaml:"namespace" comment:"Namespace to run the pod in" default:"default"`
	// ConsoleContainerNumber specifies the container to attach the running process to. Defaults to 0.
	ConsoleContainerNumber int `` /* 129-byte string literal not displayed */
	// Spec contains the pod specification to launch.
	Spec v1.PodSpec `` /* 169-byte string literal not displayed */
	// Subsystems contains a map of subsystem names and the executable to launch.
	Subsystems map[string]string `` /* 133-byte string literal not displayed */
	// ShellCommand is the command that runs when a shell is requested. This is intentionally left empty because populating it would mean a potential security issue.
	ShellCommand []string `json:"shellCommand" yaml:"shellCommand" comment:"Run this command when a new shell is requested." default:"[\"/bin/bash\"]"`
	// IdleCommand contains the command to run as the first process in the container. Other commands are executed using the "exec" method.
	IdleCommand []string `` /* 191-byte string literal not displayed */
}

PodConfig describes the pod to launch.

type PushSizeQueue

type PushSizeQueue interface {
	remotecommand.TerminalSizeQueue

	Push(remotecommand.TerminalSize)
}