Open Container Initiative (OCI) Specifications


OCI has two specs, an Image spec and a Runtime spec.

Image Specification (image-spec)

Image specification defines the archive format of OCI container images, which consists of a manifest, an image index, a set of filesystem layers, and a configuration. The goal of this specification is to enable the creation of interoperable tools for building, transporting, and preparing a container image to run.

├── blobs
│ └── sha256
│ ├── 4297f0* (image.manifest)
│ └── 7ea049 (image.config)
├── index.json
└── oci-layout


For layers, the specification essentially defines two things:

  1. How to represent a layer.
  • For the base layer, tar all the content;
  • For non-base layers, tar the changeset compared with its base.
  • Hence, first detect the change, form a changeset; and then tar the changeset, as the representation of this layer.
  1. How to union all the layers.

Runtime Specification (runtime-spec)

Once the Image is unpacked to a runtime bundle on the disk file system, you will have something that you can run. This is when the Runtime Specification kick in. The Runtime Specification specifies the configuration, execution environment, and lifecycle of a container.

Container Lifecycle

A container has a lifecycle, at its essence, as you can imagine, it can be modeled as following state diagram.

Container Configurations

We mentioned before that a container’s configuration contains the config necessary to create and run a container. And we will look at some of the configs a little bit closer to get a sense of what is container really about, and we’ll focus on Linux platform for all the configurations.

  1. Root
    It defines the root file system of the container.
  2. Mounts
    It specifies addition filesystem you can mount into the root file system. This is the place you can either bind mount your local host dir or a distributed dir, such as Ceph.
  3. Process
    It specifies all the things related to the process that you want to run inside the container. It includes environment variable and the arguments to the process.
  1. Hooks
    This is the place you can hook up into the container lifecycle and do things such as setting up and/or clean up the network.
  2. Linux Namespaces
    A whole lot of configurations for Linux platform is dedicated to the Namespace configuration. Actually, namespaces are the foundations of container technology. Or put it another way, there is will be no container without namespaces. Linux provides seven type of namespaces and they are all supported by the OCI runtime specification:NamespaceDomain / DescriptionPIDProcess IDsMountMount pointsNetworkNetwork devices, stacks, ports, etc.UserUser and group IDsIPCSystem V IPC, POSIX message queuesUTSHostname and NIS domain name
  3. Annotations
    In addition to what and how the container should be run. Annotations allow you to label the containers. The ability to label and select the container base on some properties is the basic requirement for a container orchestration platform.

Image, Container, and Processes

Containers are created from (container) Image. You can create more than one containers from a single Image, and you can also repack the containers, usually with changes to the base image, to create a new Image.

Docker and Kubernetes

Docker makes container an industry trend and there are a lot of people who consider Docker as container and container as Docker. Docker definitely deserves the credit here. But from the technical point of view, Docker is the most widely used container implementation. The architecture of the Docker implementation evolves very quickly from version to version. At the time of writing, it looks like below.

Container Orchestration

If we only need to one or two containers, Docker probably is all we need. But if we want to run dozens or thousands of containers we have more problems to solve. To name a few:

  1. Scheduling: Which host to put a container?
  2. Update: How to update the container image?
  3. Scaling: How to add more containers when more processing capacity is needed?


This is an overview of OCI container image and runtime specifications. It covers the responsibility of each specification and how they cooperate with each other. We go over the container lifecycle and primary configurations for the runtime spec. And we then introduce the relationship between Docker and runc, and finish the article with a brief introduction to container orchestration and how the container runtime fit into it.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Alibaba Cloud

Alibaba Cloud

Follow me to keep abreast with the latest technology news, industry insights, and developer trends. Alibaba Cloud website: