docker
buildx bake: provide access to SOURCE_DATE_EPOCH as an RFC3339 timestamp string
Contributing guidelines
- [x] I've read the contributing guidelines and wholeheartedly agree
I've found a bug and checked that ...
- [x] ... the documentation does not mention anything about my problem
- [x] ... there are no open or closed issues that are related to my problem
Description
I want to be able to set the org.opencontainers.image.created label via SOURCE_DATE_EPOCH.
Expected behaviour
There should be a way to access SOURCE_DATE_EPOCH as a RFC3339 timestamp string.
https://developer.hashicorp.com/terraform/language/functions/timestamp
timestamp returns a UTC timestamp string in RFC 3339 format. […] The result of this function will change every second […] For more stable time handling, see the Time Provider.
Maybe timestamp() could return the value of SOURCE_DATE_EPOCH if set?
target "test" {
labels = {
"org.opencontainers.image.created" = timestamp()
}
}
Alternatively, there would be a function similar to provider::time::unix_timestamp_parse.
Actual behaviour
-
SOURCE_DATE_EPOCHcannot be accessed as a RFC3339 timestamp string -
provider::time::unix_timestamp_parse cannot be used
Buildx version
github.com/docker/buildx v0.23.0-desktop.1 503f948aadbddb6de3ec5581f766e1d27f6975a1
Docker info
Client:
Version: 28.1.1
Context: desktop-linux
Debug Mode: false
Plugins:
ai: Docker AI Agent - Ask Gordon (Docker Inc.)
Version: v1.1.7
Path: /Users/redacted/.docker/cli-plugins/docker-ai
buildx: Docker Buildx (Docker Inc.)
Version: v0.23.0-desktop.1
Path: /Users/redacted/.docker/cli-plugins/docker-buildx
cloud: Docker Cloud (Docker Inc.)
Version: v0.3.0
Path: /Users/redacted/.docker/cli-plugins/docker-cloud
compose: Docker Compose (Docker Inc.)
Version: v2.35.1-desktop.1
Path: /Users/redacted/.docker/cli-plugins/docker-compose
debug: Get a shell into any image or container (Docker Inc.)
Version: 0.0.38
Path: /Users/redacted/.docker/cli-plugins/docker-debug
desktop: Docker Desktop commands (Docker Inc.)
Version: v0.1.8
Path: /Users/redacted/.docker/cli-plugins/docker-desktop
dev: Docker Dev Environments (Docker Inc.)
Version: v0.1.2
Path: /Users/redacted/.docker/cli-plugins/docker-dev
extension: Manages Docker extensions (Docker Inc.)
Version: v0.2.27
Path: /Users/redacted/.docker/cli-plugins/docker-extension
init: Creates Docker-related starter files for your project (Docker Inc.)
Version: v1.4.0
Path: /Users/redacted/.docker/cli-plugins/docker-init
mcp: Docker MCP Plugin (Docker Inc.)
Version: dev
Path: /Users/dev/.docker/cli-plugins/docker-mcp
sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc.)
Version: 0.6.0
Path: /Users/redacted/.docker/cli-plugins/docker-sbom
scout: Docker Scout (Docker Inc.)
Version: v1.17.1
Path: /Users/redacted/.docker/cli-plugins/docker-scout
Server:
Containers: 1
Running: 0
Paused: 0
Stopped: 1
Images: 13
Server Version: 28.1.1
Storage Driver: overlayfs
driver-type: io.containerd.snapshotter.v1
Logging Driver: json-file
Cgroup Driver: cgroupfs
Cgroup Version: 2
Plugins:
Volume: local
Network: bridge host ipvlan macvlan null overlay
Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
CDI spec directories:
/etc/cdi
/var/run/cdi
Swarm: inactive
Runtimes: io.containerd.runc.v2 runc
Default Runtime: runc
Init Binary: docker-init
containerd version: 05044ec0a9a75232cad458027ca83437aae3f4da
runc version: v1.2.5-0-g59923ef
init version: de40ad0
Security Options:
seccomp
Profile: unconfined
cgroupns
Kernel Version: 6.10.14-linuxkit
Operating System: Docker Desktop
OSType: linux
Architecture: x86_64
CPUs: 8
Total Memory: 7.656GiB
Name: docker-desktop
ID: ca550c22-08a5-4e2b-ace8-d6196ec5b543
Docker Root Dir: /var/lib/docker
Debug Mode: false
HTTP Proxy: http.docker.internal:3128
HTTPS Proxy: http.docker.internal:3128
No Proxy: hubproxy.docker.internal
Labels:
com.docker.desktop.address=unix:///Users/dev/Library/Containers/com.docker.docker/Data/docker-cli.sock
Experimental: false
Insecure Registries:
hubproxy.docker.internal:5555
::1/128
127.0.0.0/8
Live Restore Enabled: false
Builders list
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
default docker
\_ default \_ default running v0.21.0 linux/amd64 (+2), linux/arm64, linux/arm (+2), linux/ppc64le, (2 more)
desktop-linux* docker
\_ desktop-linux \_ desktop-linux running v0.21.0 linux/amd64 (+2), linux/arm64, linux/arm (+2), linux/ppc64le, (2 more)
Configuration
FROM scratch
variable "BUILD_TIME" {
type = string
default = timestamp()
}
variable "SOURCE_DATE_EPOCH" {
type = number
}
group "default" {
targets = ["test"]
}
target "test" {
tags = ["baked"]
labels = {
"org.opencontainers.image.created" = "${BUILD_TIME}"
"epoch" = "${SOURCE_DATE_EPOCH}"
}
}
$ SOURCE_DATE_EPOCH=0 docker buildx build -t test .
$ SOURCE_DATE_EPOCH=0 docker buildx bake
$ docker inspect test
[
{
"Id": "sha256:3a58ad119f0dae830e39299dd9d94100e3a764665fba8810f9a873d3ac716aec",
"RepoTags": [
"test:latest"
],
"RepoDigests": [
"test@sha256:3a58ad119f0dae830e39299dd9d94100e3a764665fba8810f9a873d3ac716aec"
],
"Parent": "",
"Comment": "",
"DockerVersion": "",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": null,
"Image": "",
"Volumes": null,
"WorkingDir": "/",
"Entrypoint": null,
"OnBuild": null,
"Labels": null
},
"Architecture": "amd64",
"Os": "linux",
"Size": 518,
"GraphDriver": {
"Data": null,
"Name": "overlayfs"
},
"RootFS": {
"Type": "layers"
},
"Metadata": {
"LastTagTime": "1970-01-01T00:00:00Z"
},
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:3a58ad119f0dae830e39299dd9d94100e3a764665fba8810f9a873d3ac716aec",
"size": 304,
"annotations": {
"config.digest": "sha256:471a1b8817eefb6569017c1a76f288e0d4e5c8476eb199485c469d0b033168bf"
}
}
}
]
$ docker inspect baked
[
{
"Id": "sha256:2dde41d15026c98ba86bd04748102d70ddefb4a92208dde271ba9f0228c2e920",
"RepoTags": [
"baked:latest"
],
"RepoDigests": [
"baked@sha256:2dde41d15026c98ba86bd04748102d70ddefb4a92208dde271ba9f0228c2e920"
],
"Parent": "",
"Comment": "",
"DockerVersion": "",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": null,
"Image": "",
"Volumes": null,
"WorkingDir": "/",
"Entrypoint": null,
"OnBuild": null,
"Labels": {
"epoch": "0",
"org.opencontainers.image.created": "2025-05-20T14:56:18Z"
}
},
"Architecture": "amd64",
"Os": "linux",
"Size": 599,
"GraphDriver": {
"Data": null,
"Name": "overlayfs"
},
"RootFS": {
"Type": "layers"
},
"Metadata": {
"LastTagTime": "1970-01-01T00:00:00Z"
},
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:2dde41d15026c98ba86bd04748102d70ddefb4a92208dde271ba9f0228c2e920",
"size": 304,
"annotations": {
"config.digest": "sha256:8f94f276f13134f47a434228684fca44e0e0e4fb08f79b5dc8c76ea37225bc66"
}
}
}
]
Build logs
Additional info
- https://reproducible-builds.org/docs/source-date-epoch/
- https://registry.terraform.io/providers/hashicorp/time/latest/docs/functions/unix_timestamp_parse
- https://developer.hashicorp.com/terraform/language/functions/timestamp
- https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys
One could pass BUILD_TIME from the outside but it would not be DRY and unfortunately BSD/Linux date have different flags, e.g.:
SOURCE_DATE_EPOCH="$(git log --max-count=1 --pretty=format:%ct)"
if [ "$(uname)" = 'Darwin' ]; then
BUILD_TIME="$(date -r "${SOURCE_DATE_EPOCH}" -Iseconds -u | sed -e 's/+00:00$/Z/')"
else
BUILD_TIME="$(date -d "@${SOURCE_DATE_EPOCH}" -Iseconds -u | sed -e 's/+00:00$/Z/')"
fi
I was thinking you could use formatdate but format is limited and X is not supported:
variable "BUILD_TIME" {
type = string
default = timestamp()
}
variable "SOURCE_DATE_EPOCH" {
type = number
default = formatdate("X", timestamp())
}
group "default" {
targets = ["test"]
}
target "test" {
tags = ["baked"]
labels = {
"org.opencontainers.image.created" = "${BUILD_TIME}"
"epoch" = "${SOURCE_DATE_EPOCH}"
}
}
$ docker buildx bake --print
#1 [internal] load local bake definitions
#1 reading docker-bake.hcl 355B / 355B done
#1 DONE 0.0s
docker-bake.hcl:7
--------------------
5 | variable "SOURCE_DATE_EPOCH" {
6 | type = number
7 | >>> default = formatdate("X", timestamp())
8 | }
9 | group "default" {
--------------------
ERROR: docker-bake.hcl:7,26-27: Invalid function argument; Invalid value for "format" parameter: invalid date format verb "X".
I think we could either support more formats or maybe have something similar to time_static
SOURCE_DATE_EPOCH - A UNIX timestamp, defined as the number of seconds, excluding leap seconds, since 01 Jan 1970 00:00:00 UTC
formatdate requires a timestamp in RFC 3339 "Date and Time format" syntax.
—--
time_static.build_time set to SOURCE_DATE_EPOCH or the current timestamp if not set is another option.
time_static.build_time.rfc3339
—--
A conversion function (unix to rfc3339 timestamp) would have more use cases though.
If we added support that the timestamp passed to formatdate (2nd param) can be unix timestamp, would that fix the issue? We could do it by just checking if it only contains numbers.
We could also consider something special for the reverse behavior of formatting timestamp RFC3339 timestamp into unix, but I think that would require upstream go-cty change (or bunch of copy-paste).
If we added support that the timestamp passed to
formatdate(2nd param) can be unix timestamp, would that fix the issue?
I am not sure if it is a good idea.
It mainly depends on how you see Docker's use of HCL:
a) HCL syntax only b) syntax and built-in functions c) syntax, built-in functions, and XYX
If built-in functions are supported then I think they should be kept closely aligned with the Terraform functions to maximize knowledge transfer.
Let's not have the GNU/BSD sed situation again.