Caching

This page is the technical reference for the on-disk caches OCM uses when it reads component versions from OCI registries.

What you can configure

The CLI and the controller enable caching by default, and the limits are fixed. You can set where the cache lives, through the temporary folder described in Cache Location, and the remote policy.

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.

The controller uses only the blob cache. One instance serves every namespace.

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-folder flag.
The tempFolder field of the filesystem.config.ocm.software/v1alpha1 configuration type.
The temporary directory of the operating system (Go os.TempDir). On Linux and macOS this is $TMPDIR, or /tmp if $TMPDIR is 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/ocm

The same temporary folder is also used for other short-lived files, for example extracted CTF archives and downloaded resource content.

`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 does not start.

Limits

Each cache applies these limits:

Limit	Value	Applies to	Behaviour
Maximum entries	`100000` (blob), `10000` (each reference)	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	`20 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 +tar variants).

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. The default is IfNotPresent for both the CLI and the controller.

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, OCM 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.

Remote Policy in the CLI

Set the policy with the oci.cache.config.ocm.software/v1alpha1 configuration type. It applies to the blob cache and every reference cache.

type: generic.config.ocm.software/v1
configurations:
  - type: oci.cache.config.ocm.software/v1alpha1
    remotePolicy: Always

remotePolicy defaults to IfNotPresent. Any value other than IfNotPresent or Always makes the CLI fail, even if a later entry overrides it. If the configuration file contains more than one oci.cache.config.ocm.software/v1alpha1 entry, the last remotePolicy that is set wins.

The schema below defines the full structure of the oci.cache.config.ocm.software/v1alpha1 type as specified by JSON Schema 2020-12.

Remote Policy in the Controller

The controller does not accept oci.cache.config.ocm.software in spec.ocmConfig for individual objects. One blob cache serves every namespace so a single object should not be able to configure it. Instead, set the policy for the whole controller with the manager.ocmConfig Helm value like this:

manager:
  ocmConfig:
    configurations:
      - type: oci.cache.config.ocm.software/v1alpha1
        remotePolicy: Always

The chart stores this configuration in a ConfigMap, mounts it into the controller, and passes it with the --ocm-config flag automatically. type defaults to generic.config.ocm.software/v1. The controller reads the file once at startup. The chart sets a checksum/ocm-config annotation on the controller pods, which Helm computes when it renders the chart. A helm upgrade that changes manager.ocmConfig therefore restarts the pods. Editing the ConfigMap directly, for example with kubectl edit, restarts nothing: the controller picks up the change only on its next restart.

oci.cache.config.ocm.software is the only type accepted here. Any other type, or an invalid remotePolicy, results in a startup error.

IfNotPresent shares cached content across namespaces

The blob cache key is the digest, not the credentials. With IfNotPresent, a blob that one namespace fetched with its credentials is, potentially, read from the cache by another with the same digest, but no credentials. On a cluster where namespaces MUST NOT read each other’s blobs, use Always. Every cache hit is then checked against the registry with the credentials of the requesting object.

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.

Reference: HTTP Client Configuration - timeouts and retries for requests that miss the cache
Reference: Resolver Configuration - configuration types in the same file
Concept: OCM Controllers - configuration types the controller accepts
Reference: ocm CLI reference - global flags, including --temp-folder

Canonical Component Repositories

Caching

Caches#

Cache Location#

Temporary Folder in the CLI#

filesystem.config.ocm.software/v1alpha1 Fields#

Temporary Folder in the Controller#

Limits#

Admission Rules#

Remote Policy#

Remote Policy in the CLI#

Remote Policy in the Controller#

Clearing the Cache#

Related Documentation#

Caches

Cache Location

Temporary Folder in the CLI

`filesystem.config.ocm.software/v1alpha1` Fields

Temporary Folder in the Controller

Limits

Admission Rules

Remote Policy

Remote Policy in the CLI

Remote Policy in the Controller

Clearing the Cache

Related Documentation