Merge pull request #166 from thin-edge/feat-set-container-host-in-config

reubenmiller · web-flow · commit 542cecf08988 · 2025-09-10T13:20:01.000Z
feat: support setting explicit container host socket path in config file
diff --git a/README.md b/README.md
@@ -51,6 +51,34 @@ The following features are supported by the plugin:
 
 ## Documentation
 
+### Container Engine Detection
+
+The plugin primarily uses the unix socket to interact with the container engine.
+
+By default, the socket is auto detected by checking a list of known socket paths, and taking the first matching socket that exists. If no socket is found, then the application will repeat the socket detection and eventually giving up after a period of time.
+
+The following table shows the list container engine socket paths and the order of precedence (where the first existing socket is used).
+
+|Socket Path|Description|
+|-----------|-----------|
+|$DOCKER_HOST|Default Docker Environment variable|
+|$CONTAINER_HOST|Default Podman Environment variable|
+|unix:///run/user/{uid}/docker.sock|Docker rootless|
+|unix://$XDG_RUNTIME_DIR/podman/podman.sock|Podman rootless|
+|unix:///tmp/storage-run-{uid}/podman/podman.sock|Podman rootless|
+|unix:///var/run/docker.sock|Docker (rootful)|
+|unix:///run/podman/podman.sock|Podman (rootful)|
+|unix:///run/user/0/podman/podman.sock|Podman (rootful)|
+
+Where `{uid}` is either the value of the `SUDO_UID` environment variable (if present), or the process's effective user ID.
+
+If your device is not finding the correct socket path for your container engine, then you can explicitly set the socket path in the `tedge-container-plugin.toml` file. Below shows an example of such a snippet which forces the usage of the rootful podman api endpoint. You will need to restart the tedge-container-plugin service before the setting will take effect.
+
+```toml
+[container]
+host = "unix:///run/podman/podman.sock"
+```
+
 ### Install/remove single containers
 
 Containers can be installed and removed via the Cumulocity Software Management interface in the Device Management Application.
