image-spec Documentation

Go containers & docker repository by @opencontainers. Docker Compose & container deployment with 4.3k stars.

4,264 stars Go Go 1 file · ~11,912 tokens #containers#docker#oci
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy image-spec on any server, homelab, or cloud container platform.

1. Project Overview & Quickstart (opencontainers/image-spec)

OCI Image Format Specification

The OCI Image Format project creates and maintains the software shipping container image format spec (OCI Image Format).

The specification can be found here.

This repository also provides Go types, intra-blob validation tooling, and JSON Schema.
The Go types and validation should be compatible with the current Go release; earlier Go releases are not supported.

Additional documentation about how this group operates:

Running an OCI Image

The OCI Image Format partner project is the OCI Runtime Spec project.
The Runtime Specification outlines how to run a "filesystem bundle" that is unpacked on disk.
At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.
At this point the OCI Runtime Bundle would be run by an OCI Runtime.

This entire workflow supports the UX that users have come to expect from container engines like Docker and rkt: primarily, the ability to run an image with no additional arguments:

  • docker run example.com/org/app:v1.0.0
  • rkt run example.com/org/app,version=v1.0.0

To support this UX the OCI Image Format contains sufficient information to launch the application on the target platform (e.g. command, arguments, environment variables, etc).

Distributing an OCI Image

The OCI Distribution Spec Project defines an API protocol to facilitate and standardize the distribution of content.
This API includes support for pushing and pulling OCI images to an OCI conformant registry.

FAQ

Q: What happens to AppC or Docker Image Formats?

A: Existing formats can continue to be a proving ground for technologies, as needed.
The OCI Image Format project strives to provide a dependable open specification that can be shared between different tools and be evolved for years or decades of compatibility; as the deb and rpm format have.

Find more FAQ on the OCI site.

Roadmap

The GitHub milestones lay out the path to the future improvements.

Contributing

Development happens on GitHub for the spec.
Issues are used for bugs and actionable items and longer discussions can happen on the mailing list.

The specification and code is licensed under the Apache 2.0 license found in the LICENSE file of this repository.

Discuss your design

The project welcomes submissions, but please let everyone know what you are working on.

Before undertaking a nontrivial change to this specification, send mail to the mailing list to discuss what you plan to do.
This gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits.
It also guarantees that the design is sound before code is written; a GitHub pull-request is not the place for high-level discussions.

Typos and grammatical errors can go straight to a pull-request.
When in doubt, start on the mailing-list.

Meetings

Please see the OCI org repository README for the most up-to-date information on OCI contributor and maintainer meeting schedules.
You can also find links to meeting agendas and minutes for all prior meetings.

Mailing List

You can subscribe and join the mailing list on Google Groups.

Markdown style

To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line.
This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length.
For example, this paragraph will span three lines in the Markdown source.

Git commit

Sign your work

The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch.
The rules are pretty simple: if you can certify the below (from developercertificate.org):

text
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

then you just add a line to every git commit message:

text
Signed-off-by: Joe Smith <[email protected]>

using your real name (sorry, no pseudonyms or anonymous contributions.)

You can add the sign off when creating the git commit via git commit -s.

Commit Style

Simple house-keeping for clean git history.
Read more on How to Write a Git Commit Message or the Discussion section of git-commit(1).

  1. Separate the subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how
    • If there was important/useful/essential conversation or information, copy or include a reference
  8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...")

2. Official Technical Reference & Guides (opencontainers/org)

File: README.md

OCI Organization

Centralized documents and information for the Open Containers Initiative (OCI) organization and projects.

Charter

See the founding charter

Code Of Conduct

See CODE_OF_CONDUCT.md

Communications

All communications are subject to our CODE_OF_CONDUCT.md

Meetings

The contributors and maintainers of all OCI projects have weekly meetings every Wednesday at 2:00 PM (USA Pacific).

Based on activity and project needs, meetings may return to a lower frequency in the future; for example twice or once a month. This README will be updated as well as the iCal entry below if and when that occurs.

You can also download meeting details as an iCalendar format invite or view the full Google Calendar.

Meetings are held via Zoom; the join URL and call-in details are as follows:

