The Distribution Spec

Table of contents

  1. Details

Distribution:

the action of sharing something out among a number of recipients.

Distribution, or sharing of container images, is just as important as building them in the first place. If you can’t easily distribute your container, you lose a lot of the benefits that we outlined in the first place.

Generally, you can think of distribution eco-system as having different use cases. I should be able to easily:

  • share: the container images that I create, across hosts, institutions, and time zones.
  • search: I should be able to find the container that I’m looking for.
  • obtain: If I find a container, and given I have permission to do so, I should be able to get it
  • verify: that the container I requested is the one that I wanted, and not some malicious entity.

Generally, a distribution comes down to a strategy that includes software, servers, and databases to fulfill these goals. The distribution specification helps to outline a lot of the interactions to make this possible.

Details

The distribution specification describes the API that might be used by a registry to distribute images. This means actions like pull, push, along with how images are named, and errors are presented. You can think of the distribution specification as a collection of endpoints served by a registry to communicate with. Do you want a manifest? Use the manifest endpoint:

GET /v2/<name>/manifests/<reference>

Do you want to upload a blob? There is an endpoint to POST to for that:

POST /v2/<name>/blobs/uploads/

Where would I find a distribution specification?

An implementation of this specification would be found with a container registry that implements the OCI standard. For example, Docker Hub implements the specification. A developer could also roll their own registry (such as this one) that implements it.

What would I do with the distribution specification?

The specification outlines a method of interaction. If you are writing a client, for example, these are the endpoints that the client would use. If you are creating a new registry that you wanted to conform to OCI, these are the API endpoints you would implement.

How might I contribute to the distribution specification?

Generally, since the goals are to move (push and pull) images, and provide endpoints for a client, if you are designing a registry or a client and find that you are missing some key function of an endpoint, or information provided by an endpoint, you might want to suggest a change to the specification.