Split Runtime interface between Deployer and Runtime (#1060)

As we split apart the k8s proxy runner from the CLI/API code, we need to decouple the code in runner and transport from concerns which are not relevant to k8s.

As a first step, split the runtime interface in two: a Deployer interface which contains the subset of Runtime needed for the code in runner and transport, and leave the other methods in Runtime. Runtime is altered to extend from Deployer in order to minimize changes in the code, but in future we could decoupe them further to allow for implementations of Runtime if it makes sense to do so.

Author: dmjb

pkg/container/docker/client.go

@@ -41,7 +41,7 @@ const (
 	LabelValueTrue                 = "true"
 )
 
-// Client implements the Runtime interface for Docker (and compatible runtimes)
+// Client implements the Deployer interface for Docker (and compatible runtimes)
 type Client struct {
 	runtimeType  runtime.Type
 	socketPath   string

pkg/container/kubernetes/client.go

@@ -42,7 +42,7 @@ const (
 	mcpContainerName = "mcp"
 )
 
-// Client implements the Runtime interface for container operations
+// Client implements the Deployer interface for container operations
 type Client struct {
 	runtimeType runtime.Type
 	client      kubernetes.Interface

pkg/container/runtime/mocks/mock_runtime.go

@@ -41,22 +41,10 @@ type PortMapping struct {
 	Protocol string
 }
 
-// Runtime defines the interface for container runtimes that manage workloads.
-//
-// A workload in ToolHive represents a complete deployment unit that may consist of:
-// - Primary MCP server container
-// - Sidecar containers (for logging, monitoring, proxying, etc.)
-// - Network configurations and port mappings
-// - Volume mounts and storage
-// - Service discovery and load balancing components
-// - Security policies and permission profiles
-//
-// This is a departure from simple container management, as modern deployments
-// often require orchestrating multiple interconnected components that work
-// together to provide a complete service.
-//
-//go:generate mockgen -destination=mocks/mock_runtime.go -package=mocks -source=types.go Runtime
-type Runtime interface {
+// Deployer contains the methods to start and stop a workload.
+// This is intended as a subset of the Runtime interface for
+// the runner code.
+type Deployer interface {
 	// DeployWorkload creates and starts a complete workload deployment.
 	// This includes the primary container, any required sidecars, networking setup,
 	// volume mounts, and service configuration. The workload is started as part
@@ -86,16 +74,45 @@ type Runtime interface {
 		isolateNetwork bool,
 	) (string, int, error)
 
-	// ListWorkloads lists all deployed workloads managed by this runtime.
-	// Returns information about each workload including its components,
-	// status, and resource usage.
-	ListWorkloads(ctx context.Context) ([]ContainerInfo, error)
-
 	// StopWorkload gracefully stops a running workload and all its components.
 	// This includes stopping the primary container, sidecars, and cleaning up
 	// any associated network resources. The workload remains available for restart.
 	StopWorkload(ctx context.Context, workloadID string) error
 
+	// AttachToWorkload establishes a direct connection to the primary container
+	// of the workload for interactive communication. This is typically used
+	// for stdio transport where direct input/output streaming is required.
+	AttachToWorkload(ctx context.Context, workloadID string) (io.WriteCloser, io.ReadCloser, error)
+
+	// IsWorkloadRunning checks if a workload is currently running and healthy.
+	// This verifies that the primary container is running and that any
+	// required sidecars are also operational.
+	IsWorkloadRunning(ctx context.Context, workloadID string) (bool, error)
+}
+
+// Runtime defines the interface for container runtimes that manage workloads.
+//
+// A workload in ToolHive represents a complete deployment unit that may consist of:
+// - Primary MCP server container
+// - Sidecar containers (for logging, monitoring, proxying, etc.)
+// - Network configurations and port mappings
+// - Volume mounts and storage
+// - Service discovery and load balancing components
+// - Security policies and permission profiles
+//
+// This is a departure from simple container management, as modern deployments
+// often require orchestrating multiple interconnected components that work
+// together to provide a complete service.
+//
+//go:generate mockgen -destination=mocks/mock_runtime.go -package=mocks -source=types.go Runtime
+type Runtime interface {
+	Deployer
+
+	// ListWorkloads lists all deployed workloads managed by this runtime.
+	// Returns information about each workload including its components,
+	// status, and resource usage.
+	ListWorkloads(ctx context.Context) ([]ContainerInfo, error)
+
 	// RemoveWorkload completely removes a workload and all its components.
 	// This includes removing containers, cleaning up networks, volumes,
 	// and any other resources associated with the workload. This operation
@@ -108,21 +125,11 @@ type Runtime interface {
 	// main MCP server container.
 	GetWorkloadLogs(ctx context.Context, workloadID string, follow bool) (string, error)
 
-	// IsWorkloadRunning checks if a workload is currently running and healthy.
-	// This verifies that the primary container is running and that any
-	// required sidecars are also operational.
-	IsWorkloadRunning(ctx context.Context, workloadID string) (bool, error)
-
 	// GetWorkloadInfo retrieves detailed information about a workload.
 	// This includes status, resource usage, network configuration,
 	// and metadata about all components in the workload.
 	GetWorkloadInfo(ctx context.Context, workloadID string) (ContainerInfo, error)
 
-	// AttachToWorkload establishes a direct connection to the primary container
-	// of the workload for interactive communication. This is typically used
-	// for stdio transport where direct input/output streaming is required.
-	AttachToWorkload(ctx context.Context, workloadID string) (io.WriteCloser, io.ReadCloser, error)
-
 	// IsRunning checks the health of the container runtime.
 	// This is used to verify that the runtime is operational and can manage workloads.
 	IsRunning(ctx context.Context) error

pkg/container/runtime/types.go

@@ -101,8 +101,8 @@ type RunConfig struct {
 	// Only applicable when using Kubernetes runtime
 	K8sPodTemplatePatch string `json:"k8s_pod_template_patch,omitempty" yaml:"k8s_pod_template_patch,omitempty"`
 
-	// Runtime is the container runtime to use (not serialized)
-	Runtime rt.Runtime `json:"-" yaml:"-"`
+	// Deployer is the container runtime to use (not serialized)
+	Deployer rt.Deployer `json:"-" yaml:"-"`
 
 	// IsolateNetwork indicates whether to isolate the network for the container
 	IsolateNetwork bool `json:"isolate_network,omitempty" yaml:"isolate_network,omitempty"`
@@ -148,7 +148,7 @@ func NewRunConfig() *RunConfig {
 // NewRunConfigFromFlags creates a new RunConfig with values from command-line flags
 func NewRunConfigFromFlags(
 	ctx context.Context,
-	runtime rt.Runtime,
+	runtime rt.Deployer,
 	cmdArgs []string,
 	name string,
 	imageURL string,

pkg/runner/config.go

@@ -39,8 +39,8 @@ func NewRunConfigBuilder() *RunConfigBuilder {
 }
 
 // WithRuntime sets the container runtime
-func (b *RunConfigBuilder) WithRuntime(runtime rt.Runtime) *RunConfigBuilder {
-	b.config.Runtime = runtime
+func (b *RunConfigBuilder) WithRuntime(deployer rt.Deployer) *RunConfigBuilder {
+	b.config.Deployer = deployer
 	return b
 }
 

pkg/runner/config_builder.go

@@ -631,7 +631,7 @@ func TestNewRunConfigFromFlags(t *testing.T) {
 	require.NoError(t, err, "NewRunConfigFromFlags should not return an error")
 
 	assert.NotNil(t, config, "NewRunConfigFromFlags should return a non-nil config")
-	assert.Equal(t, runtime, config.Runtime, "Runtime should match")
+	assert.Equal(t, runtime, config.Deployer, "Deployer should match")
 	assert.Equal(t, targetHost, config.TargetHost, "TargetHost should match")
 	// The metadata args are appended to the command-line args
 	expectedCmdArgs := append([]string{}, cmdArgs...)

pkg/runner/config_test.go

@@ -49,7 +49,7 @@ func (r *Runner) Run(ctx context.Context) error {
 		TargetPort: r.Config.TargetPort,
 		Host:       r.Config.Host,
 		TargetHost: r.Config.TargetHost,
-		Runtime:    r.Config.Runtime,
+		Deployer:   r.Config.Deployer,
 		Debug:      r.Config.Debug,
 	}
 
@@ -163,7 +163,7 @@ func (r *Runner) Run(ctx context.Context) error {
 	// Set up the transport
 	logger.Infof("Setting up %s transport...", r.Config.Transport)
 	if err := transportHandler.Setup(
-		ctx, r.Config.Runtime, r.Config.ContainerName, r.Config.Image, r.Config.CmdArgs,
+		ctx, r.Config.Deployer, r.Config.ContainerName, r.Config.Image, r.Config.CmdArgs,
 		r.Config.EnvVars, r.Config.ContainerLabels, r.Config.PermissionProfile, r.Config.K8sPodTemplatePatch,
 		r.Config.IsolateNetwork,
 	); err != nil {

pkg/runner/runner.go

@@ -13,7 +13,7 @@ var (
 	ErrTransportNotStarted  = errors.New("transport not started")
 	ErrTransportClosed      = errors.New("transport closed")
 	ErrInvalidMessage       = errors.New("invalid message")
-	ErrRuntimeNotSet        = errors.New("container runtime not set")
+	ErrRuntimeNotSet        = errors.New("container deployer not set")
 	ErrContainerIDNotSet    = errors.New("container ID not set")
 	ErrContainerNameNotSet  = errors.New("container name not set")
 )

pkg/transport/errors.go

@@ -20,7 +20,8 @@ func (*Factory) Create(config types.Config) (types.Transport, error) {
 	switch config.Type {
 	case types.TransportTypeStdio:
 		tr := NewStdioTransport(
-			config.Host, config.ProxyPort, config.Runtime, config.Debug, config.PrometheusHandler, config.Middlewares...)
+			config.Host, config.ProxyPort, config.Deployer, config.Debug, config.PrometheusHandler, config.Middlewares...,
+		)
 		tr.SetProxyMode(config.ProxyMode)
 		return tr, nil
 	case types.TransportTypeSSE:
@@ -29,7 +30,7 @@ func (*Factory) Create(config types.Config) (types.Transport, error) {
 			config.Host,
 			config.ProxyPort,
 			config.TargetPort,
-			config.Runtime,
+			config.Deployer,
 			config.Debug,
 			config.TargetHost,
 			config.PrometheusHandler,
@@ -41,7 +42,7 @@ func (*Factory) Create(config types.Config) (types.Transport, error) {
 			config.Host,
 			config.ProxyPort,
 			config.TargetPort,
-			config.Runtime,
+			config.Deployer,
 			config.Debug,
 			config.TargetHost,
 			config.PrometheusHandler,