Instruction 03-image-version-pinning-and-controlled-updates: Reading

Container tags are convenient names, but they are usually mutable pointers. If a deployment records only academy/demo:stable, the bytes selected tomorrow may differ from the bytes selected today even though the text of the deployment reference has not changed. Digest pinning changes the final identity to a content-addressed reference such as academy/demo@sha256:ba7816bf..., making an unnoticed tag move insufficient to alter the deployed identity.

Multi-platform images add an important distinction. A channel or tag commonly resolves to an OCI image index. The index is not the same object as the image manifest used by a linux/amd64 node. The index contains descriptors for multiple platforms, and the client selects one matching the requested operating system and architecture. A policy intended to approve the runnable linux/amd64 artifact must therefore compare the digest of the selected linux/amd64 manifest, not merely a tag and not an unrelated platform descriptor. The lab registry models this explicitly: stable points to index-v2, index-v2 points to linux/amd64 and linux/arm64 manifests, and the deployment pin uses the selected linux/amd64 manifest digest.

Content hashing and authorization answer different questions. Recomputing a catalog-provided digest can detect accidental corruption when the declared digest and bytes no longer agree, but a party able to replace both the content and the digest can create a new self-consistent pair. A local policy file stored beside the catalog also does not solve that boundary if the same party can edit both files. For that reason, update.py requires an expected channel, platform, and digest supplied independently at invocation time. It checks the requested tuple, resolves the catalog index, selects exactly one matching platform descriptor, verifies the selected blob against the descriptor, compares the selected digest with the out-of-band expected digest, and then confirms local policy approval. Any mismatch is rejected before deployment, backup, or audit state is written.

The lab uses the published SHA-256 test vectors for the exact bytes abc, hello, and the empty byte string. Their literal golden values are included in the lesson and verification commands. This avoids relying solely on values generated by the setup code or by update.py. The dry-run and rejection tests also compare complete deployment and audit files before and after each attempt. A successful promotion creates a retained backup, atomically replaces deployment.json, and appends an audit event linking the previous digest to the new digest. Rollback copies the failed deployment aside, validates the retained backup against both an out-of-band rollback digest and local approval, copies rather than moves the backup into place, verifies the restored state, and only then appends the rollback event.