feat(ingress): record source metadata in the image

.github/workflows/dstack-ingress-release.yml

@@ -14,20 +14,41 @@ permissions:
 jobs:
   build-and-attest:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: custom-domain/dstack-ingress
     env:
       IMAGE_REGISTRY: docker.io
       IMAGE_REPOSITORY: ${{ vars.DOCKERHUB_ORG }}/dstack-ingress
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Parse version from tag
+      - name: Parse and check version
         run: |
-          VERSION=${GITHUB_REF#refs/tags/dstack-ingress-v}
+          # The image records its version from the committed VERSION file, so
+          # that a plain checkout reproduces the digest. The release tag only
+          # selects which commit to build and must agree with that file.
+          VERSION=$(tr -d '[:space:]' < VERSION)
           if [ -z "${VERSION}" ]; then
-            echo "Unable to parse version from ref: ${GITHUB_REF}" >&2
+            echo "VERSION file is empty" >&2
             exit 1
           fi
+          case "${GITHUB_REF}" in
+            refs/tags/dstack-ingress-v*)
+              TAG_VERSION=${GITHUB_REF#refs/tags/dstack-ingress-v}
+              if [ "${TAG_VERSION}" != "${VERSION}" ]; then
+                echo "Tag dstack-ingress-v${TAG_VERSION} does not match the VERSION file (${VERSION})." >&2
+                echo "Update VERSION and re-tag, so the image version matches the release." >&2
+                exit 1
+              fi
+              ;;
+            *)
+              echo "This workflow builds a release and must run on a dstack-ingress-v* tag." >&2
+              echo "Got ref: ${GITHUB_REF}. Re-run it selecting the release tag." >&2
+              exit 1
+              ;;
+          esac
           echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
           echo "IMAGE_REFERENCE=${IMAGE_REGISTRY}/${IMAGE_REPOSITORY}:${VERSION}" >> "$GITHUB_ENV"
           echo "Parsed version: ${VERSION}"
@@ -45,15 +66,13 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build reproducible image and push
-        working-directory: custom-domain/dstack-ingress
         env:
           IMAGE_REFERENCE: ${{ env.IMAGE_REFERENCE }}
         run: |
-          ./build-image.sh --push "${IMAGE_REFERENCE}"
+          ./build-image.sh --require-clean --push "${IMAGE_REFERENCE}"
 
       - name: Capture image digest
         id: capture-digest
-        working-directory: custom-domain/dstack-ingress
         run: |
           DIGEST=$(skopeo inspect oci-archive:./oci.tar | jq -r '.Digest')
           if [ -z "${DIGEST}" ]; then
@@ -79,6 +98,7 @@ jobs:
             echo ""
             echo "- Tag: \`${IMAGE_REFERENCE}\`"
             echo "- Digest: \`${IMAGE_DIGEST}\`"
+            echo "- Source: \`${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/tree/${GITHUB_SHA}/custom-domain/dstack-ingress\`"
             echo "- Sigstore: https://search.sigstore.dev/?hash=${IMAGE_DIGEST}"
           } >> "$GITHUB_STEP_SUMMARY"
 
@@ -90,4 +110,27 @@ jobs:
 
             | Image | Digest | Verification |
             |---|---|---|