Meeting URL: https://zoom.us/my/opencontainers

Join via phone:

text
One tap mobile:
+16465588656,,6449415895# US (New York)
+16699006833,,6449415895# US (San Jose)

Dial by your location
        +1 646 558 8656 US (New York)
        +1 669 900 6833 US (San Jose)
        877 369 0926 US Toll-free
        855 880 1246 US Toll-free
Meeting ID: 644 941 5895
Find your local number: https://zoom.us/u/aLDk4OXTu

We currently use HackMD to pre-announce agenda items, record attendance and meeting minutes. Anyone is free to edit the HackMD OCI meeting document and add agenda items, record your attendance, or help record minutes and notes from the weekly call.

Minutes archives

Mailing List

You can subscribe and join the mailing list on Google Groups.

IRC

OCI discussion happens on #opencontainers on Freenode (logs).

Slack

In addition to IRC, Slack provides discussions with markdown formatting, with several channels enabling focused discussions.

Gain access to OCI Slack here: Slack inviter

Technical Oversight Board (TOB)

The TOB is responsible for managing conflicts, violations of procedures or guidelines and any cross-project or high-level issues that cannot be resolved in the TDC for OCI Projects.
The TOB shall also be responsible for adding, removing or reorganizing OCI Projects.

Archived minutes from TOB meetings can be found in meeting-notes/tob.

Security

See the security doc for reporting process and disclosure communications.

License

Unless otherwise noted, code and docs of OCI projects are released under the Apache 2.0 license.

File: docs/docs/contributing/contributing.md

Contributing

{: .no_toc }

Table of contents

{: .no_toc .text-delta }

  1. TOC
    {:toc}

Open Container Initiative Contributions

Before you are ready to contribute, make sure that you understand:

  1. What are the different OCI specifications, on an abstract level?
  2. What are applied usage examples of the specifications?
  3. How do I ask for help or clarification?

You can have a gentle introduction to containers [here]({{ site.baseurl }}/introduction/container-images/), and read about the OCI types [here]({{ site.baseurl }}/introduction/oci-projects/).

Kinds of contribution?

When you understand what a container is, and what the goals are behind each of the specifications provided by OCI, you are then in the right mindset to contribute.
Generally, you might fit into one of the following scenarios:

  1. Definition You have a goal or need that is not addressed by a specification.
  2. Documentation An idea or concept is not explained enough for you to use it.
  3. Feature Request You have a new idea for an extension to a specification.

To serve these various contribution use cases, we have an issue tracker with templates to guide you through the contribution process.
Each contribution request, whether it be asking a question or a feature, will happen via discussion on the issue board. The final decision for a request might result in the opening of new issues on other opencontainers boards, per the collaborative discussion and decision of those involved.

We have provided several templates to help guide you in your question, issue, or feature request. Open an issue to get started with the process.
Now let's walk through what interactions and discussions on the issue tracker might look like.

How do I Contribute?

1. Develop an Idea

You are on this page in first place, and reading about how to contribute, because you found a hole that isn't addressed by the specification, or have an idea for an extension to make it better.
The first thing you should do is grab your computer, go to a comfortable working spot, and write.
What is your use case or need? How did you try to use current software that implements OCI (and how did it fail?)
Tell your problem like a story.
It may be easier for experts and non-experts alike to follow your train of thought, and understand the issue you are trying to address.
If you fail to capture their understanding off the bat you may have a hard time getting support for change.

2. Discussion

Once you've written up your idea, post it to the issue tracker.
You might also post to the development list to capture people's attention, and point them to your issue.
Why would you want to use the issue tracker in combination with the list?
The issue tracker will allow you to keep a clean record of progress.
You can easily link to code you are working on, and the discussion.
It's a central place for all the things.
The mailing list is important for reach and perspective.
You can challenge others that have different use cases for interaction with containers to give feedback on your idea.

3. Support and Action

