feat: add support for preserving and labeling intermediate stage images

This adds support for preserving and labeling intermediate stage images
in multi-stage builds. In contrast to the --layers flag, --cache-stages
preserves only the final image from each named stage (FROM ... AS name),
not every instruction layer. This also keeps the final image's layer count
unchanged compared to a regular build.

New flags:
 - --cache-stages: preserve intermediate stage images instead of removing them
 - --stage-labels: add metadata labels to intermediate stage images (stage name,
   base image, build ID, parent stage name). Requires --cache-stages.
 - --build-id-file: write unique build ID (UUID) to file for easier
   identification and grouping of intermediate images from a single build.
   Requires --stage-labels.

The implementation also includes:
 - Detection of transitive alias patterns (stage using another intermediate
   stage as base)
 - Validation that --stage-labels requires --cache-stages
 - Validation that --build-id-file requires --stage-labels
 - Test coverage (15 tests) and documentation updates

This functionality is useful for debugging, exploring, and reusing
intermediate stage images in multi-stage builds.

Signed-off-by: Erik Mravec <[email protected]>

Author: ezopezo

define/build.go

@@ -262,6 +262,8 @@ type BuildOptions struct {
 	DefaultMountsFilePath string
 	// IIDFile tells the builder to write the image ID to the specified file
 	IIDFile string
+	// BuildIDFile tells the builder to write the build ID to the specified file
+	BuildIDFile string
 	// Squash tells the builder to produce an image with a single layer instead of with
 	// possibly more than one layer, by only committing a new layer after processing the
 	// final instruction.
@@ -276,6 +278,12 @@ type BuildOptions struct {
 	OnBuild []string
 	// Layers tells the builder to commit an image for each step in the Dockerfile.
 	Layers bool
+	// CacheStages tells the builder to preserve intermediate stage images instead of removing them.
+	CacheStages bool
+	// StageLabels tells the builder to add metadata labels to intermediate stage images for easier recognition.
+	// These labels include stage name, index, base image, build ID, and whether it's the final stage.
+	// This option requires CacheStages to be enabled.
+	StageLabels bool
 	// NoCache tells the builder to build the image from scratch without checking for a cache.
 	// It creates a new set of cached images for the build.
 	NoCache bool

docs/buildah-build.1.md

@@ -515,6 +515,13 @@ Path to an alternative .containerignore (.dockerignore) file.
 Write the built image's ID to the file.  When `--platform` is specified more
 than once, attempting to use this option will trigger an error.
 
+**--build-id-file** *BuildIDfile*
+
+Write a unique build ID (UUID) to the file. This build ID is generated once per
+build and is added to intermediate stage images as a label (`io.buildah.build.id`)
+when `--stage-labels` is enabled. This allows grouping all intermediate images
+from a single build together. This option requires `--stage-labels` to be enabled.
+
 **--inherit-annotations** *bool-value*
 
 Inherit the annotations from the base image or base stages. (default true).
@@ -586,6 +593,33 @@ Cache intermediate images during the build process (Default is `false`).
 Note: You can also override the default value of layers by setting the BUILDAH\_LAYERS
 environment variable. `export BUILDAH_LAYERS=true`
 
+**--cache-stages** *bool-value*
+
+Preserve intermediate stage images instead of removing them after the build completes
+(Default is `false`). By default, buildah removes intermediate stage images to save space.
+This option keeps those images, which can be useful for debugging multi-stage builds or
+for reusing intermediate stages in subsequent builds.
+
+Note: This option only preserves stage images (FROM ... AS stage_name). It does not affect
+the behavior of `--layers`, which controls per-instruction caching within stages.
+
+When combined with `--stage-labels`, intermediate images will include metadata labels
+for easier identification and management.
+
+**--stage-labels** *bool-value*
+
+Add metadata labels to intermediate stage images (Default is `false`). This option
+requires `--cache-stages` to be enabled.
+
+When enabled, intermediate stage images will be labeled with:
+- `io.buildah.stage.name`: The stage name (from `FROM ... AS name`)
+- `io.buildah.stage.base`: The base image used by this stage
+- `io.buildah.stage.parent_name`: The parent stage name (if this stage uses another stage as base)
+- `io.buildah.build.id`: A unique build ID shared across all stages in a single build
+
+These labels make it easier to identify, query, and manage intermediate images from
+multi-stage builds.
+
 **--logfile** *filename*
 
 Log output which would be sent to standard output and standard error to the
@@ -1385,6 +1419,10 @@ buildah build -v /var/lib/dnf:/var/lib/dnf:O -t imageName .
 
 buildah build --layers -t imageName .
 
+buildah build --cache-stages --stage-labels -t imageName .
+
+buildah build --cache-stages --stage-labels --build-id-file /tmp/build-id.txt -t imageName .
+
 buildah build --no-cache -t imageName .
 
 buildah build -f Containerfile --layers --force-rm -t imageName .
@@ -1443,6 +1481,21 @@ buildah build --output type=tar,dest=out.tar .
 
 buildah build -o - . > out.tar
 
+### Preserving and querying intermediate stage images
+
+Build a multi-stage image while preserving intermediate stages with metadata labels:
+
+buildah build --cache-stages --stage-labels --build-id-file /tmp/build-id.txt -t myapp .
+
+Query intermediate images from a specific build using the build ID:
+
+BUILD_ID=$(cat /tmp/build-id.txt)
+buildah images --filter "label=io.buildah.build.id=${BUILD_ID}"
+
+Find an intermediate image for a specific stage name:
+
+buildah images --filter "label=io.buildah.stage.name=builder"
+
 ### Building an image using a URL
 
   This will clone the specified GitHub repository from the URL and use it as context. The Containerfile or Dockerfile at the root of the repository is used as the context of the build. This only works if the GitHub repository is a dedicated repository.

go.mod

@@ -15,6 +15,7 @@ require (
 	github.com/docker/go-connections v0.6.0
 	github.com/docker/go-units v0.5.0
 	github.com/fsouza/go-dockerclient v1.12.2
+	github.com/google/uuid v1.6.0
 	github.com/hashicorp/go-multierror v1.1.1
 	github.com/mattn/go-shellwords v1.0.12
 	github.com/moby/buildkit v0.26.0
@@ -76,7 +77,6 @@ require (
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/go-containerregistry v0.20.6 // indirect
 	github.com/google/go-intervals v0.0.2 // indirect
-	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/mux v1.8.1 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect

imagebuildah/executor.go

@@ -22,6 +22,7 @@ import (
 	"github.com/containers/buildah/pkg/sshagent"
 	"github.com/containers/buildah/util"
 	encconfig "github.com/containers/ocicrypt/config"
+	"github.com/google/uuid"
 	digest "github.com/opencontainers/go-digest"
 	v1 "github.com/opencontainers/image-spec/specs-go/v1"
 	"github.com/openshift/imagebuilder"
@@ -111,6 +112,11 @@ type executor struct {
 	layerLabels                             []string
 	annotations                             []string
 	layers                                  bool
+	cacheStages                             bool
+	stageLabels                             bool
+	buildID                                 string
+	buildIDFile                             string
+	intermediateStageParents                map[string]struct{} // Tracks which intermediate stages are used as base by other intermediate stages
 	noHostname                              bool
 	noHosts                                 bool
 	useCache                                bool
@@ -248,6 +254,19 @@ func newExecutor(logger *logrus.Logger, logPrefix string, store storage.Store, o
 		buildOutputs = append(buildOutputs, options.BuildOutput) //nolint:staticcheck
 	}
 
+	// Generate unique build ID if stage labels or build ID file are enabled
+	var buildID string
+	if options.StageLabels || options.BuildIDFile != "" {
+		buildID = uuid.New().String()
+
+		// Write build ID to file if requested
+		if options.BuildIDFile != "" {
+			if err := os.WriteFile(options.BuildIDFile, []byte(buildID), 0o644); err != nil {
+				return nil, fmt.Errorf("writing build ID to file %q: %w", options.BuildIDFile, err)
+			}
+		}
+	}
+
 	exec := executor{
 		args:                                    options.Args,
 		cacheFrom:                               options.CacheFrom,
@@ -293,13 +312,18 @@ func newExecutor(logger *logrus.Logger, logPrefix string, store storage.Store, o
 		commonBuildOptions:                      options.CommonBuildOpts,
 		defaultMountsFilePath:                   options.DefaultMountsFilePath,
 		iidfile:                                 options.IIDFile,
+		buildIDFile:                             options.BuildIDFile,
 		squash:                                  options.Squash,
 		labels:                                  slices.Clone(options.Labels),
 		layerLabels:                             slices.Clone(options.LayerLabels),
 		processLabel:                            processLabel,
 		mountLabel:                              mountLabel,
 		annotations:                             slices.Clone(options.Annotations),
 		layers:                                  options.Layers,
+		cacheStages:                             options.CacheStages,
+		stageLabels:                             options.StageLabels,
+		buildID:                                 buildID,
+		intermediateStageParents:                make(map[string]struct{}),
 		noHostname:                              options.CommonBuildOpts.NoHostname,
 		noHosts:                                 options.CommonBuildOpts.NoHosts,
 		useCache:                                !options.NoCache,
@@ -840,6 +864,12 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 									currentStageInfo.Needs = append(currentStageInfo.Needs, baseWithArg)
 								}
 							}
+							// Track if this base is an intermediate stage used by another intermediate stage
+							if stageIndex < len(stages)-1 {
+								b.intermediateStageParents[baseWithArg] = struct{}{}
+								logrus.Debugf("stage %d (%s) uses stage %q as base - marking %q as intermediate parent",
+									stageIndex, stage.Name, baseWithArg, baseWithArg)
+							}
 						}
 					}
 				case "ADD", "COPY":
@@ -1038,9 +1068,10 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 			// We're not populating the cache with intermediate
 			// images, so add this one to the list of images that
 			// we'll remove later.
-			// Only remove intermediate image is `--layers` is not provided
-			// or following stage was not only a base image ( i.e a different image ).
-			if !b.layers && !r.OnlyBaseImage {
+			// Only remove intermediate image if `--layers` is not provided,
+			// `--cache-stages` is not enabled, or following stage was not
+			// only a base image (i.e. a different image).
+			if !b.layers && !b.cacheStages && !r.OnlyBaseImage {
 				cleanupImages = append(cleanupImages, r.ImageID)
 			}
 		}

imagebuildah/stage_executor.go

@@ -81,6 +81,7 @@ type stageExecutor struct {
 	argsFromContainerfile []string
 	hasLink               bool
 	isLastStep            bool
+	fromName              string // original FROM value (stage name or image name) before resolution to image ID
 }
 
 // Preserve informs the stage executor that from this point on, it needs to
@@ -978,6 +979,14 @@ func (s *stageExecutor) prepare(ctx context.Context, from string, initializeIBCo
 		}
 		from = base
 	}
+	// Store the original FROM value (stage name or image name) before resolution to image ID.
+	// This is needed for detecting transitive aliases when setting stage labels.
+	// Only set it on the first prepare call (when initializeIBConfig=true) to avoid
+	// overwriting with image IDs from subsequent rebasing operations.
+	if initializeIBConfig && rebase && s.fromName == "" {
+		logrus.Debugf("Setting fromName for stage %q (index %d): from=%q", s.name, s.index, from)
+		s.fromName = from
+	}
 	sanitizedFrom, err := s.sanitizeFrom(from, tmpdir.GetTempDir())
 	if err != nil {
 		return nil, fmt.Errorf("invalid base image specification %q: %w", from, err)
@@ -1221,6 +1230,11 @@ func (s *stageExecutor) execute(ctx context.Context, base string) (imgID string,
 		return "", nil, false, err
 	}
 	pullPolicy := s.executor.pullPolicy
+	// Save the original base name before it might get replaced with an image ID.
+	// This is needed for detecting transitive aliases when setting stage labels.
+	if s.fromName == "" {
+		s.fromName = base
+	}
 	s.executor.stagesLock.Lock()
 	var preserveBaseImageAnnotationsAtStageStart bool
 	if stageImage, isPreviousStage := s.executor.imageMap[base]; isPreviousStage {
@@ -1837,6 +1851,27 @@ func (s *stageExecutor) execute(ctx context.Context, base string) (imgID string,
 		s.hasLink = false
 	}
 
+	// If --cache-stages is enabled and this is not the last stage, commit the intermediate stage image.
+	// However, skip committing if this stage is a "parent" stage used as a base
+	// by another intermediate stage (transitive alias pattern).
+	// Only commit the final stage in a transitive alias chain.
+	if s.executor.cacheStages && !lastStage {
+		// Check if this stage is used as base by another intermediate stage
+		_, isParentStage := s.executor.intermediateStageParents[s.name]
+		if isParentStage {
+			logrus.Debugf("Skipping commit for intermediate stage %s (index %d) - used as base by another intermediate stage", s.name, s.index)
+		} else {
+			logrus.Debugf("Committing intermediate stage %s (index %d) for --cache-stages", s.name, s.index)
+			createdBy := fmt.Sprintf("/bin/sh -c #(nop) STAGE %s", s.name)
+			// Commit the stage without squashing, using empty output name (intermediate image)
+			imgID, commitResults, err = s.commit(ctx, createdBy, false, "", false, false)
+			if err != nil {
+				return "", nil, false, fmt.Errorf("committing intermediate stage %s: %w", s.name, err)
+			}
+			logrus.Debugf("Committed intermediate stage %s with ID %s", s.name, imgID)
+		}
+	}
+
 	return imgID, commitResults, onlyBaseImage, nil
 }
 
@@ -2548,6 +2583,23 @@ func (s *stageExecutor) commit(ctx context.Context, createdBy string, emptyLayer
 	for k, v := range config.Labels {
 		s.builder.SetLabel(k, v)
 	}
+	// Add stage metadata labels if --cache-stages and --stage-labels are enabled.
+	// IMPORTANT: This must be done AFTER copying config.Labels to ensure stage labels
+	// are not overwritten by inherited labels from parent stages (transitive aliases).
+	if output == "" && s.executor.cacheStages && s.executor.stageLabels {
+		s.builder.SetLabel("io.buildah.stage.name", s.name)
+		s.builder.SetLabel("io.buildah.stage.base", s.builder.FromImage)
+
+		// Check if the base is another stage (transitive alias) using the original FROM value.
+		// s.fromName contains the stage name before resolution to image ID.
+		if s.fromName != "" && s.executor.stages[s.fromName] != nil {
+			s.builder.SetLabel("io.buildah.stage.parent_name", s.fromName)
+		}
+
+		if s.executor.buildID != "" {
+			s.builder.SetLabel("io.buildah.build.id", s.executor.buildID)
+		}
+	}
 	switch s.executor.commonBuildOptions.IdentityLabel {
 	case types.OptionalBoolTrue:
 		s.builder.SetLabel(buildah.BuilderIdentityAnnotation, define.Version)

pkg/cli/build.go

@@ -222,6 +222,14 @@ func GenBuildOptions(c *cobra.Command, inputArgs []string, iopts BuildOptions) (
 		return options, nil, nil, errors.New("'rm' and 'force-rm' can only be set with either 'layers' or 'no-cache'")
 	}
 
+	if iopts.StageLabels && !iopts.CacheStages {
+		return options, nil, nil, errors.New("'stage-labels' requires 'cache-stages'")
+	}
+
+	if iopts.BuildIdFile != "" && !iopts.StageLabels {
+		return options, nil, nil, errors.New("'build-id-file' requires 'stage-labels'")
+	}
+
 	if c.Flag("compress").Changed {
 		logrus.Debugf("--compress option specified but is ignored")
 	}
@@ -408,6 +416,7 @@ func GenBuildOptions(c *cobra.Command, inputArgs []string, iopts BuildOptions) (
 		GroupAdd:                iopts.GroupAdd,
 		IDMappingOptions:        idmappingOptions,
 		IIDFile:                 iopts.Iidfile,
+		BuildIDFile:             iopts.BuildIdFile,
 		IgnoreFile:              iopts.IgnoreFile,
 		In:                      stdin,
 		InheritLabels:           inheritLabels,
@@ -417,6 +426,8 @@ func GenBuildOptions(c *cobra.Command, inputArgs []string, iopts BuildOptions) (
 		Labels:                  iopts.Label,
 		LayerLabels:             iopts.LayerLabel,
 		Layers:                  layers,
+		CacheStages:             iopts.CacheStages,
+		StageLabels:             iopts.StageLabels,
 		LogFile:                 iopts.Logfile,
 		LogRusage:               iopts.LogRusage,
 		LogSplitByPlatform:      iopts.LogSplitByPlatform,

pkg/cli/common.go

@@ -26,8 +26,10 @@ import (
 
 // LayerResults represents the results of the layer flags
 type LayerResults struct {
-	ForceRm bool
-	Layers  bool
+	ForceRm     bool
+	Layers      bool
+	CacheStages bool
+	StageLabels bool
 }
 
 // UserNSResults represents the results for the UserNS flags
@@ -73,6 +75,7 @@ type BudResults struct {
 	Format              string
 	From                string
 	Iidfile             string
+	BuildIdFile         string
 	InheritLabels       bool
 	InheritAnnotations  bool
 	Label               []string
@@ -217,6 +220,8 @@ func GetLayerFlags(flags *LayerResults) pflag.FlagSet {
 	fs := pflag.FlagSet{}
 	fs.BoolVar(&flags.ForceRm, "force-rm", false, "always remove intermediate containers after a build, even if the build is unsuccessful.")
 	fs.BoolVar(&flags.Layers, "layers", UseLayers(), "use intermediate layers during build. Use BUILDAH_LAYERS environment variable to override.")
+	fs.BoolVar(&flags.CacheStages, "cache-stages", false, "preserve intermediate stage images.")
+	fs.BoolVar(&flags.StageLabels, "stage-labels", false, "add metadata labels to intermediate stage images (requires --cache-stages).")
 	return fs
 }
 
@@ -253,6 +258,7 @@ func GetBudFlags(flags *BudResults) pflag.FlagSet {
 	fs.StringSliceVarP(&flags.File, "file", "f", []string{}, "`pathname or URL` of a Dockerfile")
 	fs.StringVar(&flags.Format, "format", DefaultFormat(), "`format` of the built image's manifest and metadata. Use BUILDAH_FORMAT environment variable to override.")
 	fs.StringVar(&flags.Iidfile, "iidfile", "", "`file` to write the image ID to")
+	fs.StringVar(&flags.BuildIdFile, "build-id-file", "", "`file` to write the build ID to")
 	fs.IntVar(&flags.Jobs, "jobs", 1, "how many stages to run in parallel")
 	fs.StringArrayVar(&flags.Label, "label", []string{}, "set metadata for an image (default [])")
 	fs.StringArrayVar(&flags.LayerLabel, "layer-label", []string{}, "set metadata for an intermediate image (default [])")
@@ -357,6 +363,7 @@ func GetBudFlagsCompletions() commonComp.FlagCompletions {
 	flagCompletion["hooks-dir"] = commonComp.AutocompleteNone
 	flagCompletion["ignorefile"] = commonComp.AutocompleteDefault
 	flagCompletion["iidfile"] = commonComp.AutocompleteDefault
+	flagCompletion["build-id-file"] = commonComp.AutocompleteDefault
 	flagCompletion["jobs"] = commonComp.AutocompleteNone
 	flagCompletion["label"] = commonComp.AutocompleteNone
 	flagCompletion["layer-label"] = commonComp.AutocompleteNone