Container image layers and build cache: reuse, invalidation and secrets
Explain image layers and Docker cache invalidation, then design a build that reuses dependencies without preserving secrets or stale packages. Diagnose unexpectedly slow rebuilds.
TL;DR: Image layers describe filesystem changes; build cache reuses prior instruction results when their inputs match. Order stable inputs before frequently changing ones, and keep secrets out of image layers and ordinary build arguments.
A filesystem view is assembled from layers
An image can contain multiple immutable filesystem layers plus configuration and metadata. A container adds a writable layer for its own filesystem changes. Deleting a file in a later image layer changes the assembled view but does not erase the file's bytes from an earlier distributed layer.
Docker's image-layer explanation covers this model. It explains why copying a private key into an image and deleting it in a later step is not a safe secret-handling strategy.
Build cache is related but distinct. The builder can reuse results for unchanged instructions and inputs. An instruction that executes a package manager does not necessarily rerun just because a package repository has changed since the previous build.
This is an illustrative build dependency graph. Multi-stage builds can have branches and selective reuse; do not assume every Dockerfile is a single linear chain.
Worked optimization: source edits reinstall everything
Suppose an application build copies the entire repository before installing dependencies. A documentation edit changes the copied inputs, so the dependency-install step cannot reuse the previous result. The build spends minutes repeating work unrelated to the changed application behavior.
Copy dependency manifests and the lockfile first, perform the locked install, then copy relevant application source. Exclude unrelated files through a reviewed .dockerignore. Confirm the reordered steps still include inputs that genuinely affect dependency installation, such as required workspace manifests or package-manager configuration.
The improvement is valid only if the dependency contract is complete. Omitting an installation input can produce fast but incorrect cache hits. Test both a source-only change and a dependency change; the former should reuse the intended cache while the latter should invalidate it.
Docker's cache-invalidation reference explains input matching and secret-related behavior. Cache validity means inputs match the builder's model. It does not certify that the resulting software is current or secure.
| Change | Expected investigation | Common misconception |
|---|---|---|
| Application source edit | Which copy step first consumes it? | Every dependency must reinstall |
| Lockfile update | Does dependency installation invalidate? | Same package names mean identical content |
| Base image update | Is the desired base actually selected? | A mutable tag identifies immutable bytes |
| Remote package repository changes | Is a rebuild or explicit refresh required? | Cached RUN detects remote changes automatically |
| Build secret rotation | Does the operation require cache invalidation? | Secret contents always change the cache key |
Secrets need a separate channel
Use supported build-secret mounts for credentials needed during a build. Do not place them in ordinary ARG, ENV, copied files or committed configuration. A secret mount avoids automatically baking the secret into the layer, but the command using it can still leak it by writing logs or output files.
Docker's build-secret guide describes the mechanism. Review the tool invoked inside the build too: a package manager may persist authentication configuration unless explicitly configured otherwise.
If changing a secret should cause a fetch step to rerun, use an intentional nonsecret cache invalidation input under the documented builder behavior. Never use the secret value itself as a visible cache-busting argument.
Reproducibility and freshness require policy
Promote the same verified image digest through environments, as discussed in artifact identity. Schedule deliberate dependency and base-image refreshes instead of hoping that every build accidentally discovers upstream changes.
A clean rebuild and a cached rebuild should produce behavior consistent with the intended source and dependency inputs. Where byte-for-byte reproducibility is a requirement, investigate timestamps, network fetches and nondeterministic compilation separately. Cache success alone does not prove reproducibility.
Also protect shared caches. A cache imported from an untrusted source can become part of the software supply chain. Define who may publish it and which builders may consume it.
Does deleting a secret in a later layer remove it from the image history? No. Prevent the secret from entering the layer in the first place and respond to any exposure as a credential incident.
What should a cache optimization demonstrate? Correct reuse for unchanged inputs and correct invalidation for changed inputs, with the resulting image tested. A faster build that omits a dependency input is a correctness regression.