Once discussion starts to die down, it's important to try and synthesize the content discussed into a concrete action.
The maintainers will likely be doing this without thinking about it. For example:

  • Documentation Action if there is functionality you thought was missing and it actually existed? This calls for an improvement to the documentation. The maintainer can assign issues to developers to address your concern, and ask for your feedback.
  • Show Me Action: The most likely result of you wanting a new thing will be a request for a dummy implementation. It doesn't need to be perfect, but you must show that your idea has feet, and solves the problem that you stated.
  • Feature Request Action It could be that your idea was succinct and strong, and a new feature is called for development. This likely will result in one or more developers (including you!) coming up with a plan of action. This is less likely an option, because changes to the specifications tend to be more conservative.

Generally, you will want to find support for your action, whether it be advice or actual help from others in the list.
We do this step before detailed feedback in the case that your idea doesn't need further investigation (already solved or being worked on, for example).
What should never happen is anything that goes against the code of conduct.
You should not be put down, ridiculed for your ideas, or otherwise have someone treat you poorly.

4. Detailed Feedback

After you've posted your idea to the list, I can almost guarantee you someone else will be interested or
excited to give you feedback.
The list (or a GitHub issue) itself isn't really the place to hash out the details.
Your final post on the discussion might be to share a link to a more formal write up of your idea.
You probably already have it written into a document, and it makes sense to share this writeup with others for feedback (Google Docs, GitHub markdown, HackMD, etc.).
How long should you wait to get feedback?
This is up to you.
Make sure to give others credit and thanks for their contribution.
If it's on GitHub, use an AUTHORS.md file.
If it's a Google Doc, allow collaborators to write their name in a section, if desired.
It's important to stress that the idea is a group effort.
At this point, since you have others' attention, you might want to consider creating a working group to continue progress on your idea.
What is a working group? It can be a small email list, a group of contributors subscribed to a common repository, or a slack channel.
It's basically a way to communicate, and that way should be your preferred method(s).

5. Implementation

Great! You now have created the idea, posted to the list, and you are tracking progress on the GitHub issue tracker.
Here is the fun (and challenging) part. You need to show that your idea has feet.
This comes down to a dummy implementation that, paired with your writeup, can tag team to convince others of your idea.
This step will likely require several iterations. When you present your work to the OCI maintainers again, you need to stress the following points:

  1. Restate the problem, and what you couldn't previously do to lead to your idea
  2. Show them what is now improved, and possible, with your approach.
  3. Be transparent about limitations. Ask again for feedback and help to address them.

6. Contribution to OCI

Given a strong idea, a proof of concept, and support, the discussion might next move to how and when the idea can be integrated with OCI, or it could serve as a tool to supplement it.
This final stage will vary depending on the proposal.

File: docs/docs/introduction/container-images.md

layout: default title: Container Images nav_order: 2 parent: Introduction

Introduction to Containers

A container is a portable encapsulation of an environment 1.
It's a way for you to package an entire operating system, libraries, and software into a package that you can move and run anywhere.
That is the quick and dirty definition, but today we are going to delive a little more into what this actually means.

{: .no_toc }

Table of contents

{: .no_toc .text-delta }

  1. TOC
    {:toc}

Container Basics

What problems do containers solve?

Reproducibility

{: .no_toc }

We have differences in environments, hardware, and even security, and this makes sharing of applications challenging.
A reproducible workflow that uses containers helps us get around this problem, and (hopefully) reduce the frequency of uttering the phrase But it ran on my computer!

Portability

{: .no_toc }

The ability to easily move a container from one machine to another is easily afforded by the fact that many container formats are variations on a compressed filesystem.
If you wanted to share your entire computer, right now, you would have a hard time doing that.

Development Environments

{: .no_toc }

It used to be the case that to develop a simple model - view - control (MVC) application with some application, database, and web server, you would need to install and run the components on your host.
It would be very challenging to work on multiple projects at once, because different projects might have different dependencies.
Containers are essential for developers because they allow us to spin up an entire set of components for a specific development environment, and then bring it down just as easily.

Continuous Integration

{: .no_toc }

The same is true for testing, using containers one can easily test across operating systems from a single host.

Flexible

{: .no_toc }

The technologies that we use must be flexible to change.
The resources that we invest in are ephemeral, and change is unavoidable.
For a concrete example. let's say you are running a complex (containerized) application on a cloud provider.
The costs of the provider changes, and you need to do a quick switch!
Since your application is containerized, you can easily change providers.
You aren't forced becoming locked into a cloud vendor. You are a free container whale!

