Notes about the Container format.

The Container format, as popularised by Docker, is in the process of be standardised. This process is happening as an increasing number of tools and services adopt the format.

Containers are typically distributed by registries and Package Origin provides a read-only1 registry.

Package Origin’s focus is on software distribution. The read-only registry is accessible without authentication but no-one can write (push) containers. This makes Package Origin easier to configure and robust by design.

Preparing a Container

Package Origin reads and serves containers from the local file system. Follow these steps to extract a container image from Docker:

  1. Prepare an image with docker;

  2. Tag the image;

  3. Save the image to the local file system as a tar archive:

    docker image save -o example-v1.2.tar example:1.2
  4. Prepare the image to compress the layers:

    packageorign container prepare -o example-v1.2-prepared.tar example-v1.2.tar
  5. Move the prepared archive, example-v1.2-prepared.tar, to a location readable by Package Origin.

Once saved as an archive, the file can be moved across devices and networks without constraint. Package Origin is suitable for air-gapped installations where the preparation and distribution are isolated.

Automatic Coalescing

Package Origin coalesces repositories and tags. A collection of archives containing the same repository, but with different tags, will be presented as a single repository.

An archive containing multiple images is treated as identical to a collection of archives each containing a single image. Both approaches result in the same repositories and tags being presented.

Archives containing different architectures and operating system support will also be coalesced into a single multi-platform repository.

Package Origin does not impose any directory layout or naming convention on the archives.

Inside the Container Archive

The tar archive contains a single required file, manifest.json. This required manifest file contains details of the container image or images within the archive.

Unfortunately, docker does not compress the layers within the archive. Layers are stored as uncompressed tar files within the surrounding tar archive.

Package Origin needs to serve compressed layers and the default archive format contains uncompressed layers.

Uncompressed Layers

When Package Origin encounters a container archive containing uncompressed layers, those layers are extracted, digested, and saved to a local cache directory. Depending on the size of the layers, this process can require a noticeable amount of time; in the order of seconds.

Additionally, the compressed layer in the cache requires storage space on the server.

To avoid this resource burden, Package Origin includes the ability to prepare a container. Passing a container through the preparation process will compress any uncompressed layers.

Compressed Layers

If a container archive contains tar+gzip compressed layers, Package Origin will serve those layers without prior processing or need for the cache.

  1. It appears Package Origin is the first read-only registry; something that caused us to find bugs in the specification’s conformance tests. ↩︎