OCI image fixes (#41)

## Description


Add OCI metadata, created timestamp, and simplify per-arch layout

- Add standard OCI annotations (manifest) and labels (config) to all platform manifests: created, source, revision, version, title, description, vendor, and licenses.
- Add crane.set_created() to set the image config 'created' field so docker images shows the correct timestamp instead of N/A.
- Add labels parameter to crane.mutate() for writing to image config.
- Bump crane to v0.21.2 in Dockerfile.release.

Simplify the multi-arch image layout:
Combined (no suffix):
    linux/amd64: [A1..A4, B1..B4]  (native-first, all 8 layers)
    linux/arm64: [B1..B4, A1..A4]

Per-arch (-amd64 / -arm64 suffix):
    linux/amd64: [X1..X4]  (same 4 layers under both platforms)
    linux/arm64: [X1..X4]

Pulling the combined image then the native per-arch image gives Docker cache hits because the per-arch layers form a prefix of the combined chain.  Cross-arch caching is not possible (Docker chain-IDs encode full layer ancestry) and is no longer attempted.

Remove _other_arch_available() and the cross-chain mirroring logic. Remove --platform selection from pull() since per-arch platform entries are now identical.

Fixes: #

## How Has This Been Tested?





## How are existing users impacted? What migration steps/scripts do we need?





## Checklist:

I have:

- [ ] updated the documentation and/or roadmap (if required)
- [ ] added unit or e2e tests
- [ ] provided instructions on how to upgrade

Author: mergify[bot]

Dockerfile.release

@@ -6,7 +6,7 @@
 #   docker run --rm -v $(pwd):/work captainos-release release publish
 FROM python:3.12-slim
 
-ARG CRANE_VERSION=v0.20.3
+ARG CRANE_VERSION=v0.21.2
 
 # Install git (needed for version tag computation) and tar (for crane export)
 RUN apt-get update && apt-get install -y --no-install-recommends \

captain/crane.py

@@ -12,6 +12,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 import subprocess
 import tarfile
@@ -48,16 +49,24 @@ def mutate(
     *,
     platform: str | None = None,
     annotations: dict[str, str] | None = None,
+    labels: dict[str, str] | None = None,
     tag: str | None = None,
     logger: StageLogger | None = None,
 ) -> None:
-    """Mutate metadata on *image_ref* (platform, annotations, re-tag)."""
+    """Mutate metadata on *image_ref* (platform, annotations, labels, re-tag).
+
+    *annotations* are written to the OCI manifest (visible via
+    ``crane manifest``).  *labels* are written to the image config
+    (visible via ``docker inspect``).
+    """
     _log = logger or _default_log
     cmd: list[str] = ["crane", "mutate", image_ref]
     if platform:
         cmd += ["--set-platform", platform]
     for key, value in (annotations or {}).items():
         cmd += ["-a", f"{key}={value}"]
+    for key, value in (labels or {}).items():
+        cmd += ["-l", f"{key}={value}"]
     if tag:
         cmd += ["-t", tag]
     _log.log(f"crane mutate {image_ref}")
@@ -143,3 +152,33 @@ def tag(src_ref: str, new_tag: str, *, logger: StageLogger | None = None) -> Non
     _log = logger or _default_log
     _log.log(f"crane tag {src_ref} {new_tag}")
     run(["crane", "tag", src_ref, new_tag])
+
+
+def set_created(
+    image_ref: str,
+    created: str,
+    *,
+    logger: StageLogger | None = None,
+) -> None:
+    """Set the ``created`` timestamp in the image config of *image_ref*.
+
+    Uses ``crane config`` to read the config JSON, patches the
+    ``created`` field, and pipes it back through ``crane edit config``.
+    This sets the top-level config timestamp that ``docker images``
+    displays in the CREATED column.
+    """
+    _log = logger or _default_log
+    _log.log(f"crane set-created {image_ref}")
+    cfg_result = run(["crane", "config", image_ref], capture=True)
+    config = json.loads(cfg_result.stdout)
+    config["created"] = created
+    edit_proc = subprocess.Popen(
+        ["crane", "edit", "config", image_ref],
+        stdin=subprocess.PIPE,
+    )
+    edit_proc.communicate(input=json.dumps(config).encode())
+    if edit_proc.returncode != 0:
+        raise subprocess.CalledProcessError(
+            edit_proc.returncode,
+            ["crane", "edit", "config", image_ref],
+        )

captain/oci.py

@@ -1,9 +1,22 @@
 """High-level OCI artifact operations for publishing and retrieving releases.
 
 Each artifact file is pushed as its own layer so that OCI registries
-can deduplicate blobs between per-arch and combined images.  Every
-image is a multi-arch OCI index (linux/amd64 + linux/arm64 entries
-pointing to the same content) so that any platform can pull it.
+can deduplicate blobs between per-arch and combined images.
+
+Combined image (``target="both"``, no tag suffix):
+  A multi-arch index where each platform manifest has the native
+  arch's layers first, then the other arch's layers (8 layers total).
+  ``linux/amd64`` → ``[A1‥A4, B1‥B4]``,
+  ``linux/arm64`` → ``[B1‥B4, A1‥A4]``.
+
+Per-arch image (``target="amd64"`` or ``"arm64"``, tag suffix ``-{arch}``):
+  A multi-arch index where both platform entries contain the same
+  4 layers (only that arch's artifacts).
+
+Docker layer caching: pulling the combined image first and then the
+native per-arch image gives cache hits, because the per-arch layers
+form a prefix of the combined chain.  Cross-arch caching is not
+possible due to Docker's chain-ID Merkle structure.
 
 * **containerd** can pull it (valid ``rootfs.diff_ids`` in the config) —
   Kubernetes image-volume mounts work.
@@ -14,6 +27,7 @@
 
 import subprocess
 import tarfile
+from datetime import datetime, timezone
 from pathlib import Path
 
 from captain import artifacts, crane
@@ -136,19 +150,32 @@ def _push_platform_manifest(
     sha: str,
     repository: str,
     logger: StageLogger,
+    *,
+    created: str,
+    tag: str,
+    artifact_name: str,
 ) -> None:
     """Push artifact layers and set platform metadata on a temp manifest."""
     for i, tar_path in enumerate(layer_tars):
         crane.append(tar_path, temp_ref, base=temp_ref if i > 0 else None, logger=logger)
+    oci_metadata = {
+        "org.opencontainers.image.created": created,
+        "org.opencontainers.image.source": f"https://github.com/{repository}",
+        "org.opencontainers.image.revision": sha,
+        "org.opencontainers.image.version": tag,
+        "org.opencontainers.image.title": artifact_name,
+        "org.opencontainers.image.description": "CaptainOS build artifacts",
+        "org.opencontainers.image.vendor": "Tinkerbell",
+        "org.opencontainers.image.licenses": "Apache-2.0",
+    }
     crane.mutate(
         temp_ref,
         platform=platform,
-        annotations={
-            "org.opencontainers.image.source": f"https://github.com/{repository}",
-            "org.opencontainers.image.revision": sha,
-        },
+        annotations=oci_metadata,
+        labels=oci_metadata,
         logger=logger,
     )
+    crane.set_created(temp_ref, created, logger=logger)
 
 
 def publish(
@@ -164,54 +191,93 @@ def publish(
 ) -> None:
     """Collect artifacts and publish a multi-arch OCI index.
 
-    Each artifact file becomes its own layer so that OCI registries
-    deduplicate shared blobs between per-arch and combined images.
+    Each artifact file becomes its own layer.  Deterministic tar
+    generation ensures byte-identical layers across publish runs,
+    so OCI registries deduplicate blobs automatically.
 
     *target* selects which artifacts to include: ``"amd64"``,
-    ``"arm64"``, or ``"both"`` (all artifacts from both arches).
+    ``"arm64"``, or ``"both"``.
     """
     _log = logger or _default_log
     arches = list(_ARCHES) if target == "both" else [target]
     tag_suffix = "" if target == "both" else f"-{target}"
-    final_ref = _image_ref(registry, repository, artifact_name, f"{tag}{tag_suffix}")
+    full_tag = f"{tag}{tag_suffix}"
+    final_ref = _image_ref(registry, repository, artifact_name, full_tag)
     out = ensure_dir(cfg.output_dir)
+    image_base = f"{registry}/{repository}/{artifact_name}"
+    created = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    # Collect artifacts for every requested architecture.
+    arch_files: dict[str, list[Path]] = {}
+    for arch in arches:
+        arch_files[arch] = _collect_arch_artifacts(
+            cfg.project_dir,
+            out,
+            arch,
+            _log,
+        )
 
-    all_files: list[Path] = []
-    for a in arches:
-        files = _collect_arch_artifacts(cfg.project_dir, out, a, _log)
-        all_files.extend(files)
+    # Create deterministic layer tars (shared across manifest pushes).
+    arch_layer_tars: dict[str, list[Path]] = {}
+    for arch, files in arch_files.items():
+        arch_layer_tars[arch] = [_deterministic_tar(f, out) for f in files]
 
-    # Create deterministic per-file tars for layer dedup
-    layer_tars: list[Path] = []
     try:
-        for f in all_files:
-            layer_tars.append(_deterministic_tar(f, out))
-
-        # Push platform manifests and capture their digests.
-        # Each push overwrites the same tag; the digest is captured before
-        # the next overwrite.  This avoids leftover intermediate tags.
-        image_base = f"{registry}/{repository}/{artifact_name}"
-        platforms = ["linux/amd64", "linux/arm64"]
         digest_refs: list[str] = []
-        for platform in platforms:
-            _push_platform_manifest(layer_tars, final_ref, platform, sha, repository, _log)
-            d = crane.digest(final_ref, logger=_log)
-            digest_refs.append(f"{image_base}@{d}")
+
+        if target == "both":
+            # Combined image: native-first ordering per platform.
+            for arch in _ARCHES:
+                other = next(a for a in _ARCHES if a != arch)
+                ordered = list(arch_layer_tars[arch]) + list(arch_layer_tars[other])
+                _push_platform_manifest(
+                    ordered,
+                    final_ref,
+                    f"linux/{arch}",
+                    sha,
+                    repository,
+                    _log,
+                    created=created,
+                    tag=full_tag,
+                    artifact_name=artifact_name,
+                )
+                d = crane.digest(final_ref, logger=_log)
+                digest_refs.append(f"{image_base}@{d}")
+        else:
+            # Per-arch: same layers under both platforms.
+            for arch in _ARCHES:
+                _push_platform_manifest(
+                    arch_layer_tars[target],
+                    final_ref,
+                    f"linux/{arch}",
+                    sha,
+                    repository,
+                    _log,
+                    created=created,
+                    tag=full_tag,
+                    artifact_name=artifact_name,
+                )
+                d = crane.digest(final_ref, logger=_log)
+                digest_refs.append(f"{image_base}@{d}")
 
         # Create multi-arch index (overwrites the tag with the index)
         crane.index_append(final_ref, digest_refs, logger=_log)
     finally:
-        for t in layer_tars:
-            t.unlink(missing_ok=True)
+        for tars in arch_layer_tars.values():
+            for t in tars:
+                t.unlink(missing_ok=True)
 
     # Recap
-    artifact_names = [f.name for f in all_files]
+    artifact_names: list[str] = []
+    for arch in arches:
+        artifact_names.extend(f.name for f in arch_files.get(arch, []))
+    platforms = [f"linux/{a}" for a in _ARCHES]
     _log.log("")
     _log.log("Publish complete")
     _log.log(f"  Image:     {final_ref}")
     _log.log(f"  Target:    {target}")
     _log.log(f"  Platforms: {', '.join(platforms)}")
-    _log.log(f"  Layers:    {len(layer_tars)}")
+    _log.log(f"  Layers:    {len(artifact_names)}")
     _log.log("  Artifacts:")
     for name in artifact_names:
         _log.log(f"    - {name}")