Isolation

{: .no_toc }

While the level of isolation can vary based on the container technology, containers generally allow you to isolate an application or component from your host.
This is incredibly useful if you have packages with conflicting dependencies that need to run on the same host.

Virtualization

{: .no_toc }

You might be familiar with the idea of a virtual machine (VM), which was, for some of us, our first foray into virtualization. In a bucket:

  • A hypervisor is based on emulating hardware.
  • When we emulate hardware, this is called virtualization.

While the term "virtual machine" is used in different contexts and can spawn much disagreement about its definition, for the time being let's abstractly talk about the differences between containers and hypervisors.
The biggest difference was already stated - hypervisor emulation is based on emulating hardware.
With this kind of technology, we take a machine and it emulates virtual hardware, and then bring up another operating system on top of that hardware.
There is a nice slide to show hypervisor based virutualization here.

Containers are about virtualizing the subsystems of the operating system itself.
We take services that the operating system provides (networking, filesystem, etc.) and provide them in a way that is virtuaizable.
This means that I can bring up different copies of an operating system on the same kernel.
We are using features of the kernel.
So you can think of containers as running at the level of the kernel, and this is different from hypervisors that run one level down, and try to emulate the hardware.

  • Containers: have a single kernels running underneath them
  • Hypervisors: have multiple kernels

A cool result of this, given that you have a single kernel, is that if you fix or update that kernel, all the "guests" running off it also get patched.

For memory, a hypervisor can only see pages.
It doesn't know what each guest is doing.
With a container, under a single kernel the single kernel can see all objects and usage inside each container to make resource decisions.
For this reason the resource decisions are made much more efficient.

What is a virtual machine?

Now we can tell you that a virtual machine runs on a hypervisor, and we have a hardware layer, an entire entire operating system, and then libraries and applications on top of it. A VM is a very needy fellow:

  • Each VM requires CPU, storage, memory, and an entire operating system
  • More VMs == more resources!
  • Portability is not guaranteed

The need to allocate more system resources makes them a lot fatter and less portable than containers.
For a ballpark comparison, a hypervisor image is typically gigabytes, and a container can be in the order of megabytes.
You've probably heard people talk about containers and use terms like "lightweight" and "efficient."
I found a nice slide to show the differences here.

Linux Container API

So if containers are so great, why did they only "become a thing" around 2014?
The short answer is that Docker came along and gave us "mere mortals" an ecosystem for building, pushing, pulling and running containers.
This was a product that simplified the complexity of underlying linux' isolation APIs: cgroups and namespaces.

  • cgroups: controls resources within the kernel (io, cpu, devices, memory, network). There is something called a "freezer" that you put a bunch of processes into and put them to sleep without worrying about resources between them.
  • namespaces: provide a pure isolation layer inside the kernel. Most of the time, resources only belong to a single one, for example:
    • networking devices go in networking namespaces
    • ipc namespace for messages between containers
    • mount namespace for filesystem tree
    • pid namespace - init in linux needs to be running as pid 1 it isolates the process tree between containers
    • UTS namespace because each container needs a separate hostname,
    • User namespace is important for "pretending to be root" without being root.)

For those interested, there is a good talk about the history of the Linux Containers API development here.
In early containers, you could break from a container and become root on the host.
While running as root is a desired or necessary feature for many applications, unexpected container breakouts are a bad security risk that container runtimes have worked hard to prohibit.
These core isolation APIs are for the most part the same for all linux distros.

A fun history fact (and maybe you already figured this about because you watched the video links above!).
These two things (cgroups and namespaces) were developed by different open source groups.
This came from an agreement at a conference in 2011 called the Kernel Summit, literally a bunch of people sitting in a room that had both developed technologies they wanted added to the linux kernel, and had to go through the feature process and argue their case independently.
At the end we did get a single container isolation API, but it had these two different components.
If you are interested in learning about platform specific runtime differences, see the runtime-spec repository.

Containers

Everything that claims to be a container technology is basically orchestrating these components.
You can draw boxes on your powerpoint, call the boxes containers "packages" or "encapsulated environments" or what not - but low level container runtimes must include system isolation.

