Michael Crosby
commit
03bf64fd3f
67
README.md
67
README.md
|
|
@ -1,17 +1,22 @@
|
|||
# Open Container Specifications
|
||||
|
||||
This project is where the [Open Container Initiative](http://www.opencontainers.org/) Specifications are written.
|
||||
This is a work in progress.
|
||||
[Open Container Initiative](http://www.opencontainers.org/) Specifications for standards on Operating System process and application containers.
|
||||
|
||||
|
||||
Table of Contents
|
||||
|
||||
- [Container Principles](principles.md)
|
||||
- [Filesystem Bundle](bundle.md)
|
||||
- [Container Configuration](config.md)
|
||||
- [Linux Specific Configuration](config-linux.md)
|
||||
- Configuration
|
||||
- [Container Configuration](config.md)
|
||||
- [Container Configuration (Linux-specific)](config-linux.md)
|
||||
- [Runtime Configuration](runtime-config.md)
|
||||
- [Runtime Configuration (Linux-specific)](runtime-config-linux.md)
|
||||
- [Runtime and Lifecycle](runtime.md)
|
||||
- [Linux Specific Runtime](runtime-linux.md)
|
||||
- [Implementations](implementations.md)
|
||||
|
||||
## Use Cases
|
||||
# Use Cases
|
||||
|
||||
To provide context for users the following section gives example use cases for each part of the spec.
|
||||
|
||||
|
|
@ -24,58 +29,6 @@ To provide context for users the following section gives example use cases for e
|
|||
There is a loose [Road Map](https://github.com/opencontainers/specs/wiki/RoadMap:) on the wiki.
|
||||
During the `0.x` series of OCI releases we make no backwards compatibility guarantees and intend to break the schema during this series.
|
||||
|
||||
# The 5 principles of Standard Containers
|
||||
|
||||
Define a unit of software delivery called a Standard Container.
|
||||
The goal of a Standard Container is to encapsulate a software component and all its dependencies in a format that is self-describing and portable, so that any compliant runtime can run it without extra dependencies, regardless of the underlying machine and the contents of the container.
|
||||
|
||||
The specification for Standard Containers is straightforward.
|
||||
It mostly defines 1) a file format, 2) a set of standard operations, and 3) an execution environment.
|
||||
|
||||
A great analogy for this is the shipping container.
|
||||
Just like how Standard Containers are a fundamental unit of software delivery, shipping containers are a fundamental unit of physical delivery.
|
||||
|
||||
## 1. Standard operations
|
||||
|
||||
Just like shipping containers, Standard Containers define a set of STANDARD OPERATIONS.
|
||||
Shipping containers can be lifted, stacked, locked, loaded, unloaded and labelled.
|
||||
Similarly, Standard Containers can be created, started, and stopped using standard container tools (what this spec is about); copied and snapshotted using standard filesystem tools; and downloaded and uploaded using standard network tools.
|
||||
|
||||
## 2. Content-agnostic
|
||||
|
||||
Just like shipping containers, Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents.
|
||||
A shipping container will be stacked in exactly the same way whether it contains Vietnamese powder coffee or spare Maserati parts.
|
||||
Similarly, Standard Containers are started or uploaded in the same way whether they contain a postgres database, a php application with its dependencies and application server, or Java build artifacts.
|
||||
|
||||
## 3. Infrastructure-agnostic
|
||||
|
||||
Both types of containers are INFRASTRUCTURE-AGNOSTIC: they can be transported to thousands of facilities around the world, and manipulated by a wide variety of equipment.
|
||||
A shipping container can be packed in a factory in Ukraine, transported by truck to the nearest routing center, stacked onto a train, loaded into a German boat by an Australian-built crane, stored in a warehouse at a US facility, etc.
|
||||
Similarly, a standard container can be bundled on my laptop, uploaded to S3, downloaded, run and snapshotted by a build server at Equinix in Virginia, uploaded to 10 staging servers in a home-made Openstack cluster, then sent to 30 production instances across 3 EC2 regions.
|
||||
|
||||
## 4. Designed for automation
|
||||
|
||||
Because they offer the same standard operations regardless of content and infrastructure, Standard Containers, just like their physical counterparts, are extremely well-suited for automation.
|
||||
In fact, you could say automation is their secret weapon.
|
||||
|
||||
Many things that once required time-consuming and error-prone human effort can now be programmed.
|
||||
Before shipping containers, a bag of powder coffee was hauled, dragged, dropped, rolled and stacked by 10 different people in 10 different locations by the time it reached its destination.
|
||||
1 out of 50 disappeared.
|
||||
1 out of 20 was damaged.
|
||||
The process was slow, inefficient and cost a fortune - and was entirely different depending on the facility and the type of goods.
|
||||
|
||||
Similarly, before Standard Containers, by the time a software component ran in production, it had been individually built, configured, bundled, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers.
|
||||
Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken.
|
||||
The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider.
|
||||
|
||||
## 5. Industrial-grade delivery
|
||||
|
||||
There are 17 million shipping containers in existence, packed with every physical good imaginable.
|
||||
Every single one of them can be loaded onto the same boats, by the same cranes, in the same facilities, and sent anywhere in the World with incredible efficiency.
|
||||
It is embarrassing to think that a 30 ton shipment of coffee can safely travel half-way across the World in *less time* than it takes a software team to deliver its code from one datacenter to another sitting 10 miles away.
|
||||
|
||||
With Standard Containers we can put an end to that embarrassment, by making INDUSTRIAL-GRADE DELIVERY of software a reality.
|
||||
|
||||
# Contributing
|
||||
|
||||
Development happens on GitHub for the spec.
|
||||
|
|
|
|||
11
bundle.md
11
bundle.md
|
|
@ -1,4 +1,6 @@
|
|||
# Bundle Container Format
|
||||
# Bundle
|
||||
|
||||
## Container Format
|
||||
|
||||
This section defines a format for encoding a container as a *bundle* - a directory organized in a certain way, and containing all the necessary data and metadata for any compliant runtime to perform all standard operations against it.
|
||||
See also [OS X application bundles](http://en.wikipedia.org/wiki/Bundle_%28OS_X%29) for a similar use of the term *bundle*.
|
||||
|
|
@ -14,7 +16,7 @@ A standard container bundle is made of the following 3 parts:
|
|||
- One or more content directories
|
||||
- A configuration file
|
||||
|
||||
# Directory layout
|
||||
## Directory layout
|
||||
|
||||
A Standard Container bundle is a directory containing all the content needed to load and run a container.
|
||||
This includes two configuration files `config.json` and `runtime.json`, and a rootfs directory.
|
||||
|
|
@ -22,7 +24,10 @@ The `config.json` file contains settings that are host independent and applicati
|
|||
The `runtime.json` file contains settings that are host specific such as memory limits, local device access and mount points.
|
||||
The goal is that the bundle can be moved as a unit to another machine and run the same application if `runtime.json` is removed or reconfigured.
|
||||
|
||||
The syntax and semantics for `config.json` are described in [this specification](config.md).
|
||||
Configuration file syntax and semantics:
|
||||
|
||||
* [`config.json`](config.md) (immutable, host independent configuration)
|
||||
* [`runtime.json`](runtime-config.md) (mutable, host dependent configuration)
|
||||
|
||||
A single `rootfs` directory MUST be in the same directory as the `config.json`.
|
||||
The names of the directories may be arbitrary, but users should consider using conventional names as in the example below.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,6 @@
|
|||
|
||||
Behave as a community member, follow the code of conduct.
|
||||
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
The OpenContainers community is made up of a mixture of professionals and volunteers from all over the world.
|
||||
|
|
@ -36,4 +35,3 @@ By adopting this Code of Conduct, project maintainers commit themselves to fairl
|
|||
Thanks to the [Fedora Code of Conduct](https://getfedora.org/code-of-conduct) and [Contributor Covenant](http://contributor-covenant.org) for inspiration and ideas.
|
||||
|
||||
Portions of this Code of Conduct are adapted from the Contributor Covenant, version 1.2.0, available at http://contributor-covenant.org/version/1/2/0/
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Linux-specific configuration
|
||||
# Linux-specific Container Configuration
|
||||
|
||||
The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and file system jails to fulfill the spec.
|
||||
Additional information is needed for Linux over the [default spec configuration](config.md) in order to configure these various kernel features.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Configuration file
|
||||
# Container Configuration file
|
||||
|
||||
The container's top-level directory MUST contain a configuration file called `config.json`.
|
||||
For now the canonical schema is defined in [config.go](config.go) and [config_linux.go](config_linux.go), but this will be moved to a formal JSON schema over time.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,51 @@
|
|||
# The 5 principles of Standard Containers
|
||||
|
||||
Define a unit of software delivery called a Standard Container.
|
||||
The goal of a Standard Container is to encapsulate a software component and all its dependencies in a format that is self-describing and portable, so that any compliant runtime can run it without extra dependencies, regardless of the underlying machine and the contents of the container.
|
||||
|
||||
The specification for Standard Containers is straightforward.
|
||||
It mostly defines 1) a file format, 2) a set of standard operations, and 3) an execution environment.
|
||||
|
||||
A great analogy for this is the shipping container.
|
||||
Just like how Standard Containers are a fundamental unit of software delivery, shipping containers are a fundamental unit of physical delivery.
|
||||
|
||||
## 1. Standard operations
|
||||
|
||||
Just like shipping containers, Standard Containers define a set of STANDARD OPERATIONS.
|
||||
Shipping containers can be lifted, stacked, locked, loaded, unloaded and labelled.
|
||||
Similarly, Standard Containers can be created, started, and stopped using standard container tools (what this spec is about); copied and snapshotted using standard filesystem tools; and downloaded and uploaded using standard network tools.
|
||||
|
||||
## 2. Content-agnostic
|
||||
|
||||
Just like shipping containers, Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents.
|
||||
A shipping container will be stacked in exactly the same way whether it contains Vietnamese powder coffee or spare Maserati parts.
|
||||
Similarly, Standard Containers are started or uploaded in the same way whether they contain a postgres database, a php application with its dependencies and application server, or Java build artifacts.
|
||||
|
||||
## 3. Infrastructure-agnostic
|
||||
|
||||
Both types of containers are INFRASTRUCTURE-AGNOSTIC: they can be transported to thousands of facilities around the world, and manipulated by a wide variety of equipment.
|
||||
A shipping container can be packed in a factory in Ukraine, transported by truck to the nearest routing center, stacked onto a train, loaded into a German boat by an Australian-built crane, stored in a warehouse at a US facility, etc.
|
||||
Similarly, a standard container can be bundled on my laptop, uploaded to S3, downloaded, run and snapshotted by a build server at Equinix in Virginia, uploaded to 10 staging servers in a home-made Openstack cluster, then sent to 30 production instances across 3 EC2 regions.
|
||||
|
||||
## 4. Designed for automation
|
||||
|
||||
Because they offer the same standard operations regardless of content and infrastructure, Standard Containers, just like their physical counterparts, are extremely well-suited for automation.
|
||||
In fact, you could say automation is their secret weapon.
|
||||
|
||||
Many things that once required time-consuming and error-prone human effort can now be programmed.
|
||||
Before shipping containers, a bag of powder coffee was hauled, dragged, dropped, rolled and stacked by 10 different people in 10 different locations by the time it reached its destination.
|
||||
1 out of 50 disappeared.
|
||||
1 out of 20 was damaged.
|
||||
The process was slow, inefficient and cost a fortune - and was entirely different depending on the facility and the type of goods.
|
||||
|
||||
Similarly, before Standard Containers, by the time a software component ran in production, it had been individually built, configured, bundled, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers.
|
||||
Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken.
|
||||
The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider.
|
||||
|
||||
## 5. Industrial-grade delivery
|
||||
|
||||
There are 17 million shipping containers in existence, packed with every physical good imaginable.
|
||||
Every single one of them can be loaded onto the same boats, by the same cranes, in the same facilities, and sent anywhere in the World with incredible efficiency.
|
||||
It is embarrassing to think that a 30 ton shipment of coffee can safely travel half-way across the World in *less time* than it takes a software team to deliver its code from one datacenter to another sitting 10 miles away.
|
||||
|
||||
With Standard Containers we can put an end to that embarrassment, by making INDUSTRIAL-GRADE DELIVERY of software a reality.
|
||||
|
|
@ -1,3 +1,5 @@
|
|||
# Linux-specific Runtime Configuration
|
||||
|
||||
## Namespaces
|
||||
|
||||
A namespace wraps a global system resource in an abstraction that makes it appear to the processes within the namespace that they have their own isolated instance of the global resource.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,59 @@
|
|||
# Runtime Configuration
|
||||
|
||||
## Hooks
|
||||
|
||||
Lifecycle hooks allow custom events for different points in a container's runtime.
|
||||
Presently there are `Prestart` and `Poststop`.
|
||||
|
||||
* [`Prestart`](#pre-start) is a list of hooks to be run before the container process is executed
|
||||
* [`Poststop`](#post-stop)is a list of hooks to be run after the container process exits
|
||||
|
||||
Hooks allow one to run code before/after various lifecycle events of the container.
|
||||
Hooks MUST be called in the listed order.
|
||||
The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
|
||||
|
||||
Hook paths are absolute and are executed from the host's filesystem.
|
||||
|
||||
### Pre-start
|
||||
|
||||
The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed.
|
||||
They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container.
|
||||
In Linux, for e.g., the network namespace could be configured in this hook.
|
||||
|
||||
If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.
|
||||
|
||||
### Post-stop
|
||||
|
||||
The post-stop hooks are called after the container process is stopped.
|
||||
Cleanup or debugging could be performed in such a hook.
|
||||
If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
|
||||
|
||||
*Example*
|
||||
|
||||
```json
|
||||
"hooks" : {
|
||||
"prestart": [
|
||||
{
|
||||
"path": "/usr/bin/fix-mounts",
|
||||
"args": ["arg1", "arg2"],
|
||||
"env": [ "key1=value1"]
|
||||
},
|
||||
{
|
||||
"path": "/usr/bin/setup-network"
|
||||
}
|
||||
],
|
||||
"poststop": [
|
||||
{
|
||||
"path": "/usr/sbin/cleanup.sh",
|
||||
"args": ["-f"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`path` is required for a hook.
|
||||
`args` and `env` are optional.
|
||||
|
||||
## Mount Configuration
|
||||
|
||||
Additional filesystems can be declared as "mounts", specified in the *mounts* object.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
# Linux Runtime
|
||||
|
||||
## File descriptors
|
||||
By default, only the `stdin`, `stdout` and `stderr` file descriptors are kept open for the application by the runtime.
|
||||
|
||||
|
|
|
|||
46
runtime.md
46
runtime.md
|
|
@ -49,48 +49,4 @@ This event needs to be captured by runc to run onstop event handlers.
|
|||
|
||||
## Hooks
|
||||
|
||||
Hooks allow one to run code before/after various lifecycle events of the container.
|
||||
Hooks MUST be called in the listed order.
|
||||
The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
|
||||
|
||||
Hook paths are absolute and are executed from the host's filesystem.
|
||||
|
||||
### Pre-start
|
||||
|
||||
The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed.
|
||||
They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container.
|
||||
In Linux, for e.g., the network namespace could be configured in this hook.
|
||||
|
||||
If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.
|
||||
|
||||
### Post-stop
|
||||
|
||||
The post-stop hooks are called after the container process is stopped.
|
||||
Cleanup or debugging could be performed in such a hook.
|
||||
If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
|
||||
|
||||
*Example*
|
||||
|
||||
```json
|
||||
"hooks" : {
|
||||
"prestart": [
|
||||
{
|
||||
"path": "/usr/bin/fix-mounts",
|
||||
"args": ["arg1", "arg2"],
|
||||
"env": [ "key1=value1"]
|
||||
},
|
||||
{
|
||||
"path": "/usr/bin/setup-network"
|
||||
}
|
||||
],
|
||||
"poststop": [
|
||||
{
|
||||
"path": "/usr/sbin/cleanup.sh",
|
||||
"args": ["-f"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`path` is required for a hook.
|
||||
`args` and `env` are optional.
|
||||
See [runtime configuration for hooks](./runtime-config.md)
|
||||
|
|
|
|||
Loading…
Reference in New Issue