Add output timestamp field in API

Ref: https://github.com/shipwright-io/community/blob/main/ships/0037-build-output-timestamp.md Add optional output image timestamp field to allow for setting a custom image creation timestamp.
shipwright-io · Mar 1, 2024 · 9e3c444 · 9e3c444
1 parent 67a0a7e
commit 9e3c444
Show file tree

Hide file tree

Showing 8 changed files with 137 additions and 0 deletions.
diff --git a/deploy/crds/shipwright.io_buildruns.yaml b/deploy/crds/shipwright.io_buildruns.yaml
@@ -114,6 +114,15 @@ spec:
                         description: Labels references the additional labels to be
                           applied on the image
                         type: object
+                      timestamp:
+                        description: 'Timestamp references the optional image timestamp
+                          to be set, valid values are: - "Zero", to set 00:00:00 UTC
+                          on 1 January 1970 - "SourceTimestamp", to set the source
+                          timestamp dereived from the input source - "BuildTimestamp",
+                          to set the timestamp of the current build itself - Parsable
+                          integer number defined as the epoch seconds - or nil/empty
+                          to not set any specific timestamp'
+                        type: string
                     required:
                     - image
                     type: object
@@ -272,6 +281,15 @@ spec:
                         description: Labels references the additional labels to be
                           applied on the image
                         type: object
+                      timestamp:
+                        description: 'Timestamp references the optional image timestamp
+                          to be set, valid values are: - "Zero", to set 00:00:00 UTC
+                          on 1 January 1970 - "SourceTimestamp", to set the source
+                          timestamp dereived from the input source - "BuildTimestamp",
+                          to set the timestamp of the current build itself - Parsable
+                          integer number defined as the epoch seconds - or nil/empty
+                          to not set any specific timestamp'
+                        type: string
                     required:
                     - image
                     type: object
@@ -2351,6 +2369,15 @@ spec:
                     description: Labels references the additional labels to be applied
                       on the image
                     type: object
+                  timestamp:
+                    description: 'Timestamp references the optional image timestamp
+                      to be set, valid values are: - "Zero", to set 00:00:00 UTC on
+                      1 January 1970 - "SourceTimestamp", to set the source timestamp
+                      dereived from the input source - "BuildTimestamp", to set the
+                      timestamp of the current build itself - Parsable integer number
+                      defined as the epoch seconds - or nil/empty to not set any specific
+                      timestamp'
+                    type: string
                 required:
                 - image
                 type: object
@@ -4124,6 +4151,15 @@ spec:
                         description: Labels references the additional labels to be
                           applied on the image
                         type: object
+                      timestamp:
+                        description: 'Timestamp references the optional image timestamp
+                          to be set, valid values are: - "Zero", to set 00:00:00 UTC
+                          on 1 January 1970 - "SourceTimestamp", to set the source
+                          timestamp dereived from the input source - "BuildTimestamp",
+                          to set the timestamp of the current build itself - Parsable
+                          integer number defined as the epoch seconds - or nil/empty
+                          to not set any specific timestamp'
+                        type: string
                     required:
                     - image
                     type: object
@@ -4282,6 +4318,15 @@ spec:
                         description: Labels references the additional labels to be
                           applied on the image
                         type: object
+                      timestamp:
+                        description: 'Timestamp references the optional image timestamp
+                          to be set, valid values are: - "Zero", to set 00:00:00 UTC
+                          on 1 January 1970 - "SourceTimestamp", to set the source
+                          timestamp dereived from the input source - "BuildTimestamp",
+                          to set the timestamp of the current build itself - Parsable
+                          integer number defined as the epoch seconds - or nil/empty
+                          to not set any specific timestamp'
+                        type: string
                     required:
                     - image
                     type: object
@@ -6550,6 +6595,16 @@ spec:
                             description: Describes the secret name for pushing a container
                               image.
                             type: string
