🏷️ Stamp images with their build commit and time

Dockerfiles bake DROBOTICFLOW_IMAGE_BUILD_COMMIT from a build-arg that
defaults to 'unknown', and the API prefers it over the deployment stamp, so
release images built without the arg reported buildCommit 'unknown'.

Add scripts/release-build-api-image.sh for release.py builds: it refuses
uncommitted tracked changes, passes the checkout commit and UTC build time,
pushes, and prints the digest reference for prepare --image. The general
build-and-push script now passes both args too. Document the step in the
release README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
d-robotics 2026-10-28 00:36:20 +08:00
parent d0a63cc9dd
commit 54a960284c
5 changed files with 166 additions and 0 deletions

View File

@ -45,6 +45,19 @@ Coordinator 保留当前镜像;更新它们仍须单独审查与授权。
使用干净、已提交的工作树;其他人的未提交改动保留在原工作树,使用隔离工作树发布。
镜像必须使用 `repository@sha256:...`,不接受可变 tag。先构建、核对镜像来源,再准备发布。
在隔离检出中用脚本构建 API 镜像(处理器使用同一镜像):
```sh
GOPROXY=https://goproxy.cn,direct scripts/release-build-api-image.sh \
ccr-29eug8s3-pub.cnc.bj.baidubce.com/fanyu/droboticflow-api <metadata-file>
```
脚本要求已跟踪文件无未提交改动,把检出 commit 和 UTC 构建时间作为
`DROBOTICFLOW_BUILD_COMMIT`/`DROBOTICFLOW_BUILD_TIME` build-arg 写进镜像,推送后从 buildx
metadata 读取 digest,输出 `IMAGE=...@sha256:...` 供 `--image` 使用。镜像里的
`DROBOTICFLOW_IMAGE_BUILD_COMMIT` 优先于部署注入的构建标记;直接运行 `docker buildx build`
而不传这两个参数时,`/api/ready` 和页面的连接诊断会显示 commit 为 `unknown`。
目标 server、context、namespace UID 从已核实的集群身份取得,不能从一次错误连接中直接认可。
工具检查 namespace UID 及 API server,namespace 名字相同也不能蒙混过关。

View File

