Merge pull request containers#6239 from nalind/oci-created-annotation

build, commit: set the OCI ...created annotation on OCI images

Author: openshift-merge-bot[bot]

cmd/buildah/commit.go

@@ -66,6 +66,9 @@ type commitInputOptions struct {
 	encryptLayers      []int
 	unsetenvs          []string
 	addFile            []string
+	unsetAnnotation    []string
+	annotation         []string
+	createdAnnotation  bool
 }
 
 func init() {
@@ -187,6 +190,11 @@ func commitListFlagSet(cmd *cobra.Command, opts *commitInputOptions) {
 
 	flags.StringSliceVar(&opts.unsetenvs, "unsetenv", nil, "unset env from final image")
 	_ = cmd.RegisterFlagCompletionFunc("unsetenv", completion.AutocompleteNone)
+	flags.StringSliceVar(&opts.unsetAnnotation, "unsetannotation", nil, "unset annotation when inheriting annotations from base image")
+	_ = cmd.RegisterFlagCompletionFunc("unsetannotation", completion.AutocompleteNone)
+	flags.StringArrayVar(&opts.annotation, "annotation", []string{}, "set metadata for an image (default [])")
+	_ = cmd.RegisterFlagCompletionFunc("annotation", completion.AutocompleteNone)
+	flags.BoolVar(&opts.createdAnnotation, "created-annotation", true, `set an "org.opencontainers.image.created" annotation in the image`)
 }
 
 func commitCmd(c *cobra.Command, args []string, iopts commitInputOptions) error {
@@ -311,6 +319,9 @@ func commitCmd(c *cobra.Command, args []string, iopts commitInputOptions) error
 		OverrideChanges:       iopts.changes,
 		OverrideConfig:        overrideConfig,
 		ExtraImageContent:     addFiles,
+		UnsetAnnotations:      iopts.unsetAnnotation,
+		Annotations:           iopts.annotation,
+		CreatedAnnotation:     types.NewOptionalBool(iopts.createdAnnotation),
 	}
 	exclusiveFlags := 0
 	if c.Flag("reference-time").Changed {

commit.go

@@ -104,7 +104,8 @@ type CommitOptions struct {
 	OmitLayerHistoryEntry bool
 	// OmitTimestamp forces epoch 0 as created timestamp to allow for
 	// deterministic, content-addressable builds.
-	// Deprecated use HistoryTimestamp instead.
+	// Deprecated: use HistoryTimestamp or SourceDateEpoch (possibly with
+	// RewriteTimestamp) instead.
 	OmitTimestamp bool
 	// SignBy is the fingerprint of a GPG key to use for signing the image.
 	SignBy string
@@ -130,7 +131,8 @@ type CommitOptions struct {
 	// contents of a rootfs.
 	ConfidentialWorkloadOptions ConfidentialWorkloadOptions
 	// UnsetEnvs is a list of environments to not add to final image.
-	// Deprecated: use UnsetEnv() before committing instead.
+	// Deprecated: use UnsetEnv() before committing, or set OverrideChanges
+	// instead.
 	UnsetEnvs []string
 	// OverrideConfig is an optional Schema2Config which can override parts
 	// of the working container's configuration for the image that is being
@@ -167,6 +169,15 @@ type CommitOptions struct {
 	// corresponding members in the Builder object, in the committed image
 	// is not guaranteed.
 	PrependedLinkedLayers, AppendedLinkedLayers []LinkedLayer
+	// UnsetAnnotations is a list of annotations (names only) to withhold
+	// from the image.
+	UnsetAnnotations []string
+	// Annotations is a list of annotations (in the form "key=value") to
+	// add to the image.
+	Annotations []string
+	// CreatedAnnotation controls whether or not an "org.opencontainers.image.created"
+	// annotation is present in the output image.
+	CreatedAnnotation types.OptionalBool
 }
 
 // LinkedLayer combines a history entry with the location of either a directory

define/build.go

@@ -49,7 +49,8 @@ type CommonBuildOptions struct {
 	CPUSetMems string
 	// HTTPProxy determines whether *_proxy env vars from the build host are passed into the container.
 	HTTPProxy bool
-	// IdentityLabel if set ensures that default `io.buildah.version` label is not applied to build image.
+	// IdentityLabel if set controls whether or not a `io.buildah.version` label is added to the built image.
+	// Setting this to false does not clear the label if it would be inherited from the base image.
 	IdentityLabel types.OptionalBool
 	// Memory is the upper limit (in bytes) on how much memory running containers can use.
 	Memory int64
@@ -414,4 +415,7 @@ type BuildOptions struct {
 	CompatLayerOmissions types.OptionalBool
 	// NoPivotRoot inhibits the usage of pivot_root when setting up the rootfs
 	NoPivotRoot bool
+	// CreatedAnnotation controls whether or not an "org.opencontainers.image.created"
+	// annotation is present in the output image.
+	CreatedAnnotation types.OptionalBool
 }

docs/buildah-build.1.md

@@ -297,6 +297,16 @@ If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1`
 then processes in your container will only use memory from the first
 two memory nodes.
 
+**--created-annotation**
+
+Add an image *annotation* (see also **--annotation**) to the image metadata
+setting "org.opencontainers.image.created" to the current time, or to the
+datestamp specified to the **--source-date-epoch** or **--timestamp** flag,
+if either was used.  If *false*, no such annotation will be present in the
+written image.
+
+Note: this information is not present in Docker image formats, so it is discarded when writing images in Docker formats.
+
 **--creds** *creds*
 
 The [username[:password]] to use to authenticate with the registry if required.
@@ -508,6 +518,8 @@ than once, attempting to use this option will trigger an error.
 **--inherit-annotations** *bool-value*
 
 Inherit the annotations from the base image or base stages. (default true).
+Use cases which set this flag to *false* may need to do the same for the
+**--created-annotation** flag.
 
 **--inherit-labels** *bool-value*
 

docs/buildah-commit.1.md

@@ -29,6 +29,13 @@ will be used.  The new file will be owned by UID 0, GID 0, have 0644
 permissions, and be given the timestamp specified to the **--timestamp** option
 if it is specified.  This option can be specified multiple times.
 
+**--annotation** *annotation[=value]*
+
+Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple times.
+If *annotation* is named, but neither `=` nor a `value` is provided, then the *annotation* is set to an empty value.
+
+Note: this information is not present in Docker image formats, so it is discarded when writing images in Docker formats.
+
 **--authfile** *path*
 
 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json. See containers-auth.json(5) for more information. This file is created using `buildah login`.
@@ -55,6 +62,16 @@ Read a JSON-encoded version of an image configuration object from the specified
 file, and merge the values from it with the configuration of the image being
 committed.
 
+**--created-annotation**
+
+Add an image *annotation* (see also **--annotation**) to the image metadata
+setting "org.opencontainers.image.created" to the current time, or to the
+datestamp specified to the **--source-date-epoch** or **--timestamp** flag,
+if either was used.  If *false*, no such annotation will be present in the
+written image.
+
+Note: this information is not present in Docker image formats, so it is discarded when writing images in Docker formats.
+
 **--creds** *creds*
 
 The [username[:password]] to use to authenticate with the registry if required.
@@ -350,6 +367,10 @@ not affect the timestamps of layer contents.
 
 Require HTTPS and verification of certificates when talking to container registries (defaults to true).  TLS verification cannot be used when talking to an insecure registry.
 
+**--unsetannotation** *annotation*
+
+Unset the image annotation, causing the annotation not to be inherited from the base image.
+
 **--unsetenv** *env*
 
 Unset environment variables from the final image.

image.go

@@ -104,6 +104,9 @@ type containerImageRef struct {
 	extraImageContent     map[string]string
 	compatSetParent       types.OptionalBool
 	layerExclusions       []copier.ConditionalRemovePath
+	unsetAnnotations      []string
+	setAnnotations        []string
+	createdAnnotation     types.OptionalBool
 }
 
 type blobLayerInfo struct {
@@ -590,6 +593,23 @@ func (i *containerImageRef) newOCIManifestBuilder() (manifestBuilder, error) {
 	}
 
 	// Return partial manifest.  The Layers lists will be populated later.
+	annotations := make(map[string]string)
+	maps.Copy(annotations, i.annotations)
+	switch i.createdAnnotation {
+	case types.OptionalBoolFalse:
+		delete(annotations, v1.AnnotationCreated)
+	default:
+		fallthrough
+	case types.OptionalBoolTrue, types.OptionalBoolUndefined:
+		annotations[v1.AnnotationCreated] = created.UTC().Format(time.RFC3339Nano)
+	}
+	for _, k := range i.unsetAnnotations {
+		delete(annotations, k)
+	}
+	for _, kv := range i.setAnnotations {
+		k, v, _ := strings.Cut(kv, "=")
+		annotations[k] = v
+	}
 	return &ociManifestBuilder{
 		i: i,
 		// The default layer media type assumes no compression.
@@ -604,7 +624,7 @@ func (i *containerImageRef) newOCIManifestBuilder() (manifestBuilder, error) {
 				MediaType: v1.MediaTypeImageConfig,
 			},
 			Layers:      []v1.Descriptor{},
-			Annotations: i.annotations,
+			Annotations: annotations,
 		},
 	}, nil
 }
@@ -1525,6 +1545,8 @@ func (b *Builder) makeContainerImageRef(options CommitOptions) (*containerImageR
 		layerLatestModTime:    layerLatestModTime,
 		historyComment:        b.HistoryComment(),
 		annotations:           b.Annotations(),
+		setAnnotations:        slices.Clone(options.Annotations),
+		unsetAnnotations:      slices.Clone(options.UnsetAnnotations),
 		preferredManifestType: manifestType,
 		squash:                options.Squash,
 		confidentialWorkload:  options.ConfidentialWorkloadOptions,
@@ -1543,6 +1565,7 @@ func (b *Builder) makeContainerImageRef(options CommitOptions) (*containerImageR
 		extraImageContent:     maps.Clone(options.ExtraImageContent),
 		compatSetParent:       options.CompatSetParent,
 		layerExclusions:       layerExclusions,
+		createdAnnotation:     options.CreatedAnnotation,
 	}
 	if ref.created != nil {
 		for i := range ref.preEmptyLayers {

imagebuildah/executor.go

@@ -171,6 +171,7 @@ type Executor struct {
 	noPivotRoot                             bool
 	sourceDateEpoch                         *time.Time
 	rewriteTimestamp                        bool
+	createdAnnotation                       types.OptionalBool
 }
 
 type imageTypeAndHistoryAndDiffIDs struct {
@@ -342,6 +343,7 @@ func newExecutor(logger *logrus.Logger, logPrefix string, store storage.Store, o
 		noPivotRoot:                             options.NoPivotRoot,
 		sourceDateEpoch:                         options.SourceDateEpoch,
 		rewriteTimestamp:                        options.RewriteTimestamp,
+		createdAnnotation:                       options.CreatedAnnotation,
 	}
 	// sort unsetAnnotations because we will later write these
 	// values to the history of the image therefore we want to

imagebuildah/stage_executor.go

@@ -2505,6 +2505,9 @@ func (s *StageExecutor) commit(ctx context.Context, createdBy string, emptyLayer
 		SourceDateEpoch:       s.executor.sourceDateEpoch,
 		RewriteTimestamp:      s.executor.rewriteTimestamp,
 		CompatLayerOmissions:  s.executor.compatLayerOmissions,
+		UnsetAnnotations:      s.executor.unsetAnnotations,
+		Annotations:           s.executor.annotations,
+		CreatedAnnotation:     s.executor.createdAnnotation,
 	}
 	if finalInstruction {
 		options.ConfidentialWorkloadOptions = s.executor.confidentialWorkload

pkg/cli/build.go

@@ -378,6 +378,7 @@ func GenBuildOptions(c *cobra.Command, inputArgs []string, iopts BuildOptions) (
 		Compression:             compression,
 		ConfigureNetwork:        networkPolicy,
 		ContextDirectory:        contextDir,
+		CreatedAnnotation:       types.NewOptionalBool(iopts.CreatedAnnotation),
 		Devices:                 iopts.Devices,
 		DropCapabilities:        iopts.CapDrop,
 		Err:                     stderr,

pkg/cli/common.go

@@ -127,6 +127,7 @@ type BudResults struct {
 	CompatVolumes       bool
 	SourceDateEpoch     string
 	RewriteTimestamp    bool
+	CreatedAnnotation   bool
 }
 
 // FromAndBugResults represents the results for common flags
@@ -240,6 +241,7 @@ func GetBudFlags(flags *BudResults) pflag.FlagSet {
 	fs.BoolVar(&flags.InheritLabels, "inherit-labels", true, "inherit the labels from the base image or base stages.")
 	fs.BoolVar(&flags.InheritAnnotations, "inherit-annotations", true, "inherit the annotations from the base image or base stages.")
 	fs.StringArrayVar(&flags.CPPFlags, "cpp-flag", []string{}, "set additional flag to pass to C preprocessor (cpp)")
+	fs.BoolVar(&flags.CreatedAnnotation, "created-annotation", true, `set an "org.opencontainers.image.created" annotation in the image`)
 	fs.StringVar(&flags.Creds, "creds", "", "use `[username[:password]]` for accessing the registry")
 	fs.StringVarP(&flags.CWOptions, "cw", "", "", "confidential workload `options`")
 	fs.BoolVarP(&flags.DisableCompression, "disable-compression", "D", true, "don't compress layers by default")
@@ -326,7 +328,7 @@ newer:   only pull base and SBOM scanner images when newer images exist on the r
 	fs.String("variant", "", "override the `variant` of the specified image")
 	fs.StringSliceVar(&flags.UnsetEnvs, "unsetenv", nil, "unset environment variable from final image")
 	fs.StringSliceVar(&flags.UnsetLabels, "unsetlabel", nil, "unset label when inheriting labels from base image")
-	fs.StringSliceVar(&flags.UnsetAnnotations, "unsetannotation", nil, "unset annotation when inheriting annotation from base image")
+	fs.StringSliceVar(&flags.UnsetAnnotations, "unsetannotation", nil, "unset annotation when inheriting annotations from base image")
 	return fs
 }