diff --git a/docs/source/markdown/options/created-annotation.md b/docs/source/markdown/options/created-annotation.md new file mode 100644 index 0000000000..755bd33a07 --- /dev/null +++ b/docs/source/markdown/options/created-annotation.md @@ -0,0 +1,13 @@ +####> This option file is used in: +####> podman build, farm build +####> If file is edited, make sure the changes +####> are applicable to all of those. +#### **--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. diff --git a/docs/source/markdown/options/inherit-annotations.md b/docs/source/markdown/options/inherit-annotations.md new file mode 100644 index 0000000000..5e329541a6 --- /dev/null +++ b/docs/source/markdown/options/inherit-annotations.md @@ -0,0 +1,9 @@ +####> This option file is used in: +####> podman build, farm build +####> If file is edited, make sure the changes +####> are applicable to all of those. +#### **--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. diff --git a/docs/source/markdown/options/rewrite-timestamp.md b/docs/source/markdown/options/rewrite-timestamp.md new file mode 100644 index 0000000000..7d2269a256 --- /dev/null +++ b/docs/source/markdown/options/rewrite-timestamp.md @@ -0,0 +1,10 @@ +####> This option file is used in: +####> podman build, farm build +####> If file is edited, make sure the changes +####> are applicable to all of those. +#### **--rewrite-timestamp** + +When generating new layers for the image, ensure that no newly added content +bears a timestamp later than the value used by the **--source-date-epoch** +flag, if one was provided, by replacing any timestamps which are later than +that value, with that value. diff --git a/docs/source/markdown/options/source-date-epoch.md b/docs/source/markdown/options/source-date-epoch.md new file mode 100644 index 0000000000..a3b6334208 --- /dev/null +++ b/docs/source/markdown/options/source-date-epoch.md @@ -0,0 +1,28 @@ +####> This option file is used in: +####> podman build, farm build +####> If file is edited, make sure the changes +####> are applicable to all of those. +#### **--source-date-epoch**=*seconds* + +Set the "created" timestamp for the built image to this number of seconds since +the epoch (Unix time 0, i.e., 00:00:00 UTC on 1 January 1970) (default is to +use the value set in the `SOURCE_DATE_EPOCH` environment variable, or the +current time if it is not set). + +The "created" timestamp is written into the image's configuration and manifest +when the image is committed, so running the same build two different times +will ordinarily produce images with different sha256 hashes, even if no other +changes were made to the Containerfile and build context. + +When this flag is set, a `SOURCE_DATE_EPOCH` build arg will provide its value +for a stage in which it is declared. + +When this flag is set, the image configuration's "created" timestamp is always +set to the time specified, which should allow for identical images to be built +at different times using the same set of inputs. + +When this flag is set, output written as specified to the **--output** flag +will bear exactly the specified timestamp. + +Conflicts with the similar **--timestamp** flag, which also sets its specified +time on the contents of new layers. diff --git a/docs/source/markdown/options/unsetannotation.md b/docs/source/markdown/options/unsetannotation.md new file mode 100644 index 0000000000..7e0dd44c69 --- /dev/null +++ b/docs/source/markdown/options/unsetannotation.md @@ -0,0 +1,7 @@ +####> This option file is used in: +####> podman build, farm build +####> If file is edited, make sure the changes +####> are applicable to all of those. +#### **--unsetannotation**=*annotation* + +Unset the image annotation, causing the annotation not to be inherited from the base image. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index 110927e65b..43b544bcf5 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -111,6 +111,8 @@ Thus, compressing the data before sending it is irrelevant to Podman. (This opti @@option cpuset-mems +@@option created-annotation + @@option creds #### **--cw**=*options* @@ -221,6 +223,8 @@ It does not affect _/etc/resolv.conf_ in the final image. @@option iidfile +@@option inherit-annotations + @@option inherit-labels @@option ipc.image @@ -324,6 +328,8 @@ the help of emulation provided by packages like `qemu-user-static`. @@option retry-delay +@@option rewrite-timestamp + @@option rm @@option runtime @@ -433,6 +439,8 @@ Sign the image using a GPG key with the specified FINGERPRINT. (This option is n @@option skip-unused-stages +@@option source-date-epoch + @@option squash @@option squash-all @@ -455,6 +463,8 @@ Use --stdin to be able to interact from the terminal during the build. @@option ulimit.image +@@option unsetannotation + @@option unsetenv.image @@option unsetlabel diff --git a/docs/source/markdown/podman-farm-build.1.md.in b/docs/source/markdown/podman-farm-build.1.md.in index 41f52d7ba7..a16e2ea422 100644 --- a/docs/source/markdown/podman-farm-build.1.md.in +++ b/docs/source/markdown/podman-farm-build.1.md.in @@ -71,6 +71,8 @@ Remove built images from farm nodes on success (Default: false). @@option cpuset-mems +@@option created-annotation + @@option creds @@option decryption-key @@ -123,6 +125,8 @@ This option specifies the name of the farm to be used in the build process. @@option iidfile +@@option inherit-annotations + @@option inherit-labels @@option ipc.image @@ -177,6 +181,8 @@ Build only on farm nodes that match the given platforms. @@option retry-delay +@@option rewrite-timestamp + @@option rm @@option runtime @@ -207,6 +213,8 @@ Build only on farm nodes that match the given platforms. @@option skip-unused-stages +@@option source-date-epoch + @@option squash @@option squash-all @@ -223,6 +231,8 @@ Build only on farm nodes that match the given platforms. @@option ulimit.image +@@option unsetannotation + @@option unsetenv.image @@option unsetlabel