Container vocabulary often collapses several independent contracts into the word “Docker.” That makes incidents harder to localize. An image can be valid while a registry denies access, a runtime rejects configuration, or Kubernetes schedules the wrong platform variant.
Quick answer
The OCI Image Specification describes image manifests, indexes, configurations, layers, and descriptors. The Distribution Specification defines registry transfer behavior. The Runtime Specification defines the filesystem bundle and process configuration used by a low-level runtime. Docker builds and distributes OCI-compatible artifacts; containerd or CRI-O can manage runtime work; Kubernetes communicates through CRI and reconciles Pods. These are related layers, not synonyms.
Learning objectives
- Distinguish image content, registry distribution, runtime execution, CRI integration, and Kubernetes orchestration evidence.
- Use digest and platform metadata to identify exactly what artifact a production Pod attempted to run.
Prerequisites
Start with Production Cloud-Native Backend Systems. Browse the full Cloud-Native Backend course and topic cluster.
Artifact identity and platform selection
An OCI descriptor points to content with a digest, media type, and size. A manifest describes configuration and filesystem layers for one platform. An image index can reference manifests for several operating-system and architecture combinations. A registry tag is a mutable name that resolves to a manifest; the digest is the content identity used for immutable promotion.
At runtime, an implementation fetches the selected content, verifies digests, unpacks layers into a root filesystem, and starts the configured process with namespaces, mounts, capabilities, and resource settings. Kubernetes declares desired containers but delegates low-level execution through the node runtime integration.
commit -> build -> OCI index/manifest + layers -> registry
-> kubelet/CRI -> runtime bundle -> process in a PodProduction failure scenario
The team tests an amd64 image, then promotes a multi-platform tag. An index entry for arm64 references an older manifest missing the application binary. Some nodes run correctly while others enter a start failure. The tag name looks identical everywhere.
Inspect the Pod node architecture, resolved image ID, index entries, and manifest digests. Repair the incorrect platform artifact and promote a reviewed digest. Restarting or rescheduling without checking platform identity can merely move the symptom.
Common misconceptions
- A tag is not immutable provenance.
- OCI does not mean every runtime implements every optional feature identically.
- Docker Engine, containerd, runc, CRI, and Kubernetes are not interchangeable names.
- A successful pull does not prove the configured process can start or serve traffic.
- A scanner result for one manifest does not automatically cover every platform in an index.
Decision checklist
- Record the exact image index or manifest digest promoted to each environment.
- Verify all declared platform variants, not only the developer workstation architecture.
- Keep registry authentication, content integrity, runtime configuration, and application startup as separate gates.
- Inspect resolved image identity on the Pod before diagnosing source code.
- Retain artifact provenance and SBOM relationships by immutable digest.
Continue with Production Container Images, Dockerfiles, and Supply Chain.
Related reading
- Production Cloud-Native Backend Systems places artifact identity in the full release evidence chain.
- Production Container Images, Dockerfiles, and Supply Chain applies OCI identity to a reviewable build.
- Kubernetes Pods, Deployments, and Services continues from runtime execution into workload reconciliation.
Official sources
- OCI Image Specification, accessed August 18, 2026.
- OCI Distribution Specification, accessed August 18, 2026.
- OCI Runtime Specification, accessed August 18, 2026.
- Kubernetes container runtimes, accessed August 18, 2026.