feat(agent): lts tag and a flag for agent image tag (#177)

Author: stevensbkang

INSTALL.md

@@ -98,6 +98,7 @@ export KUBESOLO_PATH="/var/lib/kubesolo"        # Installation path
 export KUBESOLO_PORTAINER_EDGE_ID="your-id"     # Portainer Edge ID
 export KUBESOLO_PORTAINER_EDGE_KEY="your-key"   # Portainer Edge Key
 export KUBESOLO_PORTAINER_EDGE_ASYNC="false"    # Async mode
+export KUBESOLO_PORTAINER_EDGE_IMAGE="docker.io/portainer/agent:lts"  # Edge Agent image
 export KUBESOLO_LOCAL_STORAGE="false"           # Enable local storage
 export KUBESOLO_DEBUG="false"                   # Debug logging
 export KUBESOLO_PPROF_SERVER="false"            # Enable pprof

README.md

@@ -159,6 +159,7 @@ KubeSolo supports the following command-line flags:
 | `--portainer-edge-id` | `KUBESOLO_PORTAINER_EDGE_ID` | Portainer Edge ID | `""` |
 | `--portainer-edge-key` | `KUBESOLO_PORTAINER_EDGE_KEY` | Portainer Edge Key | `""` |
 | `--portainer-edge-async` | `KUBESOLO_PORTAINER_EDGE_ASYNC` | Enable Portainer Edge Async Mode | `false` |
+| `--portainer-edge-image` | `KUBESOLO_PORTAINER_EDGE_IMAGE` | Image deployed for the Portainer Edge Agent, including the tag. Any image other than the default is pulled from the registry rather than loaded from the embedded image | `docker.io/portainer/agent:lts` |
 | `--load-balancer` | `KUBESOLO_LOAD_BALANCER` | Enable load balancer. With this enabled, kubesolo will update a newly deployed service with the load balancer type so that the EXTERNAL-IP is set to the node IP | `true` |
 | `--local-storage` | `KUBESOLO_LOCAL_STORAGE` | Enable local storage | `true` |
 | `--local-storage-shared-path` | `KUBESOLO_LOCAL_STORAGE_SHARED_PATH` | Path to the shared file system for the local storage | `""` |

build/download-deps.sh

@@ -8,7 +8,7 @@ ARCH="amd64"
 CONTAINERD_VERSION="2.2.5"
 CRUN_VERSION="1.26"
 CNI_VERSION="v1.9.0"
-PORTAINER_AGENT_VERSION="2.39.4"
+PORTAINER_AGENT_VERSION="lts"
 COREDNS_VERSION="1.14.4"
 LOCAL_PATH_PROVISIONER_VERSION="v0.0.36"
 PAUSE_IMAGE_VERSION="3.10"

cmd/kubesolo/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"fmt"
 	"os"
 	"os/signal"
 	"path/filepath"
@@ -11,6 +12,7 @@ import (
 	"syscall"
 
 	"github.com/alecthomas/kingpin/v2"
+	"github.com/distribution/reference"
 	"github.com/portainer/kubesolo/internal/config/flags"
 	"github.com/portainer/kubesolo/internal/core/embedded"
 	"github.com/portainer/kubesolo/internal/core/pki"
@@ -47,6 +49,7 @@ type kubesolo struct {
 	portainerEdgeID        string
 	portainerEdgeKey       string
 	portainerEdgeAsync     bool
+	portainerEdgeImage     string
 	loadBalancer           bool
 	localStorage           bool
 	localStorageSharedPath string
@@ -78,6 +81,11 @@ func service() (*kubesolo, error) {
 		log.Fatal().Str("component", "kubesolo").Msg("--d2k requires --load-balancer: the d2k Service endpoint is populated by the LoadBalancer webhook")
 	}
 
+	portainerEdgeImage, err := normaliseImageRef(*flags.PortainerEdgeImage)
+	if err != nil {
+		return nil, err
+	}
+
 	return &kubesolo{
 		hostName:               system.GetHostname(),
 		extraSANs:              *flags.APIServerExtraSANs,
@@ -86,6 +94,7 @@ func service() (*kubesolo, error) {
 		portainerEdgeID:        *flags.PortainerEdgeID,
 		portainerEdgeKey:       *flags.PortainerEdgeKey,
 		portainerEdgeAsync:     *flags.PortainerEdgeAsync,
+		portainerEdgeImage:     portainerEdgeImage,
 		loadBalancer:           *flags.LoadBalancer,
 		localStorage:           *flags.LocalStorage,
 		localStorageSharedPath: *flags.LocalStorageSharedPath,
@@ -96,6 +105,19 @@ func service() (*kubesolo, error) {
 	}, nil
 }
 
+// normaliseImageRef expands a short image reference such as portainerci/agent:develop
+// into a fully qualified one (docker.io/portainerci/agent:develop). The containerd
+// client, unlike the Docker CLI, applies no Docker Hub defaults and would otherwise
+// treat the first component as a registry host and fail to resolve it.
+func normaliseImageRef(image string) (string, error) {
+	named, err := reference.ParseNormalizedNamed(image)
+	if err != nil {
+		return "", fmt.Errorf("invalid image reference %q: %v", image, err)
+	}
+
+	return reference.TagNameOnly(named).String(), nil
+}
+
 // main is the entry point for the kubesolo application
 // it parses the command line arguments and creates a new kubesolo application
 // it then bootstraps the application and runs it
@@ -276,6 +298,7 @@ func (s *kubesolo) run() {
 	if s.portainerEdgeID != "" && s.portainerEdgeKey != "" {
 		log.Info().Str("component", "kubesolo").Msg("deploying portainer edge agent...")
 		if err := portainer.DeployEdgeAgent(s.embedded.AdminKubeconfigFile, types.EdgeAgentConfig{
+			Image:            s.portainerEdgeImage,
 			EdgeID:           s.portainerEdgeID,
 			EdgeKey:          s.portainerEdgeKey,
 			EdgeAsync:        s.portainerEdgeAsync,
@@ -531,7 +554,7 @@ func (s *kubesolo) bootstrap() {
 		WebhookDir: filepath.Join(basePath, types.KubesoloWebhookDir),
 
 		// Image paths
-		PortainerAgentImageFile:       filepath.Join(basePath, types.DefaultContainerdDir, "images", "portainer-agent.tar.gz"),
+		PortainerEdgeImageFile:        filepath.Join(basePath, types.DefaultContainerdDir, "images", "portainer-agent.tar.gz"),
 		CorednsImageFile:              filepath.Join(basePath, types.DefaultContainerdDir, "images", "coredns.tar.gz"),
 		SandboxImageFile:              filepath.Join(basePath, types.DefaultContainerdDir, "images", "pause.tar.gz"),
 		LocalPathProvisionerImageFile: filepath.Join(basePath, types.DefaultContainerdDir, "images", "local-path-provisioner.tar.gz"),
@@ -543,7 +566,8 @@ func (s *kubesolo) bootstrap() {
 		LocalPathStorageDir: filepath.Join(basePath, types.DefaultLocalPathStorageDir),
 
 		// Portainer Edge
-		IsPortainerEdge: s.portainerEdgeID != "" && s.portainerEdgeKey != "",
+		IsPortainerEdge:    s.portainerEdgeID != "" && s.portainerEdgeKey != "",
+		PortainerEdgeImage: s.portainerEdgeImage,
 
 		// Container Mode
 		ContainerMode: containerMode,

cmd/kubesolo/main_test.go

@@ -0,0 +1,32 @@
+package main
+
+import "testing"
+
+func TestNormaliseImageRef(t *testing.T) {
+	tests := []struct {
+		in   string
+		want string
+	}{
+		{"docker.io/portainer/agent:lts", "docker.io/portainer/agent:lts"},
+		{"portainer/agent:lts", "docker.io/portainer/agent:lts"},
+		{"portainerci/agent:develop", "docker.io/portainerci/agent:develop"},
+		{"portainerci/agent", "docker.io/portainerci/agent:latest"},
+		{"ghcr.io/portainer/agent:1.0", "ghcr.io/portainer/agent:1.0"},
+		{"localhost:5000/agent:dev", "localhost:5000/agent:dev"},
+	}
+
+	for _, tt := range tests {
+		got, err := normaliseImageRef(tt.in)
+		if err != nil {
+			t.Errorf("normaliseImageRef(%q) returned error: %v", tt.in, err)
+			continue
+		}
+		if got != tt.want {
+			t.Errorf("normaliseImageRef(%q) = %q, want %q", tt.in, got, tt.want)
+		}
+	}
+
+	if _, err := normaliseImageRef("NOT A REF"); err == nil {
+		t.Errorf("normaliseImageRef should reject an invalid reference")
+	}
+}

docs/installation/flags.md

@@ -116,6 +116,27 @@ curl -sfL https://get.kubesolo.io | \
 
 ---
 
+### --portainer-edge-image
+
+Full image reference deployed for the Portainer Edge Agent, including the tag. Accepts any registry, repository, and tag. Only the default image is loaded from the bundled image; any other reference is pulled from the registry, so the node needs access to it. If the registry cannot be reached at startup, KubeSolo logs a warning and continues — the kubelet retries the pull when the agent pod starts.
+
+Short references are expanded the way Docker expands them, so `portainerci/agent:develop` becomes `docker.io/portainerci/agent:develop` and an omitted tag defaults to `latest`. Use a full host prefix for other registries, e.g. `ghcr.io/portainer/agent:2.34.0`.
+
+Note that the deployment is only created once — on reboot it is restored from the database. Changing this flag on an existing installation does not update an already deployed agent.
+
+| Flag | Env var | Default |
+|---|---|---|
+| `--portainer-edge-image=IMAGE` | `KUBESOLO_PORTAINER_EDGE_IMAGE` | `docker.io/portainer/agent:lts` |
+
+```bash
+curl -sfL https://get.kubesolo.io | \
+  KUBESOLO_PORTAINER_EDGE_ID=<your-edge-id> \
+  KUBESOLO_PORTAINER_EDGE_KEY=<your-edge-key> \
+  sudo -E sh -s -- --portainer-edge-image=docker.io/portainer/agent:sts
+```
+
+---
+
 ### --local-storage
 
 Enable the [Local Path Provisioner](https://github.com/rancher/local-path-provisioner), which creates a `local-path` StorageClass backed by host-local directories. Workloads that request persistent volumes will have them provisioned automatically under the KubeSolo data path.

docs/installation/kubesoloctl.md

@@ -104,6 +104,7 @@ Common flags:
 | `--container-ports` | `KUBESOLO_CONTAINER_PORTS` | _(none)_ | Workload host ports to publish (container mode) |
 | `--d2k` | `KUBESOLO_D2K` | `false` | Enable the Docker-compatible API translator |
 | `--local-storage` | `KUBESOLO_LOCAL_STORAGE` | `false` | Enable the local-path storage provisioner |
+| `--portainer-edge-image` | `KUBESOLO_PORTAINER_EDGE_IMAGE` | `docker.io/portainer/agent:lts` | Image deployed for the Portainer edge agent |
 | `--offline-install` | `KUBESOLO_OFFLINE_INSTALL` | _(none)_ | Install from a local tarball/binary instead of downloading |
 | `--proxy` | `KUBESOLO_PROXY` | _(none)_ | HTTP/HTTPS proxy injected into the service environment |
 

go.mod

@@ -7,6 +7,7 @@ require (
 	github.com/containerd/containerd/v2 v2.2.3
 	github.com/containerd/errdefs v1.0.0
 	github.com/containerd/fuse-overlayfs-snapshotter/v2 v2.1.7
+	github.com/distribution/reference v0.6.0
 	github.com/docker/docker v28.5.2+incompatible
 	github.com/docker/go-connections v0.5.0
 	github.com/k3s-io/kine v0.15.0
@@ -77,7 +78,6 @@ require (
 	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
 	github.com/cyphar/filepath-securejoin v0.6.0 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
-	github.com/distribution/reference v0.6.0 // indirect
 	github.com/docker/go-events v0.0.0-20190806004212-e31b211e4f1c // indirect
 	github.com/docker/go-metrics v0.0.1 // indirect
 	github.com/docker/go-units v0.5.0 // indirect

install.sh

@@ -1082,6 +1082,7 @@ APISERVER_EXTRA_SANS="${KUBESOLO_APISERVER_EXTRA_SANS:-}"
 PORTAINER_EDGE_ID="${KUBESOLO_PORTAINER_EDGE_ID:-}"
 PORTAINER_EDGE_KEY="${KUBESOLO_PORTAINER_EDGE_KEY:-}"
 PORTAINER_EDGE_ASYNC="${KUBESOLO_PORTAINER_EDGE_ASYNC:-false}"
+PORTAINER_EDGE_IMAGE="${KUBESOLO_PORTAINER_EDGE_IMAGE:-}"
 LOAD_BALANCER="${KUBESOLO_LOAD_BALANCER:-true}"
 LOCAL_STORAGE="${KUBESOLO_LOCAL_STORAGE:-true}"
 LOCAL_STORAGE_SHARED_PATH="${KUBESOLO_LOCAL_STORAGE_SHARED_PATH:-}"
@@ -1120,6 +1121,9 @@ for arg in "$@"; do
     --portainer-edge-async=*)
       PORTAINER_EDGE_ASYNC="${arg#*=}"
       ;;
+    --portainer-edge-image=*)
+      PORTAINER_EDGE_IMAGE="${arg#*=}"
+      ;;
     --local-storage=*)
       LOCAL_STORAGE="${arg#*=}"
       ;;
@@ -1165,6 +1169,7 @@ for arg in "$@"; do
       echo "  --portainer-edge-id=ID       Set Portainer Edge ID"
       echo "  --portainer-edge-key=KEY     Set Portainer Edge Key"
       echo "  --portainer-edge-async=true|false   Enable Portainer Edge Async (default: $PORTAINER_EDGE_ASYNC)"
+      echo "  --portainer-edge-image=IMAGE        Set the Portainer Edge Agent image (default: docker.io/portainer/agent:lts)"
       echo "  --local-storage=true|false   Enable local storage (default: $LOCAL_STORAGE)"
       echo "  --d2k=true|false             Embed d2k Docker-to-Kubernetes API translator (default: $D2K)"
       echo "  --d2k-namespace=NAMESPACE    Namespace into which d2k is deployed (default: $D2K_NAMESPACE)"
@@ -1304,6 +1309,10 @@ if [ "$PORTAINER_EDGE_ASYNC" = "true" ]; then
   CMD_ARGS="$CMD_ARGS --portainer-edge-async=true"
 fi
 
+if [ -n "$PORTAINER_EDGE_IMAGE" ]; then
+  CMD_ARGS="$CMD_ARGS --portainer-edge-image=$PORTAINER_EDGE_IMAGE"
+fi
+
 if [ "$LOAD_BALANCER" = "false" ]; then
   CMD_ARGS="$CMD_ARGS --load-balancer=false"
 fi

internal/cli/cmd_install.go

@@ -61,6 +61,11 @@ func addInstallFlags(cmd *cobra.Command, cfg *config.Config) {
 		envBool("KUBESOLO_PORTAINER_EDGE_ASYNC", false),
 		"Enable async mode for the Portainer edge agent")
 
+	f.StringVar(&cfg.PortainerEdgeImage, "portainer-edge-image",
+		os.Getenv("KUBESOLO_PORTAINER_EDGE_IMAGE"),
+		"Image deployed for the Portainer edge agent, including the tag\n"+
+			"(default: docker.io/portainer/agent:lts). Any other image is pulled from the registry")
+
 	f.BoolVar(&cfg.LocalStorage, "local-storage",
 		envBool("KUBESOLO_LOCAL_STORAGE", false),
 		"Enable the local-path storage provisioner")