Containers:

  • are encapsulations of an environment
  • have their own process namespace
  • the root process of the container container on the host is still associated with one parent process, and when you start the root process the set of child processes within the container might kick off, and when you kill the root process the container's child processes are also killed.

Container Namespaces

Akin to the namespaces on your host, a container also has its own namespace, or may be associated with a namespace shared by a group of containers.
Here it is helpful to think of a container like a little packaged environment, one that you can actually shell into like you would a server.
When I shell inside the container I find that it has its own little process namespace.

Container Cgroups

A cgroup is a "control group" and it's exactly that - a feature of the kernel that lets you allocate permissions for resources.
So, for example, I might allocate a particular amount of memory, or CPU time, or network bandwidth to a set of tasks (processes that are running on my computer.)
What else can we do?
We can monitor them, reconfigure them, and even deny them access to resources.
Containers also have their own set of cgroups.

What about a container image?

The words "container" and "image" are sometimes used synonymously, but are subtly two different things.
You can think of a container image as a template, and a container is one or more running instances of that template.
In more concrete terms, the image is one or more binary blobs sitting on your filesystem, ready to instantiate to create an isolated, encapsulated environment.

Example Interactions

Let's give a concrete example of how you might use a container.
Let's say you are a scientist, and a life changing paper just came out that describes how to estimate an optimal cheese eating time based on measured properties of the cheese.
You've been collecting cheeses for decades, you can easily collect the metrics needed, and you just need the software.

1. You find container images in a registry

{: .no-toc }