+                          timestamp:
+                            description: 'Timestamp references the optional image
+                              timestamp to be set, valid values are: - "Zero", to
+                              set 00:00:00 UTC on 1 January 1970 - "SourceTimestamp",
+                              to set the source timestamp dereived from the input
+                              source - "BuildTimestamp", to set the timestamp of the
+                              current build itself - Parsable integer number defined
+                              as the epoch seconds - or nil/empty to not set any specific
+                              timestamp'
+                            type: string
                         required:
                         - image
                         type: object
@@ -8684,6 +8739,15 @@ spec:
                     description: Describes the secret name for pushing a container
                       image.
                     type: string
+                  timestamp:
+                    description: 'Timestamp references the optional image timestamp
+                      to be set, valid values are: - "Zero", to set 00:00:00 UTC on
+                      1 January 1970 - "SourceTimestamp", to set the source timestamp
+                      dereived from the input source - "BuildTimestamp", to set the
+                      timestamp of the current build itself - Parsable integer number
+                      defined as the epoch seconds - or nil/empty to not set any specific
+                      timestamp'
+                    type: string
                 required:
                 - image
                 type: object
@@ -10546,6 +10610,15 @@ spec:
                         description: Describes the secret name for pushing a container
                           image.
                         type: string
+                      timestamp:
+                        description: 'Timestamp references the optional image timestamp
+                          to be set, valid values are: - "Zero", to set 00:00:00 UTC
+                          on 1 January 1970 - "SourceTimestamp", to set the source
+                          timestamp dereived from the input source - "BuildTimestamp",
+                          to set the timestamp of the current build itself - Parsable
+                          integer number defined as the epoch seconds - or nil/empty
+                          to not set any specific timestamp'
+                        type: string
                     required:
                     - image
                     type: object

diff --git a/deploy/crds/shipwright.io_builds.yaml b/deploy/crds/shipwright.io_builds.yaml
@@ -100,6 +100,15 @@ spec:
                     description: Labels references the additional labels to be applied
                       on the image
                     type: object
+                  timestamp:
+                    description: 'Timestamp references the optional image timestamp
+                      to be set, valid values are: - "Zero", to set 00:00:00 UTC on
+                      1 January 1970 - "SourceTimestamp", to set the source timestamp
+                      dereived from the input source - "BuildTimestamp", to set the
+                      timestamp of the current build itself - Parsable integer number
+                      defined as the epoch seconds - or nil/empty to not set any specific
+                      timestamp'
+                    type: string
                 required:
                 - image
                 type: object
@@ -252,6 +261,15 @@ spec:
                     description: Labels references the additional labels to be applied
                       on the image
                     type: object
+                  timestamp:
+                    description: 'Timestamp references the optional image timestamp
+                      to be set, valid values are: - "Zero", to set 00:00:00 UTC on
+                      1 January 1970 - "SourceTimestamp", to set the source timestamp
+                      dereived from the input source - "BuildTimestamp", to set the
+                      timestamp of the current build itself - Parsable integer number
+                      defined as the epoch seconds - or nil/empty to not set any specific
+                      timestamp'
+                    type: string
                 required:
                 - image
                 type: object
@@ -2324,6 +2342,15 @@ spec:
                     description: Describes the secret name for pushing a container
                       image.
                     type: string
+                  timestamp:
+                    description: 'Timestamp references the optional image timestamp
+                      to be set, valid values are: - "Zero", to set 00:00:00 UTC on
+                      1 January 1970 - "SourceTimestamp", to set the source timestamp
+                      dereived from the input source - "BuildTimestamp", to set the
+                      timestamp of the current build itself - Parsable integer number
+                      defined as the epoch seconds - or nil/empty to not set any specific
+                      timestamp'
+                    type: string
                 required:
                 - image
                 type: object

