run: allow passing a custom version of the Docker image (#480)

By default, when using `boe run --docker`, the version of the BOE CLI
will be used (if it is an officially released one), and fall back to
`latest` otherwise. This change allows passing a command line flag to
set the version of the Docker image to use.

Signed-off-by: Ignasi Barrera <ignasi@tetrate.io>

Author: nacx

cli/cmd/run.go

@@ -54,6 +54,7 @@ type Run struct {
 	TestUpstreamCluster     string       `name:"test-upstream-cluster" help:"Name of an existing configured cluster to use as the test upstream. The cluster must be configured via --cluster, --cluster-insecure, or --cluster-json. Mutually exclusive with --test-upstream-host."`
 	Docker                  bool         `help:"Run Envoy as a Docker container instead of using func-e." default:"false" env:"BOE_RUN_DOCKER"`
 	Pull                    string       `name:"pull" help:"Pull policy for the BOE Docker image (missing, always, never). Only applicable when running with --docker." enum:"missing,always,never" default:"missing"`
+	DockerImageVersion      string       `name:"docker-image-version" help:"Override the BOE Docker image tag to use when running with --docker. By default, the image version matches the BOE version."`
 	OCI                     OCIFlags     `embed:""`
 
 	extensionPositions extensionPositions `kong:"-"` // Internal field: tracks the original position of extensions specified via both --extension and --local flags
@@ -103,6 +104,9 @@ func (r *Run) Validate() error {
 	if r.EnvoyPath != "" && r.EnvoyVersion != "" {
 		return fmt.Errorf("--envoy-path and --envoy-version are mutually exclusive")
 	}
+	if r.DockerImageVersion != "" && !r.Docker {
+		return fmt.Errorf("--docker-image-version can only be used with --docker")
+	}
 	return nil
 }
 
@@ -120,6 +124,7 @@ func (r *Run) Run(ctx context.Context, dirs *xdg.Directories, logger *slog.Logge
 			Arch:            runtime.GOARCH,
 			LocalExtensions: r.Local,
 			Pull:            r.Pull,
+			ImageVersion:    r.DockerImageVersion,
 		}
 		return runner.Run(ctx)
 	}

cli/cmd/run_test.go

@@ -108,6 +108,10 @@ Flags:
       --pull="missing"             Pull policy for the BOE Docker image
                                    (missing, always, never). Only applicable
                                    when running with --docker.
+      --docker-image-version=STRING
+                                   Override the BOE Docker image tag to use
+                                   when running with --docker. By default,
+                                   the image version matches the BOE version.
       --registry="%s"
                                    OCI registry URL for the extensions
                                    ($BOE_REGISTRY).
@@ -290,6 +294,14 @@ func TestRunValidateMutualExclusion(t *testing.T) {
 			},
 			expectedErr: "--envoy-path and --envoy-version are mutually exclusive",
 		},
+		{
+			name: "docker image version without docker",
+			run: Run{
+				LogLevel:           "all:error",
+				DockerImageVersion: "custom-version",
+			},
+			expectedErr: "--docker-image-version can only be used with --docker",
+		},
 	}
 
 	for _, tt := range tests {

cli/internal/envoy/runner.go

@@ -391,12 +391,13 @@ type RunnerDocker struct {
 	Arch            string
 	LocalExtensions []string
 	Pull            string
+	ImageVersion    string
 }
 
 // Run starts Envoy in a Docker container.
 func (r *RunnerDocker) Run(ctx context.Context) error {
 	var (
-		version = imageVersion(internal.CurrentVersion())
+		version = imageVersion(internal.CurrentVersion(), r.ImageVersion)
 		image   = fmt.Sprintf("%s/%s:%s", r.Registry, dockerImage, version)
 	)
 
@@ -458,7 +459,10 @@ func (r *RunnerDocker) dockerRunArgs(image string, localExtArgs []string) []stri
 
 // imageVersion returns the image version to use for the Docker runner. For dev versions, it returns "latest"
 // to pull the most recent image. For release versions, it returns the specific version tag to pull the corresponding image.
-func imageVersion(version internal.Version) string {
+func imageVersion(version internal.Version, requestedVersion string) string {
+	if requestedVersion != "" {
+		return requestedVersion
+	}
 	if version.CommitsAhead != 0 || version.ClosestTag == "" || version.Sha == "" {
 		return "latest"
 	}
@@ -525,6 +529,12 @@ func (r *RunnerDocker) processCommandArgs(args []string) []string {
 		// Skip the --docker and --pull flags as they are only relevant to the host CLI
 		// and should not be passed to the container.
 		// Need to do prefix match not equality because flags could be in the form of --docker=true or --pull=always.
+
+		// Handle --docker-image-version value
+		if arg == "--docker-image-version" && i+1 < len(args) {
+			i++ // skip next arg (the value for --docker-image-version)
+			continue
+		}
 		if strings.HasPrefix(arg, "--docker") {
 			continue
 		}

cli/internal/envoy/runner_test.go

@@ -357,9 +357,10 @@ func TestPassthroughEnvVars(t *testing.T) {
 }
 
 func TestImageVersion(t *testing.T) {
-	require.Equal(t, "0.6.6", imageVersion(internal.Version{ClosestTag: "v0.6.6", Sha: "123"}))
-	require.Equal(t, "latest", imageVersion(internal.CurrentVersion()))
-	require.Equal(t, "latest", imageVersion(internal.Version{ClosestTag: "v0.6.6", CommitsAhead: 2, Sha: "123"}))
-	require.Equal(t, "latest", imageVersion(internal.Version{Sha: "123"}))
-	require.Equal(t, "latest", imageVersion(internal.Version{ClosestTag: "v0.6.6", CommitsAhead: 0}))
+	require.Equal(t, "0.6.6", imageVersion(internal.Version{ClosestTag: "v0.6.6", Sha: "123"}, ""))
+	require.Equal(t, "latest", imageVersion(internal.CurrentVersion(), ""))
+	require.Equal(t, "latest", imageVersion(internal.Version{ClosestTag: "v0.6.6", CommitsAhead: 2, Sha: "123"}, ""))
+	require.Equal(t, "latest", imageVersion(internal.Version{Sha: "123"}, ""))
+	require.Equal(t, "latest", imageVersion(internal.Version{ClosestTag: "v0.6.6", CommitsAhead: 0}, ""))
+	require.Equal(t, "custom-version", imageVersion(internal.CurrentVersion(), "custom-version"))
 }

website/src/pages/docs/cli/run.mdx

@@ -116,6 +116,7 @@ boe run --help
 | `--test-upstream-cluster` | Name of an existing configured cluster to use as the test upstream. The cluster must be configured via --cluster, --cluster-insecure, or --cluster-json. Mutually exclusive with --test-upstream-host. | `string` | - | - | No |
 | `--docker` | Run Envoy as a Docker container instead of using func-e. | `bool` | `false` | `BOE_RUN_DOCKER` | No |
 | `--pull` | Pull policy for the BOE Docker image (missing, always, never). Only applicable when running with --docker. | `string` | `missing` | - | No |
+| `--docker-image-version` | Override the BOE Docker image tag to use when running with --docker. By default, the image version matches the BOE version. | `string` | - | - | No |
 | `--registry` | OCI registry URL for the extensions. | `string` | `ghcr.io/tetratelabs/built-on-envoy` | `BOE_REGISTRY` | No |
 | `--insecure` | Allow connecting to an insecure (HTTP) registry. | `bool` | `false` | `BOE_REGISTRY_INSECURE` | No |
 | `--username` | Username for the OCI registry. | `string` | - | `BOE_REGISTRY_USERNAME` | No |