Add --metadata-file

Add a MetadataFile field to BuildOptions, to which we write a dictionary
of information about a just-committed image.

Pay more attention to sourceDateEpoch than to timestamp when we're
tagging an existing image with the intended destination name.

Signed-off-by: Nalin Dahyabhai <[email protected]>

Author: nalind

cmd/buildah/commit.go

@@ -69,6 +69,7 @@ type commitInputOptions struct {
 	unsetAnnotation    []string
 	annotation         []string
 	createdAnnotation  bool
+	metadataFile       string
 }
 
 func init() {
@@ -123,6 +124,9 @@ func commitListFlagSet(cmd *cobra.Command, opts *commitInputOptions) {
 	_ = cmd.RegisterFlagCompletionFunc("manifest", completion.AutocompleteNone)
 	flags.StringVar(&opts.iidfile, "iidfile", "", "write the image ID to the file")
 	_ = cmd.RegisterFlagCompletionFunc("iidfile", completion.AutocompleteDefault)
+	flags.StringVar(&opts.metadataFile, "metadata-file", "", "`file` to write metadata about the image to")
+	_ = cmd.RegisterFlagCompletionFunc("metadata-file", completion.AutocompleteDefault)
+
 	flags.BoolVar(&opts.omitTimestamp, "omit-timestamp", false, "set created timestamp to epoch 0 to allow for deterministic builds")
 	sourceDateEpochUsageDefault := "current time"
 	if v := os.Getenv(internal.SourceDateEpochName); v != "" {
@@ -401,10 +405,12 @@ func commitCmd(c *cobra.Command, args []string, iopts commitInputOptions) error
 	if !iopts.quiet {
 		options.ReportWriter = os.Stderr
 	}
-	id, ref, _, err := builder.Commit(ctx, dest, options)
+	results, err := builder.CommitResults(ctx, dest, options)
 	if err != nil {
 		return util.GetFailureCause(err, fmt.Errorf("committing container %q to %q: %w", builder.Container, image, err))
 	}
+	ref := results.Canonical
+	id := results.ImageID
 	if ref != nil && id != "" {
 		logrus.Debugf("wrote image %s with ID %s", ref, id)
 	} else if ref != nil {
@@ -417,6 +423,15 @@ func commitCmd(c *cobra.Command, args []string, iopts commitInputOptions) error
 	if options.IIDFile == "" && id != "" {
 		fmt.Printf("%s\n", id)
 	}
+	if iopts.metadataFile != "" {
+		metadataBytes, err := json.Marshal(results.Metadata)
+		if err != nil {
+			return fmt.Errorf("encoding contents for %q: %w", iopts.metadataFile, err)
+		}
+		if err := os.WriteFile(iopts.metadataFile, metadataBytes, 0o644); err != nil {
+			return err
+		}
+	}
 
 	if iopts.rm {
 		return builder.Delete()

commit.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/containers/buildah/internal/metadata"
 	"github.com/containers/buildah/pkg/blobcache"
 	"github.com/containers/buildah/util"
 	encconfig "github.com/containers/ocicrypt/config"
@@ -76,7 +77,8 @@ type CommitOptions struct {
 	// github.com/containers/image/types SystemContext to hold credentials
 	// and other authentication/authorization information.
 	SystemContext *types.SystemContext
-	// IIDFile tells the builder to write the image ID to the specified file
+	// IIDFile tells the builder to write the image's ID, preceded by
+	// "sha256:", to the specified file.
 	IIDFile string
 	// Squash tells the builder to produce an image with a single layer
 	// instead of with possibly more than one layer.
@@ -308,9 +310,10 @@ func (b *Builder) addManifest(ctx context.Context, manifestName string, imageSpe
 type CommitResults struct {
 	ImageID       string              // a local image ID, or part of the digest of the image's config blob
 	Canonical     reference.Canonical // set if destination included a DockerReference
-	MediaType     string              // always returned
-	ImageManifest []byte              // always returned
-	Digest        digest.Digest       // always returned
+	MediaType     string              // image manifest MIME type, always returned
+	ImageManifest []byte              // raw image manifest, always returned
+	Digest        digest.Digest       // digest of the manifest, always returned
+	Metadata      map[string]any      // always returned, format is flexible
 }
 
 // Commit writes the contents of the container, along with its updated
@@ -555,13 +558,13 @@ func (b *Builder) CommitResults(ctx context.Context, dest types.ImageReference,
 	if err != nil {
 		return nil, fmt.Errorf("computing digest of manifest of new image %q: %w", transports.ImageName(dest), err)
 	}
-	if imgID == "" {
-		parsedManifest, err := manifest.FromBlob(manifestBytes, manifest.GuessMIMEType(manifestBytes))
-		if err != nil {
-			return nil, fmt.Errorf("parsing written manifest to determine the image's ID: %w", err)
-		}
-		configInfo := parsedManifest.ConfigInfo()
-		if configInfo.Size > 2 && configInfo.Digest.Validate() == nil { // don't be returning a digest of "" or "{}"
+	parsedManifest, err := manifest.FromBlob(manifestBytes, manifest.GuessMIMEType(manifestBytes))
+	if err != nil {
+		return nil, fmt.Errorf("parsing written manifest to determine the image's ID: %w", err)
+	}
+	configInfo := parsedManifest.ConfigInfo()
+	if configInfo.Size > 2 && configInfo.Digest.Validate() == nil { // don't be returning a digest of "" or "{}"
+		if imgID == "" {
 			imgID = configInfo.Digest.Encoded()
 		}
 	}
@@ -582,12 +585,23 @@ func (b *Builder) CommitResults(ctx context.Context, dest types.ImageReference,
 		logrus.Debugf("added imgID %s to manifestID %s", imgID, manifestID)
 	}
 
+	descriptor := v1.Descriptor{
+		MediaType: manifest.GuessMIMEType(manifestBytes),
+		Digest:    manifestDigest,
+		Size:      int64(len(manifestBytes)),
+	}
+	metadata, err := metadata.Build(configInfo.Digest, descriptor)
+	if err != nil {
+		return nil, fmt.Errorf("building metadata map for image: %w", err)
+	}
+
 	results := CommitResults{
 		ImageID:       imgID,
 		Canonical:     ref,
-		MediaType:     manifest.GuessMIMEType(manifestBytes),
+		MediaType:     descriptor.MediaType,
 		ImageManifest: manifestBytes,
 		Digest:        manifestDigest,
+		Metadata:      metadata,
 	}
 	return &results, nil
 }

define/build.go

@@ -418,4 +418,7 @@ type BuildOptions struct {
 	// CreatedAnnotation controls whether or not an "org.opencontainers.image.created"
 	// annotation is present in the output image.
 	CreatedAnnotation types.OptionalBool
+	// MetadataFile is the name of a file to which the builder should write a JSON map
+	// containing metadata about the built image.
+	MetadataFile string
 }

docker/types.go

@@ -257,3 +257,10 @@ type V2S2Manifest struct {
 	// configuration.
 	Layers []V2S2Descriptor `json:"layers"`
 }
+
+const (
+	// github.com/moby/buildkit/exporter/containerimage/exptypes/types.go
+	ExporterImageDigestKey       = "containerimage.digest"
+	ExporterImageConfigDigestKey = "containerimage.config.digest"
+	ExporterImageDescriptorKey   = "containerimage.descriptor"
+)

docs/buildah-build.1.md

@@ -625,6 +625,12 @@ The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
 `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a
 unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
 
+**--metadata-file** *MetadataFile*
+
+Write information about the built image to the named file.  When `--platform`
+is specified more than once, attempting to use this option will trigger an
+error.
+
 **--network**, **--net**=*mode*
 
 Sets the configuration for network namespaces when handling `RUN` instructions.

docs/buildah-commit.1.md

@@ -176,6 +176,10 @@ Write the image ID to the file.
 Name of the manifest list to which the built image will be added. Creates the manifest list
 if it does not exist. This option is useful for building multi architecture images.
 
+**--metadata-file** *MetadataFile*
+
+Write information about the committed image to the named file.
+
 **--omit-history** *bool-value*
 
 Omit build history information in the built image. (default false).

imagebuildah/build.go

@@ -86,6 +86,9 @@ func BuildDockerfiles(ctx context.Context, store storage.Store, options define.B
 	if len(options.Platforms) > 1 && options.IIDFile != "" {
 		return "", nil, fmt.Errorf("building multiple images, but iidfile %q can only be used to store one image ID", options.IIDFile)
 	}
+	if len(options.Platforms) > 1 && options.MetadataFile != "" {
+		return "", nil, fmt.Errorf("building multiple images, but metadata file %q can only be used to store information about one image", options.MetadataFile)
+	}
 
 	logger := logrus.New()
 	if options.Err != nil {

imagebuildah/executor.go

@@ -2,6 +2,7 @@ package imagebuildah
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -15,6 +16,7 @@ import (
 	"github.com/containers/buildah"
 	"github.com/containers/buildah/define"
 	"github.com/containers/buildah/internal"
+	"github.com/containers/buildah/internal/metadata"
 	internalUtil "github.com/containers/buildah/internal/util"
 	"github.com/containers/buildah/pkg/parse"
 	"github.com/containers/buildah/pkg/sshagent"
@@ -172,6 +174,7 @@ type executor struct {
 	sourceDateEpoch                         *time.Time
 	rewriteTimestamp                        bool
 	createdAnnotation                       types.OptionalBool
+	metadataFile                            string
 }
 
 type imageTypeAndHistoryAndDiffIDs struct {
@@ -346,6 +349,7 @@ func newExecutor(logger *logrus.Logger, logPrefix string, store storage.Store, o
 		sourceDateEpoch:                         options.SourceDateEpoch,
 		rewriteTimestamp:                        options.RewriteTimestamp,
 		createdAnnotation:                       options.CreatedAnnotation,
+		metadataFile:                            options.MetadataFile,
 	}
 	// sort unsetAnnotations because we will later write these
 	// values to the history of the image therefore we want to
@@ -519,7 +523,7 @@ func (b *executor) getImageTypeAndHistoryAndDiffIDs(ctx context.Context, imageID
 	return oci.OS, oci.Architecture, manifestFormat, oci.History, oci.RootFS.DiffIDs, nil
 }
 
-func (b *executor) buildStage(ctx context.Context, cleanupStages map[int]*stageExecutor, stages imagebuilder.Stages, stageIndex int) (imageID string, ref reference.Canonical, onlyBaseImage bool, err error) {
+func (b *executor) buildStage(ctx context.Context, cleanupStages map[int]*stageExecutor, stages imagebuilder.Stages, stageIndex int) (imageID string, commitResults *buildah.CommitResults, onlyBaseImage bool, err error) {
 	stage := stages[stageIndex]
 	ib := stage.Builder
 	node := stage.Node
@@ -616,7 +620,7 @@ func (b *executor) buildStage(ctx context.Context, cleanupStages map[int]*stageE
 	}
 
 	// Build this stage.
-	if imageID, ref, onlyBaseImage, err = stageExecutor.execute(ctx, base); err != nil {
+	if imageID, commitResults, onlyBaseImage, err = stageExecutor.execute(ctx, base); err != nil {
 		return "", nil, onlyBaseImage, err
 	}
 
@@ -630,7 +634,7 @@ func (b *executor) buildStage(ctx context.Context, cleanupStages map[int]*stageE
 		b.stagesLock.Unlock()
 	}
 
-	return imageID, ref, onlyBaseImage, nil
+	return imageID, commitResults, onlyBaseImage, nil
 }
 
 type stageDependencyInfo struct {
@@ -922,7 +926,7 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 		Index         int
 		ImageID       string
 		OnlyBaseImage bool
-		Ref           reference.Canonical
+		CommitResults buildah.CommitResults
 		Error         error
 	}
 
@@ -935,6 +939,7 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 	var wg sync.WaitGroup
 	wg.Add(len(stages))
 
+	var commitResults buildah.CommitResults
 	go func() {
 		cancel := false
 		for stageIndex := range stages {
@@ -983,7 +988,7 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 						return
 					}
 				}
-				stageID, stageRef, stageOnlyBaseImage, stageErr := b.buildStage(ctx, cleanupStages, stages, index)
+				stageID, stageResults, stageOnlyBaseImage, stageErr := b.buildStage(ctx, cleanupStages, stages, index)
 				if stageErr != nil {
 					cancel = true
 					ch <- Result{
@@ -997,7 +1002,7 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 				ch <- Result{
 					Index:         index,
 					ImageID:       stageID,
-					Ref:           stageRef,
+					CommitResults: *stageResults,
 					OnlyBaseImage: stageOnlyBaseImage,
 					Error:         nil,
 				}
@@ -1037,7 +1042,8 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 		}
 		if r.Index == len(stages)-1 {
 			imageID = r.ImageID
-			ref = r.Ref
+			commitResults = r.CommitResults
+			ref = commitResults.Canonical
 		}
 		b.stagesLock.Unlock()
 	}
@@ -1088,7 +1094,11 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 	if b.iidfile != "" {
 		iid := imageID
 		if iid != "" {
-			iid = "sha256:" + iid // only prepend a digest algorithm name if we actually got a value back
+			cdigest, err := digest.Parse("sha256:" + imageID)
+			if err != nil {
+				return imageID, ref, fmt.Errorf("coercing image ID into a digest structure: %w", err)
+			}
+			iid = cdigest.String()
 		}
 		if err = os.WriteFile(b.iidfile, []byte(iid), 0o644); err != nil {
 			return imageID, ref, fmt.Errorf("failed to write image ID to file %q: %w", b.iidfile, err)
@@ -1098,6 +1108,29 @@ func (b *executor) Build(ctx context.Context, stages imagebuilder.Stages) (image
 			return imageID, ref, fmt.Errorf("failed to write image ID to stdout: %w", err)
 		}
 	}
+	if b.metadataFile != "" {
+		var cdigest digest.Digest
+		if imageID != "" {
+			if cdigest, err = digest.Parse("sha256:" + imageID); err != nil {
+				return imageID, ref, fmt.Errorf("coercing image ID into a digest structure: %w", err)
+			}
+		}
+		metadata, err := metadata.Build(cdigest, v1.Descriptor{
+			MediaType: commitResults.MediaType,
+			Digest:    commitResults.Digest,
+			Size:      int64(len(commitResults.ImageManifest)),
+		})
+		if err != nil {
+			return imageID, ref, fmt.Errorf("building metadata for metadata file: %w", err)
+		}
+		metadataBytes, err := json.Marshal(metadata)
+		if err != nil {
+			return imageID, ref, fmt.Errorf("encoding metadata for metadata file: %w", err)
+		}
+		if err = os.WriteFile(b.metadataFile, metadataBytes, 0o644); err != nil {
+			return imageID, ref, fmt.Errorf("failed to write image metadata to file %q: %w", b.metadataFile, err)
+		}
+	}
 	return imageID, ref, nil
 }