An image label is a key/value metadata item attached during an image build. Unlike runtime-only settings, it is baked into the image and travels with it when the image is pushed or pulled. section 11.3
Labels provide an audit trail for connecting a running container to the build that produced its image. Common values include application version, build number, and build tag. section 11.3 section 16.2
Add and inspect image labels with the build workflow:
- Declare fixed metadata with Dockerfile LABEL instructions, such as app_version="3.0". section 11.3
- Pass changing build metadata through ARG values, then reference those values in LABEL instructions. section 11.3
- Supply reusable arguments through Docker Compose so local and CI builds can apply consistent labels. section 11.3
- Inspect the resulting metadata with docker image inspect or docker inspect and the image's Config.Labels field. section 11.3 section 16.2
Build metadata in a Dockerfile
A Dockerfile can define ARG BUILD_NUMBER=0 and ARG BUILD_TAG=local, then apply LABEL app_version="3.0", LABEL build_number=${BUILD_NUMBER}, and LABEL build_tag=${BUILD_TAG}. Build with --build-arg BUILD_TAG=ch11 and inspect the labels afterward.