Thankfully, the scientist created the container you need and pushed it to Docker Hub so all you need to do is:

  1. Install a container runtime, such as Docker, to manage OCI containers
  2. Run the container with your input parameters (if the container isn't in your cache, it will be pulled)

That is it, and truly it is that easy!

2. You want to change the cheese algorithm

{: .no-toc }

Uhoh, the scientist calculated the relationship between the moisture content of cheese completely wrong, and you need to modify his code and then write your own paper to refute his claims.
Dry cheese, like cheddar, deserves just as high of a rating!
In this case, you would:

  1. Find the container recipe, which is an Docker build specification file in this case
  2. Build and run your new container
  3. Modify it as desired, and continue testing and modifying until you get the desired result

And you could equally publish your container and findings.
This is a good example of how containers support reproducible science.

Resources:

File: docs/docs/introduction/digests.md

layout: default title: Content Addressability nav_order: 4 parent: Introduction

Content Addressability

Content addressability is important so that you can ask for what you want.
When you are asking for (pulling) a container from a registry, the registry may provide content addressable storage, or some similar mechanism, to ensure that you get exactly what you are requesting.

Unique Resource Identifiers

How do we ask for containers? We ask for a unique resource identifier (uri) which broadly comes in this form:

text
<registry>//<container>:<tag>@<digest>

The example above is given in a familiar format for many users - one where we have a server (the registry) with some higher level project or organization (project), and under this project some set of container names that have different versions (tags and digets).
Some might clump the entire first address into a general tag, the "namespace":

text
<namespace>:<tag>@<digest>

For our purposes, let's use language to describe a concrete example of a repository on Docker Hub (the registry):

text
<registry>/<organization>/<repository>:<tag>@<digest>
  • registry: is usually a server running software with an API to interact with to pull images. Docker Hub is our registry in this example.
  • organization: is part of the namespace, and is the (more humanly interpretable) portion of the address.
  • repository is the specific container. On Docker Hub this might come from a user pushing containers directly, or an automated build from a connected webhook.

Let's make this example more specific.
Here is the busybox container on Docker Hub.
I want to pull it!
I might be tempted to do this:

bash
$ docker pull busybox
Using default tag: latest
latest: Pulling from library/busybox
697743189b6d: Pull complete 
Digest: sha256:061ca9704a714ee3e8b80523ec720c64f6209ad3f97c0ff7cb9ec7d19f15149f
Status: Downloaded newer image for busybox:latest

That's great, and I ultimately get a specific tag (the default is "latest" and the digest of my container is shown) but if I wanted to pull the container again, and I did it in the same fashion?
Well, take a look at the changes to "latest" (it was updated recently) and you'll see that I'd likely get a different container.

A (slightly) better interaction might have been asking for a particular tag:

bash
$ docker pull busybox:1.30.1
1.30.1: Pulling from library/busybox
Digest: sha256:061ca9704a714ee3e8b80523ec720c64f6209ad3f97c0ff7cb9ec7d19f15149f
Status: Downloaded newer image for busybox:1.30.1

There is likely not one best way to reference containers, thus the methodology used will vary by project.

bash
$ docker pull busybox@sha256:061ca9704a714ee3e8b80523ec720c64f6209ad3f97c0ff7cb9ec7d19f15149f

File: docs/docs/introduction/distribution.md

layout: default title: Distributing Container Images nav_order: 5 parent: Introduction

Distributing Container Images

{:.no_toc}

Table of contents

{: .no_toc .text-delta }

  1. TOC
    {:toc}

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]({{ site.baseurl }}/docs/introduction/container-images/#what-problems-do-containers-solve) 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.

File: docs/docs/introduction/introduction.md

Introduction

{: .no_toc }

Table of contents

{: .no_toc .text-delta }

  1. TOC
    {:toc}

If you are looking for a gentle introduction to containers and the Open Container
Initiative, you've come to the right place!

Containers

A container is generally an encapsulated environment that is created from one or more binaries (images) to provide some form of isolation. Read more about [containers here]({{ site.baseurl }}/docs/introduction/container-images/).

What is OCI?

OCI stands for the "Open Container Initiative" and encompasses a group of people and a set of projects for describing container formats and interactions.
For more information about OCI, see [About the Open Container Initiative]({{ site.baseurl }}/about/).

OCI Project Types

The runtime-spec, image-spec, and distribution-spec, provide details for how a container is built, or interacted with.
To give you a good understanding of OCI projects, let's talk about the goals of [OCI projects]({{ site.baseurl }}/docs/introduction/oci-projects/).
When you understand the goals of each one, this puts you in a position to understand how they are used, why they are used, and how you can contribute.

Content Addressability

How does somebody find your house to mail a letter? They have an address, or a unique
identifier for the location of your house. Containers are no different - we can calculate
hashes of their content called digests and then use these addresses as unique identifiers
to reference the containers. Read more about [Content Addressability]({{ site.baseurl }}/docs/introduction/digests/) here.

Distributing Container Images

Let's say I have a container on my host. How do I get it to you? How can you be sure
that your containers are safe if your laptop crashes? The task of distributing containers
offers an entire new space of challenges. Read about
[distributing container images here]({{ site.baseurl }}/docs/introduction/distribution/)

You made it to the bottom! Now that have an understanding of containers and the specifications, you should next read about how to contribute.

[Contributing]({{ site.baseurl }}/contributing){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }

File: docs/docs/introduction/oci-projects.md

layout: default title: OCI Projects nav_order: 3 parent: Introduction

OCI Projects

{:.no_toc}

  1. TOC
    {:toc}

Understanding How The Projects Meet Goals

The core of OCI are the projects for container images, registry interactions (for the distribution of containers) and runtime interactions.
Let's step back and talk about what this actually means.
If you are a developer, as we discuss these projects, think about them in the context of answering these questions:

  • How would I want to use this to solve a particular problem?
  • Where might I have seen this in the wild, and not realized it's a part of OCI?

Specific examples will be given to help guide your thinking.

The Image Specification

The image specification generally is a grouping of things to describe a container image.
While there is a definition for a filesystem and configuration, the most general entity to describe is the image manifest:

Manifest

The manifest comes down to a json blob of properties for the container such as contents (in Docker, we refer to image layers since the image is a bunch of .tar.gz assembled at runtime), annotations, and a unique identifier for a configuration object. For example, here is a json dump that describes a Docker container:

text
{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "size": 7023,
    "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7"
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 32654,
      "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0"
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 16724,
      "digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b"
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 73109,
      "digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736"
    }
  ],
  "annotations": {
    "com.example.key1": "value1",
    "com.example.key2": "value2"
  }
}