@ -31,6 +31,11 @@ validate_image_reference OPERATOR_RUNNER_IMAGE "$OPERATOR_RUNNER_IMAGE"
docker buildx inspect >/dev/null 2>&1 || docker buildx create --use >/dev/null
# Images bake these into DROBOTICFLOW_IMAGE_BUILD_*, which /api/ready prefers
# over the deployment stamp; without them every image reports "unknown".
BUILD_COMMIT="${DROBOTICFLOW_BUILD_COMMIT:-$(git -C "$ROOT_DIR" rev-parse HEAD)}"
BUILD_TIME="${DROBOTICFLOW_BUILD_TIME:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"
build_image() {
local dockerfile="$1"
local image="$2"
@ -44,6 +49,8 @@ build_image() {
docker buildx build \
--platform "$PLATFORM" \
--build-arg "GOPROXY=${GOPROXY:-https://proxy.golang.org,direct}" \
--build-arg "DROBOTICFLOW_BUILD_COMMIT=$BUILD_COMMIT" \
--build-arg "DROBOTICFLOW_BUILD_TIME=$BUILD_TIME" \
"$action_flag" \
-f "$ROOT_DIR/$dockerfile" \
-t "$image" \

View File

@ -0,0 +1,46 @@
#!/usr/bin/env bash
# Build and push the API image (also run by the annotation processor) for a
# release.py image release. The image carries the checkout commit and build
# time, so /api/ready reports the commit the image was built from.
#
# Usage: scripts/release-build-api-image.sh <registry/repository> [metadata-file]
# Prints IMAGE=<registry/repository@sha256:...> for `release.py prepare --image`.
set -euo pipefail
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
DOCKER="${DOCKER:-docker}"
PLATFORM="${PLATFORM:-linux/amd64}"
repository="${1:-}"
if [[ -z "$repository" || "$repository" == *@* || "$repository" =~ :[^/]*$ ]]; then
echo "usage: $0 <registry/repository> [metadata-file] (repository without tag or digest)" >&2
exit 2
fi
# The stamp names the commit; uncommitted tracked changes would make it lie.
if [[ -n "$(git -C "$ROOT_DIR" status --porcelain --untracked-files=no)" ]]; then
echo "tracked files have uncommitted changes; build from a clean release checkout" >&2
exit 1
fi
commit="$(git -C "$ROOT_DIR" rev-parse HEAD)"
build_time="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
metadata="${2:-$(mktemp -t droboticflow-api-build.XXXXXX)}"
"$DOCKER" buildx build \
--platform "$PLATFORM" \
--build-arg "GOPROXY=${GOPROXY:-https://proxy.golang.org,direct}" \
--build-arg "DROBOTICFLOW_BUILD_COMMIT=$commit" \
--build-arg "DROBOTICFLOW_BUILD_TIME=$build_time" \
--metadata-file "$metadata" \
--push \
-f "$ROOT_DIR/Dockerfile.api" \
-t "$repository:${commit:0:8}" \
"$ROOT_DIR"
digest="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["containerimage.digest"])' "$metadata")"
if [[ "$digest" != sha256:* ]]; then
echo "build metadata has no image digest: $metadata" >&2
exit 1
fi
printf 'COMMIT=%s\nBUILD_TIME=%s\nMETADATA=%s\nIMAGE=%s@%s\n' "$commit" "$build_time" "$metadata" "$repository" "$digest"

View File

@ -46,3 +46,30 @@ def test_build_and_push_rejects_invalid_explicit_image_before_docker():
assert result.returncode == 1
assert "API_IMAGE must be a non-empty container image reference" in result.stderr
def test_build_and_push_stamps_every_image_with_commit_and_time(tmp_path):
fake = tmp_path / "docker"
log = tmp_path / "calls"
fake.write_text('#!/usr/bin/env bash\n[[ "$2" == build ]] && printf \'%s\\n\' "$*" >> "$FAKE_DOCKER_LOG"\nexit 0\n')
fake.chmod(0o755)
result = run_build_script(
{
"PATH": f"{tmp_path}:{os.environ['PATH']}",
"FAKE_DOCKER_LOG": str(log),
"PUSH": "false",
"DROBOTICFLOW_BUILD_COMMIT": "abc123",
"DROBOTICFLOW_BUILD_TIME": "2026-10-28T00:00:00Z",
"API_IMAGE": "registry.example.com/dataflow/droboticflow-api:test",
"WORKER_IMAGE": "registry.example.com/dataflow/droboticflow-worker:test",
"DROSYNC_COORDINATOR_IMAGE": "registry.example.com/dataflow/drosync-coordinator:test",
"OPERATOR_RUNNER_IMAGE": "registry.example.com/dataflow/droboticflow-operator-runner:test",
}
)
assert result.returncode == 0, result.stderr
builds = log.read_text().splitlines()
assert len(builds) == 4
for build in builds:
assert "--build-arg DROBOTICFLOW_BUILD_COMMIT=abc123" in build
assert "--build-arg DROBOTICFLOW_BUILD_TIME=2026-10-28T00:00:00Z" in build

View File

@ -0,0 +1,73 @@
import json
import os
import pathlib
import shutil
import subprocess
import tempfile
import unittest
ROOT = pathlib.Path(__file__).resolve().parents[2]
SCRIPT = ROOT / "scripts" / "release-build-api-image.sh"
# Records its arguments and writes buildx metadata like a successful push.
FAKE_DOCKER = """#!/usr/bin/env bash
printf '%s\\n' "$@" > "$FAKE_DOCKER_ARGS"
while [[ $# -gt 0 ]]; do
if [[ "$1" == --metadata-file ]]; then
printf '{"containerimage.digest": "sha256:%064d"}' 7 > "$2"
fi
shift
done
"""
class ReleaseBuildApiImageTest(unittest.TestCase):
def setUp(self):
self.tmp = pathlib.Path(tempfile.mkdtemp())
self.addCleanup(shutil.rmtree, self.tmp)
self.repo = self.tmp / "repo"
(self.repo / "scripts").mkdir(parents=True)
shutil.copy(SCRIPT, self.repo / "scripts" / SCRIPT.name)
(self.repo / "Dockerfile.api").write_text("FROM scratch\n")
git = ["git", "-C", str(self.repo), "-c", "user.name=t", "-c", "user.email=t@example.com"]
subprocess.run(["git", "init", "-q", str(self.repo)], check=True)
subprocess.run([*git, "add", "."], check=True)
subprocess.run([*git, "commit", "-q", "-m", "init"], check=True)
self.commit = subprocess.run(["git", "-C", str(self.repo), "rev-parse", "HEAD"], check=True, capture_output=True, text=True).stdout.strip()
self.docker = self.tmp / "docker"
self.docker.write_text(FAKE_DOCKER)
self.docker.chmod(0o755)
self.args_file = self.tmp / "args"
def run_script(self, *args):
env = {**os.environ, "DOCKER": str(self.docker), "FAKE_DOCKER_ARGS": str(self.args_file)}
return subprocess.run(["bash", str(self.repo / "scripts" / SCRIPT.name), *args], env=env, text=True, capture_output=True)
def test_passes_commit_and_time_and_prints_digest_reference(self):
metadata = self.tmp / "meta.json"
result = self.run_script("registry.example.com/team/droboticflow-api", str(metadata))
self.assertEqual(result.returncode, 0, result.stderr)
args = self.args_file.read_text().splitlines()
self.assertIn(f"DROBOTICFLOW_BUILD_COMMIT={self.commit}", args)
self.assertTrue(any(a.startswith("DROBOTICFLOW_BUILD_TIME=20") and a.endswith("Z") for a in args), args)
self.assertIn(f"registry.example.com/team/droboticflow-api:{self.commit[:8]}", args)
self.assertIn("--push", args)
self.assertIn(f"IMAGE=registry.example.com/team/droboticflow-api@sha256:{7:064d}", result.stdout)
self.assertEqual(json.loads(metadata.read_text())["containerimage.digest"], f"sha256:{7:064d}")
def test_rejects_uncommitted_tracked_changes_before_docker(self):
(self.repo / "Dockerfile.api").write_text("FROM scratch\nRUN true\n")
result = self.run_script("registry.example.com/team/droboticflow-api")
self.assertEqual(result.returncode, 1)
self.assertIn("uncommitted changes", result.stderr)
self.assertFalse(self.args_file.exists())
def test_rejects_tagged_or_digest_repository(self):
for ref in ("registry.example.com/team/api:tag", "registry.example.com/team/api@sha256:abc", ""):
result = self.run_script(ref)
self.assertEqual(result.returncode, 2, ref)
self.assertFalse(self.args_file.exists())
if __name__ == "__main__":
unittest.main()