Loading And Pre-Loading¶
Loading and Pre-loading supports the air-gapped use case of populating the registry in a connected environment, and then moving it into an air-gapped environment.
You can pre-load the cache two ways:
- As a startup task before running the service:
bin/ociregistry serve --preload-images .... The server will load the image cache and then serve. - By using the binary as a CLI:
bin/ociregistry load --image-file .... The executable will load the cache and then exit back to the command prompt.
More details are presented in the Loading Images section of the Configuring The Server page. Since the entirety of the image cache consists of files and sub-directories under the image cache directory, you can tar that directory up at any time, copy it somewhere, untar it, and start an Ociregistry server instance there pointing to the copied directory and it will just work.
Image Store¶
The image store is persisted to the file system. This includes blobs and manifests. Let's say you run the server with --image-path=/var/lib/ociregistry, which is the default. Then:
/var/lib/ociregistry
├── blobs
└── manifests
blobsare where the blobs are stored.manifestsstores the manifests.
Blobs are stored by digest. Manifests are stored by one file named by the SHA-256 digest of the canonical manifest URL. When the server starts it loads everything into an in-memory representation. Each new pull through the server while it is running updates both the in-memory representation of the image store as well as the persistent state on the file system.
Note
As of version 2.0.0 the filesystem layout changed. When you start the server (via the serve subcommand) or when you use the migrate-cache sub-command the pre-2.0.0 manifests in img and lts are migrated to manifests and a marker is written. The img and lts directories remain until you remove them but the server will not "see" those directories after migration to the 2.0.0 storage scheme.
The software uses a data structure called a ManifestHolder to hold all the image metadata and the actual manifest bytes from the upstream registry. These are simply serialized to the file system as JSON. (So you can find and inspect them if needed for troubleshooting with grep, cat, and jq.)
A ManifestHolder looks like this:
type ManifestHolder struct {
Type ManifestType
Digest string
ImageUrl string
Bytes []byte
V1ociIndex v1oci.Index
V1ociManifest v1oci.Manifest
V2dockerManifestList v2docker.ManifestList
V2dockerManifest v2docker.Manifest
Created string
Pulled string
}
The Bytes field has the actual manifest bytes from the upstream. You can see the supported manifest types: V1ociIndex, V1ociManifest, V2dockerManifestList, and V2dockerManifest.
Loading behavior¶
Loading is additive, meaning if you run the load command to load 100 images, then run it again to load 100 different images, your image cache will have 200 images. If you load 100 images, and then later load the same 100 images again, the server will detect during the second load that there is nothing to do. And of course, if you first load A, B, and C, and then later load C, D, and E, then the cache will hold A, B, C, D, and E.
Canonicalization¶
The server canonicalizes images on intake:
- For every registry the registry host and repository are lowercased, and so is a digest; tags keep their case
- For legacy reasons it is possible to pull
docker.io/hello-world:latesteven though the canonical url isdocker.io/library/hello-world:latest. Since canonicalization happens in ontake, it is always possible to re-pulldocker.io/hello-world:latesteven though internally it is cached with thelibrarysegment.