diff --git a/cli/container/list.go b/cli/container/list.go
@@ -22,7 +22,7 @@ func NewListCommand(cliContext cli.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			slog.Info("Executing", "cmd", cmd.CalledAs(), "args", args)
 			ctx := context.Background()
-			cli, err := container.NewContainerClient(ctx)
+			cli, err := container.NewContainerClient(ctx, cliContext.GetContainerClientOptions()...)
 			if err != nil {
 				return err
 			}
diff --git a/cli/container/remove.go b/cli/container/remove.go
@@ -19,7 +19,7 @@ type RemoveCommand struct {
 }
 
 // removeCmd represents the remove command
-func NewRemoveCommand(ctx cli.Cli) *cobra.Command {
+func NewRemoveCommand(cliContext cli.Cli) *cobra.Command {
 	command := &RemoveCommand{}
 	cmd := &cobra.Command{
 		Use:   "remove",
@@ -35,7 +35,7 @@ Example 1: Remove a container
 			ctx := context.Background()
 			containerName := args[0]
 
-			cli, err := container.NewContainerClient(ctx)
+			cli, err := container.NewContainerClient(ctx, cliContext.GetContainerClientOptions()...)
 			if err != nil {
 				return err
 			}
diff --git a/cli/container_group/finalize.go b/cli/container_group/finalize.go
@@ -13,18 +13,18 @@ import (
 	"github.com/thin-edge/tedge-container-plugin/pkg/container"
 )
 
-func NewFinalizeCommand(ctx cli.Cli) *cobra.Command {
+func NewFinalizeCommand(cliContext cli.Cli) *cobra.Command {
 	return &cobra.Command{
 		Use:   "finalize",
 		Short: "Finalize container install/remove operation",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			slog.Info("Executing", "cmd", cmd.CalledAs(), "args", args)
 
-			pruneImages := ctx.GetBool("container.pruneImages")
+			pruneImages := cliContext.GetBool("container.pruneImages")
 			if !pruneImages {
 				return nil
 			}
-			cli, err := container.NewContainerClient(context.TODO())
+			cli, err := container.NewContainerClient(context.TODO(), cliContext.GetContainerClientOptions()...)
 			if err != nil {
 				return err
 			}
diff --git a/cli/container_group/install.go b/cli/container_group/install.go
@@ -52,7 +52,7 @@ func (c *InstallCommand) RunE(cmd *cobra.Command, args []string) error {
 	projectName := args[0]
 	stderr := cmd.ErrOrStderr()
 
-	cli, err := container.NewContainerClient(context.TODO())
+	cli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/cli/container_group/list.go b/cli/container_group/list.go
@@ -42,7 +42,7 @@ func NewListCommand(cliContext cli.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			slog.Info("Executing", "cmd", cmd.CalledAs(), "args", args)
 			ctx := context.Background()
-			cli, err := container.NewContainerClient(context.TODO())
+			cli, err := container.NewContainerClient(context.TODO(), cliContext.GetContainerClientOptions()...)
 			if err != nil {
 				return err
 			}
diff --git a/cli/container_group/remove.go b/cli/container_group/remove.go
@@ -40,7 +40,7 @@ func (c *RemoveCommand) RunE(cmd *cobra.Command, args []string) error {
 	ctx := context.Background()
 	projectName := args[0]
 
-	cli, err := container.NewContainerClient(context.TODO())
+	cli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/cli/engine/docker.go b/cli/engine/docker.go
@@ -15,11 +15,15 @@ import (
 
 type DockerCommand struct {
 	*cobra.Command
+
+	CommandContext cli.Cli
 }
 
 // NewRunCommand create a new run command
 func NewRunCommand(ctx cli.Cli) *cobra.Command {
-	command := &DockerCommand{}
+	command := &DockerCommand{
+		CommandContext: ctx,
+	}
 	cmd := &cobra.Command{
 		Use:                "docker",
 		Short:              "Run a command using the detected container engine",
@@ -34,7 +38,7 @@ func NewRunCommand(ctx cli.Cli) *cobra.Command {
 
 func (c *DockerCommand) RunE(cmd *cobra.Command, args []string) error {
 	slog.Debug("Executing", "cmd", cmd.CalledAs(), "args", args)
-	containerCli, err := container.NewContainerClient(context.TODO())
+	containerCli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/cli/run/cmd.go b/cli/run/cmd.go
@@ -45,6 +45,7 @@ func NewRunCommand(cliContext cli.Cli) *cobra.Command {
 
 			device := cliContext.GetDeviceTarget()
 			application, err := app.NewApp(device, app.Config{
+				ContainerHost:      cliContext.GetContainerHost(),
 				ServiceName:        cliContext.GetServiceName(),
 				EnableMetrics:      cliContext.MetricsEnabled(),
 				DeleteFromCloud:    cliContext.DeleteFromCloud(),
diff --git a/cli/self/check.go b/cli/self/check.go
@@ -52,12 +52,15 @@ var SoftwareManagementActionRemove = "remove"
 type CheckCommand struct {
 	*cobra.Command
 
-	ContainerName string
+	CommandContext cli.Cli
+	ContainerName  string
 }
 
 // NewCheckCommand represents the check command
 func NewCheckCommand(ctx cli.Cli) *cobra.Command {
-	command := &CheckCommand{}
+	command := &CheckCommand{
+		CommandContext: ctx,
+	}
 	cmd := &cobra.Command{
 		Use:   "check",
 		Args:  cobra.ExactArgs(1),
@@ -78,7 +81,7 @@ func (c *CheckCommand) RunE(cmd *cobra.Command, args []string) error {
 	}
 
 	// Check container self
-	containerCLI, err := container.NewContainerClient(context.TODO())
+	containerCLI, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/cli/self/list.go b/cli/self/list.go
@@ -36,7 +36,7 @@ func NewListCommand(cliContext cli.Cli) *cobra.Command {
 			}
 
 			ctx := context.Background()
-			containerCli, err := container.NewContainerClient(context.TODO())
+			containerCli, err := container.NewContainerClient(context.TODO(), cliContext.GetContainerClientOptions()...)
 			if err != nil {
 				return newNotSupportedErr(err)
 			}
diff --git a/cli/tools/container_clone.go b/cli/tools/container_clone.go
@@ -87,7 +87,7 @@ func (c *ContainerCloneCommand) RunE(cmd *cobra.Command, args []string) error {
 		slog.Info("Custom args.", "args", containerCmd)
 	}
 
-	containerCli, err := container.NewContainerClient(context.TODO())
+	containerCli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/cli/tools/container_logs.go b/cli/tools/container_logs.go
@@ -54,7 +54,7 @@ func NewContainerLogsCommand(ctx cli.Cli) *cobra.Command {
 func (c *ContainerLogsCommand) RunE(cmd *cobra.Command, args []string) error {
 	slog.Debug("Executing", "cmd", cmd.CalledAs(), "args", args)
 
-	containerCli, err := container.NewContainerClient(context.TODO())
+	containerCli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/cli/tools/container_remove.go b/cli/tools/container_remove.go
@@ -46,7 +46,7 @@ func NewContainerRemoveCommand(ctx cli.Cli) *cobra.Command {
 func (c *ContainerRemoveCommand) RunE(cmd *cobra.Command, args []string) error {
 	slog.Debug("Executing", "cmd", cmd.CalledAs(), "args", args)
 
-	containerCli, err := container.NewContainerClient(context.TODO())
+	containerCli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/cli/tools/container_restart.go b/cli/tools/container_restart.go
@@ -40,7 +40,7 @@ func NewContainerRestartCommand(ctx cli.Cli) *cobra.Command {
 func (c *ContainerRestartCommand) RunE(cmd *cobra.Command, args []string) error {
 	slog.Debug("Executing", "cmd", cmd.CalledAs(), "args", args)
 
-	containerCli, err := container.NewContainerClient(context.TODO())
+	containerCli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/cli/tools/run_context.go b/cli/tools/run_context.go
@@ -59,7 +59,7 @@ func NewContainerRunInContextCommand(ctx cli.Cli) *cobra.Command {
 func (c *ContainerRunInContextCommand) RunE(cmd *cobra.Command, args []string) error {
 	slog.Debug("Executing", "cmd", cmd.CalledAs(), "args", args)
 
-	containerCli, err := container.NewContainerClient(context.TODO())
+	containerCli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)
 	if err != nil {
 		return err
 	}
diff --git a/packaging/config.toml b/packaging/config.toml
@@ -49,6 +49,12 @@ cert_file = "/etc/tedge/device-certs/local-tedge.crt"
   port = 8001
 
 [container]
+# Custom container engine host. If missing or blank, then the host will be auto detected
+# Container engine host/socket address .e.g. unix:///run/podman/podman.sock.
+# If the value is missing or an empty string, then the socket will be auto detected.
+# If the auto detection mechanism is not working for you, then set the path to the expected socket address.
+#host = "unix:///run/podman/podman.sock"
+
 # Always try pulling the image without checking if a local image already exists or not
 alwayspull = false
 
diff --git a/pkg/app/app.go b/pkg/app/app.go
@@ -58,6 +58,8 @@ type App struct {
 }
 
 type Config struct {
+	ContainerHost string
+
 	ServiceName string
 
 	// TLS
@@ -99,10 +101,18 @@ func NewApp(device tedge.Target, config Config) (*App, error) {
 	ctx, ctxCancel := context.WithTimeout(context.TODO(), 300*time.Second)
 	defer ctxCancel()
 
+	clientOptions := make([]container.Opt, 0)
+
+	// Use a time-based timeout instead of limiting number of retries
+	clientOptions = append(clientOptions, container.WithInfiniteRetries())
+
+	if config.ContainerHost != "" {
+		clientOptions = append(clientOptions, container.WithHost(config.ContainerHost))
+	}
+
 	containerClient, err := container.NewContainerClient(
 		ctx,
-		// Use a time-based timeout instead of limiting number of retries
-		container.WithInfiniteRetries(),
+		clientOptions...,
 	)
 	if err != nil {
 		return nil, err
diff --git a/pkg/cli/cli.go b/pkg/cli/cli.go
@@ -107,6 +107,19 @@ func (c *Cli) GetBool(key string) bool {
 	return viper.GetBool(key)
 }
 
+func (c *Cli) GetContainerClientOptions() []container.Opt {
+	options := make([]container.Opt, 0)
+	if v := c.GetContainerHost(); v != "" {
+		options = append(options, container.WithHost(v))
+	}
+	return options
+}
+
+// GetContainerHost get the container engine's host configuration (if manually defined by the user)
+func (c *Cli) GetContainerHost() string {
+	return viper.GetString("container.host")
+}
+
 func (c *Cli) PrintConfig() {
 	keys := viper.AllKeys()
 	sort.Strings(keys)

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ func NewListCommand(cliContext cli.Cli) *cobra.Command {`
`22`	`22`	`RunE: func(cmd *cobra.Command, args []string) error {`
`23`	`23`	`slog.Info("Executing", "cmd", cmd.CalledAs(), "args", args)`
`24`	`24`	`ctx := context.Background()`
`25`		`- cli, err := container.NewContainerClient(ctx)`
	`25`	`+ cli, err := container.NewContainerClient(ctx, cliContext.GetContainerClientOptions()...)`
`26`	`26`	`if err != nil {`
`27`	`27`	`return err`
`28`	`28`	`}`
Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ func (c InstallCommand) RunE(cmd cobra.Command, args []string) error {`
`52`	`52`	`projectName := args[0]`
`53`	`53`	`stderr := cmd.ErrOrStderr()`
`54`	`54`
`55`		`- cli, err := container.NewContainerClient(context.TODO())`
	`55`	`+ cli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)`
`56`	`56`	`if err != nil {`
`57`	`57`	`return err`
`58`	`58`	`}`
Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ func NewListCommand(cliContext cli.Cli) *cobra.Command {`
`42`	`42`	`RunE: func(cmd *cobra.Command, args []string) error {`
`43`	`43`	`slog.Info("Executing", "cmd", cmd.CalledAs(), "args", args)`
`44`	`44`	`ctx := context.Background()`
`45`		`- cli, err := container.NewContainerClient(context.TODO())`
	`45`	`+ cli, err := container.NewContainerClient(context.TODO(), cliContext.GetContainerClientOptions()...)`
`46`	`46`	`if err != nil {`
`47`	`47`	`return err`
`48`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@ func (c RemoveCommand) RunE(cmd cobra.Command, args []string) error {`
`40`	`40`	`ctx := context.Background()`
`41`	`41`	`projectName := args[0]`
`42`	`42`
`43`		`- cli, err := container.NewContainerClient(context.TODO())`
	`43`	`+ cli, err := container.NewContainerClient(context.TODO(), c.CommandContext.GetContainerClientOptions()...)`
`44`	`44`	`if err != nil {`
`45`	`45`	`return err`
`46`	`46`	`}`