diff --git a/docs/build.md b/docs/build.md
@@ -89,6 +89,11 @@ The `Build` definition supports the following fields:
   - `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example, `5m`. The default is ten minutes. You can overwrite the value in the `BuildRun`.
   - `spec.output.annotations` - Refers to a list of `key/value` that could be used to [annotate](https://github.com/opencontainers/image-spec/blob/main/annotations.md) the output image.
   - `spec.output.labels` - Refers to a list of `key/value` that could be used to label the output image.
+  - `spec.output.timestamp` - Configure that the output image timestamp is changed to a specific value. When omitted, the respective strategy tool defines the output image timestamp.
+    - Use string `Zero` to set the image timestamp to UNIX epoch timestamp zero.
+    - Use string `SourceTimestamp` to set the image timestamp to the source timestamp, i.e. the timestamp of the Git commit that was used.
+    - Use string `BuildTimestamp` to set the image timestamp to the timestamp of the build run.
+    - Use any valid UNIX epoch seconds number as a string to set this as the image timestamp.
   - `spec.env` - Specifies additional environment variables that should be passed to the build container. The available variables depend on the tool that is being used by the chosen build strategy.
   - `spec.retention.atBuildDeletion` - Defines if all related BuildRuns needs to be deleted when deleting the Build. The default is false.
   - `spec.retention.ttlAfterFailed` - Specifies the duration for which a failed buildrun can exist.

diff --git a/pkg/apis/build/v1alpha1/build_types.go b/pkg/apis/build/v1alpha1/build_types.go
@@ -233,6 +233,16 @@ type Image struct {
 	//
 	// +optional
 	Labels map[string]string `json:"labels,omitempty"`
+
+	// Timestamp references the optional image timestamp to be set, valid values are:
+	// - "Zero", to set 00:00:00 UTC on 1 January 1970
+	// - "SourceTimestamp", to set the source timestamp dereived from the input source
+	// - "BuildTimestamp", to set the timestamp of the current build itself
+	// - Parsable integer number defined as the epoch seconds
+	// - or nil/empty to not set any specific timestamp
+	//
+	// +optional
+	Timestamp *string `json:"timestamp,omitempty"`
 }
 
 // BuildStatus defines the observed state of Build

diff --git a/pkg/apis/build/v1alpha1/zz_generated.deepcopy.go b/pkg/apis/build/v1alpha1/zz_generated.deepcopy.go
diff --git a/pkg/apis/build/v1beta1/build_conversion.go b/pkg/apis/build/v1beta1/build_conversion.go
@@ -200,6 +200,7 @@ func (dest *BuildSpec) ConvertFrom(orig *v1alpha1.BuildSpec) error {
 
 	dest.Output.Annotations = orig.Output.Annotations
 	dest.Output.Labels = orig.Output.Labels
+	dest.Output.Timestamp = orig.Output.Timestamp
 
 	// Handle BuildSpec Timeout
 	dest.Timeout = orig.Timeout
@@ -292,6 +293,7 @@ func (dest *BuildSpec) ConvertTo(bs *v1alpha1.BuildSpec) error {
 	}
 	bs.Output.Annotations = dest.Output.Annotations
 	bs.Output.Labels = dest.Output.Labels
+	bs.Output.Timestamp = dest.Output.Timestamp
 
 	// Handle BuildSpec Timeout
 	bs.Timeout = dest.Timeout

diff --git a/pkg/apis/build/v1beta1/build_types.go b/pkg/apis/build/v1beta1/build_types.go
@@ -196,6 +196,16 @@ type Image struct {
 	//
 	// +optional
 	Labels map[string]string `json:"labels,omitempty"`
+
+	// Timestamp references the optional image timestamp to be set, valid values are:
+	// - "Zero", to set 00:00:00 UTC on 1 January 1970
+	// - "SourceTimestamp", to set the source timestamp dereived from the input source
+	// - "BuildTimestamp", to set the timestamp of the current build itself
+	// - Parsable integer number defined as the epoch seconds
+	// - or nil/empty to not set any specific timestamp
+	//
+	// +optional
+	Timestamp *string `json:"timestamp,omitempty"`
 }
 
 // BuildStatus defines the observed state of Build

diff --git a/pkg/apis/build/v1beta1/zz_generated.deepcopy.go b/pkg/apis/build/v1beta1/zz_generated.deepcopy.go