Where would I find an image manifest?

An image manifest would be served by a registry, and would help the user to obtain the content (in the example above, the .tar.gz layers assembled at runtime to create the image).

What would I do with the image manifest?

The manifest helps you to download image layers.
I might query the registry API to find the image manifest for an image I'm interested in, get back this json blob, and then use the client to pull the image layers (the digests).
Depending on the design of the registry, there would be another endpoint that I know to query with the blob digests to actually download them.

What are the annotations for?

Annotations are key value pairs of metadata to describe the image of interest. They are fairly flexible to allow for the registry and user to use as they see fit.

How would I want to use this to solve a particular problem?

The image manifest definition should be able to describe some kind of content blobs for an application like a registry.

Where might I have seen this in the wild?

An image manifest is what you see delivered by the Docker registry to get metadata for a particular container tag.

The Distribution Specification

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:

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

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

text
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.

The Runtime Specification

The runtime specification is another description of an interaction, but this time it's with a container binary. Specifically, this means the execution environment, configuration, and lifecycle of a container.

What do you mean by execution environment?

What is the host operating system of your computer, Windows? Linux?
These are different execution environments that come with different rules and standards for generating (what feels like) the same running container.
If you look at the runtime specification entry page, you'll actually find that there is a different specification file for each base operating system.

Why do we need runtime specifications?

As a user, you expect a container run on a Windows machine to generally feel like and act the same as a container run on a Linux host.
The runtime specifications are catered toward this goal, with different configuration files (called config.json) to drive the creation, execution enviroinment, and actions for the container.

How might I contribute?

You might have an entirely different operating system or technology that you want to explore running containers on, in which case you would want to contribute a new specification.
You might find that there is an ambiguity or bug for one runtime, and ask a question about how to work on it.

Runc

The project opencontainers/runc is perhaps one of the most important of all the OCI projects.

Why do we need runc?

This project includes code used by container runtimes to implement the OCI specification.
You can think of the runtime specification as a set of rules, and runc the actual implementation of those rules that you will find in code bases for popular container software.

How might I contribute?

It could be the case that you find a security hole in a container runtime that is possibly related to, or might be addressed by runc.
Realistically, if you want to change runc, the first step would be to start discussion around the runtime specification itself.

What are you waiting for? We want to hear from you!

[Contribute]({{ site.baseurl }}/docs/contribute/){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }

File: docs/docs/about.md

About OCI

The Open Container Initiative was established in June 2015 by Docker and other leaders in the containers industry to provide an intuitive API to interact with linux containers.

Challenges for OCI

Why did the OCI get established in the first place? There were several questions and challenges that warranted community discussion and support. Generally, the focus of initial work was to better define standards for container formats and runtime. If containers were to be successful, meaning they would have widespread adoption across different systems, and have development of tools for interaction, a standard was needed that everyone could rally behind.

Continued Challenges

Container technologies evolve on a regular basis, as do the needs of society and research groups. As new problems and use cases are brought to light, it's important that the standards for containers are continually challenged to address them.
For this reason, it's up to you [to contribute]({{ site.baseurl }}/contribute) your issues, thoughts, and questions about the OCI specifications catered to your use case.
If there is an issue, it's the responsibility of the community to discuss and address it.

Where do I go from here?

We suggest that you start with our introductory material.

[Introduction]({{ site.baseurl }}/introduction){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }

File: docs/index.md

The Open Container Initiative

Welcome to the Open Container Initiative (OCI) documentation site! The Open Container
Initiative cares about open, industry standards for container technology.
Broadly, technology encompasses two prominent ideas:

  • formats: What exactly is a container?
  • interaction: How do we run, create, pull, or otherwise interact with a container?

What will I find here?

This is a collection of introductory material to help you to understand containers,
the specifications that were created to support them, and finally, how
you can contribute to OCI.

  • [About the Open Container Initiative]({{ site.baseurl }}/about)
  • [Introductory Material]({{ site.baseurl }}/introduction)
  • [Contributing]({{ site.baseurl }}/contributing)

{: .fs-6 .fw-300 }

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#containers Browse containers catalog → #docker Browse docker catalog → #oci Browse oci catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →