Title here
Summary here
Caching Configuration
This page is the technical reference for the on-disk caches OCM uses when it reads component versions from OCI registries.
No dedicated configuration type
OCM has no caching configuration type. The CLI and the controller enable caching by default, and the limits and remote policy are fixed. The only thing you can set is where the cache lives, through the temporary folder described in Cache Location.
Caches
OCM keeps two caches for OCI component version repositories. Both are stored on disk, so their contents survive between runs of the CLI and restarts of the controller.
| Cache | Key | Content | Scope |
|---|---|---|---|
| Blob cache | Blob digest | Manifests, indexes, and component descriptors | Shared by all registries and repositories in the process |
| Reference cache | Registry, repository, and tag or digest | The descriptor that a tag or digest resolves to | One cache per repository |
The blob cache stores content by digest, and a digest always identifies the same bytes. That makes it safe to share the blob cache between repositories and credentials. OCM checks every fetched blob against its digest before it writes the blob to disk.
The reference cache has one instance per repository location (hostname[:port]/path). Credentials are not part of
the key, so rotating short-lived tokens does not make the cache useless. Use the Always remote policy
when every access must be authorized by the registry.
Resource layers, such as the image layers of an OCI image resource, are not cached. Only the blobs listed in Admission Rules are cached.
Cache Location
Both caches are stored under the OCM temporary folder:
| Cache | Directory |
|---|---|
| Blob cache | <tempFolder>/ocm-oci-cas/blobs/<algorithm>/<hex> |
| Reference cache | <tempFolder>/ocm-oci-refcache/<repository-key>/refs/<sha256(namespace)>.json |
<repository-key> is the first 16 hex characters of the SHA-256 of hostname[:port]/path. namespace is
<registry>/<repository>. Each reference cache file stores the resolved descriptors of one namespace together
with the time each descriptor was resolved.
The directory names do not change between runs. Every OCM process that uses the same temporary folder reads and writes the same cache.
Temporary Folder in the CLI
The CLI takes the temporary folder from the first of these that is set:
- The
--temp-folderflag. - The
tempFolderfield of thefilesystem.config.ocm.software/v1alpha1configuration type. - The temporary directory of the operating system (Go
os.TempDir). On Linux and macOS this is$TMPDIR, or/tmpif$TMPDIRis empty. On Windows it is the first of%TMP%,%TEMP%,%USERPROFILE%, or the Windows directory.
If both the flag and the configuration field are set, the CLI uses the flag and logs a warning.
type: generic.config.ocm.software/v1
configurations:
- type: filesystem.config.ocm.software/v1alpha1
tempFolder: /var/cache/ocmThe same temporary folder is also used for other short-lived files, for example extracted CTF archives, downloaded resource content, and the temporary GnuPG home directories of GPG signing and verification.
filesystem.config.ocm.software/v1alpha1 Fields
| Field | Type | Default | Description |
|---|---|---|---|
tempFolder | string | Operating system temporary directory | Directory for short-lived files and for the OCI caches. |
workingDirectory | string | Current working directory | Base directory for resolving relative file paths. Not related to caching. Overridden by the --working-directory flag. |
If the configuration file contains more than one filesystem.config.ocm.software/v1alpha1 entry, the last value set
for each field wins.
Temporary Folder in the Controller
The controller does not accept filesystem.config.ocm.software (see
OCM Controllers). It always uses the temporary directory of the
operating system, so the cache is stored under $TMPDIR (or /tmp) of the controller container.
If the root filesystem of the container is read-only, mount a writable volume at that path, or set TMPDIR to a
writable volume. If the cache directory cannot be created, the controller logs a warning and continues without caching.
Limits
Each cache applies these limits:
| Limit | Value | Applies to | Behaviour |
|---|---|---|---|
| Maximum entries | 256 | Blob cache, each reference cache | When the limit is reached, the least recently used entry is removed. |
| Time to live | 10m | Blob cache, each reference cache | Entries older than this are removed. |
| Maximum blob size | 4 MiB | Blob cache | Larger blobs are downloaded as usual but not cached. |
When the blob cache removes an entry, it also deletes the file. When a reference cache is loaded from disk,
entries resolved more than 10m ago are not loaded. When the blob cache is loaded from disk, every valid file is
loaded and gets a new time to live, because content addressed by digest cannot become stale.
Admission Rules
The blob cache stores a blob only if its media type is one of:
- an OCI or Docker manifest or index media type;
- the OCM component config media type;
- an OCM component descriptor media type (any media type that starts with
application/vnd.ocm.software.component-descriptor, which includes legacy v1 and+tarvariants).
All other blobs are downloaded from the registry every time.
Remote Policy
The remote policy decides whether OCM contacts the registry when it finds an entry in the cache. It is fixed per component:
| Component | Policy |
|---|---|
| CLI | IfNotPresent |
| Controller | Always |
| Policy | Blob cache hit | Reference cache |
|---|---|---|
IfNotPresent | Returns the cached blob without contacting the registry. | Returns cached results for digest references. Tags are always resolved against the registry. |
Always | Checks that the blob exists and is accessible in the registry, then returns the cached blob without downloading it again. If the check fails, the fetch fails. | Always resolves against the registry and updates the cache with the result. |
With IfNotPresent, anyone who can read the cache directory can read cached manifests and component descriptors
without registry access. On macOS $TMPDIR is per user, but on Linux the default /tmp is shared by all users. On
shared machines, set tempFolder or --temp-folder to a directory that only you can read.
With Always, the controller asks the registry to authorize every access, but does not download cached content again.
A tag that has been moved to a new digest is never served from the cache under either policy, because tags are always resolved against the registry.
Clearing the Cache
It is safe to delete <tempFolder>/ocm-oci-cas and <tempFolder>/ocm-oci-refcache at any time when no OCM process
is running. OCM creates the directories again on the next run. If a cached file is missing while OCM is running, OCM
treats the entry as a cache miss and downloads the content again.
Related Documentation
- HTTP Client Configuration — timeouts and retries for requests that miss the cache
- Resolver Configuration — configuration types in the same file
- OCM Controllers — configuration types the controller accepts
ocmCLI reference — global flags, including--temp-folder