Versions
Record which build is running in places that people with access already read: the error tracker's release, a Kubernetes label, a build_info metric and annotations on the image. Bake the version into the image, inject environment config at deploy time, and keep the version out of public response headers.
Build time
The version identifies the build, so the image carries it itself. It then stays correct wherever the image runs, even after a manual kubectl set image or in a plain docker run. Environment config, such as the environment name and the error tracker DSN, stays out of the image and comes in at deploy time (The Twelve-Factor App: build, release, run).
Caching
Pass the version as build arguments in the last instructions of the Dockerfile, after the last RUN. All RUN instructions after an ARG line use it as an environment variable, so an ARG near the top makes every commit a cache miss for the whole image (Dockerfile reference). At the end, a new commit only changes image metadata:
# After the last RUN, so a new commit only changes image metadata
ARG VERSION=development
ARG REVISION
ENV APP_VERSION=${VERSION}${REVISION:+:$REVISION}Arguments
No build argument name is common across CI systems; these follow the OCI annotation keys org.opencontainers.image.version and org.opencontainers.image.revision. GitLab CI passes the same values as the image tag with --build-arg VERSION=$CI_COMMIT_REF_SLUG --build-arg REVISION=$CI_COMMIT_SHORT_SHA. A build without arguments reads development.
Error tracker
Sentry links each error to a release. Release names can't contain /, \, tabs or newlines, and are at most 200 characters (Sentry: naming releases). Use the branch slug (feature-login), never the branch name (feature/login). Releases are global per Sentry organization, so prefix them with the project name when several projects share an organization. Derive the release in the app from the baked version, for example backend@main+7056b235 in Sentry's package@version+build format.
Kubernetes label
Put the version on the app.kubernetes.io/version label of every resource (recommended labels). kubectl get pods --label-columns app.kubernetes.io/version then shows it per pod. The downward API can pass that one label into the container as an environment variable or a file (downward API).
Metrics
Export a gauge that is always 1 and carries the build as labels:
build_info{branch="main",revision="7056b235",version="main:7056b235"} 1Dashboards join it onto other series with group_left, for example rate(http_requests_total[5m]) * on (pod) group_left(version) build_info (vector matching). The Prometheus naming guide asks for an application prefix, as in myapp_build_info (naming). Several apps exporting a plain build_info share one metric name and differ only by target labels such as job and namespace.
Endpoint
Expose the gauge on the endpoint that is already scraped:
- The Python client's
Infometric doesn't work in multiprocess mode (client_python). AGaugewith labels, set to 1, gives the same series. - A Pushgateway keeps every pushed series until it's deleted (when to use the Pushgateway). If you push anyway, use
PUTwith one grouping key per deployment, which replaces the group's old series (Pushgateway).
kube-state-metrics
kube-state-metrics' kube_pod_container_info carries the image tag, but GKE's managed kube-state-metrics doesn't export it: its allowlist (35 metrics on v2.14.0-gke.51) has neither kube_pod_container_info nor kube_pod_labels.
Image annotations
Annotate pushed images with org.opencontainers.image.revision (the full commit SHA) and org.opencontainers.image.source (the repository URL) (OCI annotations). docker buildx build --annotation key=value writes them to the image manifest by default (Docker: annotations). With --provenance=false that manifest is the top-level object, so no index is needed. docker buildx imagetools inspect --raw <image> shows them.
Headers and endpoints
Leave the version out of response headers, because every public response carries them. OWASP recommends removing headers that reveal technical details, such as Server and X-Powered-By (HTTP headers cheat sheet). ASVS 4.0 requirement 14.3.3 says neither the headers nor any other part of a response may expose detailed version information of system components (ASVS 4.0).
Build a version endpoint only for people who can't reach the cluster or the dashboards. Keep it off the public ingress or behind staff authentication: ASVS 5.0 requirement 13.4.5 says monitoring endpoints must not be exposed unless that is intended (ASVS 5.0).