-            | ${{ env.IMAGE_REFERENCE }} | ${{ steps.capture-digest.outputs.digest }} | [Verify on Sigstore](https://search.sigstore.dev/?hash=${{ steps.capture-digest.outputs.digest }}) |
+            | ${{ env.IMAGE_REFERENCE }} | ${{ steps.capture-digest.outputs.digest }} | [Verify on Sigstore](https://search.sigstore.dev/?hash=${{ steps.capture-digest.outputs.digest }}) |
+
+            ## Source
+
+            Built from [`${{ github.sha }}`](${{ github.server_url }}/${{ github.repository }}/tree/${{ github.sha }}/custom-domain/dstack-ingress). The image records its source repository, commit and version as OCI labels and manifest annotations:
+
+            ```bash
+            skopeo inspect docker://${{ env.IMAGE_REFERENCE }} | jq .Labels
+            skopeo inspect --raw docker://${{ env.IMAGE_REFERENCE }} | jq .annotations
+            ```
+
+            ## Reproducible Build
+
+            Build on a native Linux amd64 host with Docker Buildx, Skopeo, jq and Git installed:
+
+            ```bash
+            git clone ${{ github.server_url }}/${{ github.repository }}.git
+            cd dstack-examples/custom-domain/dstack-ingress
+            git checkout ${{ github.sha }}
+            ./build-image.sh
+            skopeo inspect oci-archive:./oci.tar | jq -r '.Digest'
+            ```
+
+            Expected digest: `${{ steps.capture-digest.outputs.digest }}`

custom-domain/dstack-ingress/.dockerignore

@@ -0,0 +1,16 @@
+# The image needs exactly four things from this directory, so everything else
+# is excluded by default: an untracked local file can then neither leak into
+# the image nor change its digest. Enumerating junk instead would be a trap --
+# a tool's cache directory often carries its own .gitignore, so git reports a
+# clean tree and the --require-clean check in build-image.sh cannot see it.
+*
+!.BUILD_INFO
+!pinned-packages.txt
+!requirements.txt
+!scripts/
+
+# scripts/ comes back wholesale, so keep the same caches out of it: the dot
+# directories the Python tooling writes (pytest, mypy, ruff, coverage) and
+# __pycache__, which is the one that does not start with a dot.
+scripts/**/.*
+scripts/**/__pycache__

custom-domain/dstack-ingress/.gitignore

@@ -2,4 +2,6 @@
 /CLAUDE.md
 /test/
 __pycache__
+.pytest_cache
 /oci.tar
+/.BUILD_INFO

custom-domain/dstack-ingress/Dockerfile

@@ -97,7 +97,10 @@ RUN --mount=type=bind,source=scripts,target=/tmp/scripts,ro \
 ENV PATH="/scripts:$PATH"
 ENV PYTHONPATH="/scripts"
 ENV PYTHONUNBUFFERED=1
-COPY --chmod=666 .GIT_REV /etc/
+# Source metadata generated by build-image.sh (same key=value set as the OCI
+# labels and manifest annotations), so a running container can identify its
+# own source revision. Printed by the entrypoint at startup.
+COPY --chmod=644 .BUILD_INFO /etc/dstack-ingress/build-info
 
 ENTRYPOINT ["/scripts/entrypoint.sh"]
 CMD ["haproxy", "-W", "-f", "/etc/haproxy/haproxy.cfg"]

custom-domain/dstack-ingress/README.md

@@ -299,7 +299,44 @@ To disable the built-in evidence endpoint and serve evidence files only through
 ./build-image.sh --push yourusername/dstack-ingress:tag
 ```
 
-The build script ensures reproducibility via pinned packages, deterministic timestamps, and specific buildkit version.
+The build script ensures reproducibility via pinned packages, deterministic timestamps, and specific buildkit version. Building the same commit from a clean checkout produces the same image digest; CI runs the same script with `--require-clean`.
+
+### Image metadata
+
+Every image records where it came from, using the standard [OCI image annotation keys](https://github.com/opencontainers/image-spec/blob/main/annotations.md). The values are derived from the git checkout only (commit, the `VERSION` file, the Dockerfile base image), so they do not disturb reproducibility. The same key/value set is written to three places:
+
+| Location | How to read it |
+|---|---|
+| Image config labels | `skopeo inspect docker://dstacktee/dstack-ingress:<tag> \| jq .Labels` or `docker inspect --format '{{json .Config.Labels}}' <image>` |
+| Image manifest annotations | `skopeo inspect --raw docker://dstacktee/dstack-ingress:<tag> \| jq .annotations` |
+| `/etc/dstack-ingress/build-info` inside the image | `docker run --rm --entrypoint cat <image> /etc/dstack-ingress/build-info`; also printed as the first line of the container log |
+
+| Key | Value |
+|---|---|
+| `org.opencontainers.image.source` | Repository URL (`SOURCE_URL` env when building from a fork) |
+| `org.opencontainers.image.revision` | Git commit; suffixed with `-dirty` when built from an unclean tree |
+| `org.opencontainers.image.version` | Contents of `VERSION`; the release tag `dstack-ingress-v<version>` must match |
+| `org.opencontainers.image.url` / `.documentation` | This directory / README at that exact commit |
+| `org.opencontainers.image.base.name` / `.base.digest` | The pinned haproxy base image |
+
+To reproduce a published image, check out the commit from its `revision` label and run `./build-image.sh` on a native Linux amd64 host with Docker Buildx, Skopeo, jq and Git installed; the digest printed at the end must match the registry. Releases are additionally signed with SLSA provenance, verifiable with `gh attestation verify oci://docker.io/dstacktee/dstack-ingress:<tag> --owner Dstack-TEE`.
+
+### Releasing
+
+A release is not finished when the image is pushed. The compose files and the snippets above are what people deploy, so they have to point at the new image; 2.4 and 2.5 were tagged and published without that step, and every example kept deploying 2.3.
+
+1. Update `VERSION` and commit it. Bumping the version is a source change: the release workflow refuses to build unless the tag matches this file.
+
+   If the base image or the installed packages changed since the last release, run `./build-image.sh` locally first and commit the regenerated `pinned-packages.txt` in the same batch. The build refuses to publish an image whose packages that file does not record, so a stale one fails the release after a full CI build.
+2. Tag that commit `dstack-ingress-v<version>` and push the tag. CI builds with `--require-clean`, pushes the image, and reports the digest in the run summary and the release notes.
+3. Pin the published `<version>@sha256:<digest>` in one commit, everywhere the examples name the image:
+
+   ```bash
+   # from the repository root
+   grep -rn 'dstacktee/dstack-ingress:[0-9]' --include='*.yaml' --include='*.md' .
+   ```
+
+   Today that is `custom-domain/dstack-ingress/docker-compose.yaml`, `docker-compose.multi.yaml`, three snippets in this README, and `k3s/docker-compose.yaml`.
 
 ## License
 

custom-domain/dstack-ingress/VERSION

@@ -0,0 +1 @@
+2.6