Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ DOC_FILES := \
ROADMAP.md \
implementations.md \
project.md \
bundle.md \
runtime.md \
runtime-linux.md \
config.md \
Expand Down
11 changes: 5 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ Table of Contents
- [Roadmap](ROADMAP.md)
- [Implementations](implementations.md)
- [project](project.md)
- [Filesystem Bundle](bundle.md)
- Runtime and Lifecycle
- [General Runtime and Lifecycle](runtime.md)
- [Linux-specific Runtime and Lifecycle](runtime-linux.md)
Expand All @@ -31,11 +30,11 @@ An implementation that satisfies all the MUST or REQUIRED and all the SHOULD req

To provide context for users the following section gives example use cases for each part of the spec.

#### Application Bundle Builders
#### Application Publishers

Application bundle builders can create a [bundle](bundle.md) directory that includes all of the files required for launching an application as a container.
The bundle contains an OCI [configuration file](config.md) where the builder can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](config.md#mounts) locations, [hook](config.md#hooks) paths, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups).
Because the configuration includes host-specific settings, application bundle directories copied between two hosts may require configuration adjustments.
Application publishers distribute OCI [configuration files](config.md) and related resources (for example, [referenced filesystems](config.md#root-configuration) for launching an application as a [container](glossary.md#container).
The publisher can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](config.md#mounts) locations, [hook](config.md#hooks) paths, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups).
Because the configuration includes host-specific settings, configurations copied between two hosts may require local adjustments.

#### Hook Developers

Expand All @@ -44,7 +43,7 @@ Example use cases include sophisticated network configuration, volume garbage co

#### Runtime Developers

Runtime developers can build runtime implementations that run OCI-compliant bundles and container configuration, containing low-level OS and host specific details, on a particular platform.
Runtime developers can build runtime implementations that perform [operations](runtime.md#operations) on [containers](glossary.md#container) on a particular platform.

# Releases

Expand Down
24 changes: 0 additions & 24 deletions bundle.md

This file was deleted.

6 changes: 3 additions & 3 deletions config.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Below is a detailed description of each field defined in the configuration forma

## Specification version

* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OpenContainer specification with which the bundle complies.
* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OpenContainer specification with which the configuration complies.
The OpenContainer spec follows semantic versioning and retains forward and backward compatibility within major versions.
For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series.
NOTE that there is no guarantee for forward or backward compatibility for version 0.x.
Expand Down Expand Up @@ -180,7 +180,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th

## Hostname

* **`hostname`** (string, optional) as it is accessible to processes running inside. On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace].
* **`hostname`** (string, optional) as it is accessible to processes running inside. On Linux, you can only set this if your configuration creates a new [UTS namespace][uts-namespace].

### Example

Expand All @@ -192,7 +192,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th

* **`os`** (string, required) specifies the operating system family this image targets.
The runtime MUST generate an error if it does not support the configured **`os`**.
Bundles SHOULD use, and runtimes SHOULD understand, **`os`** entries listed in the Go Language document for [`$GOOS`][go-environment].
Configuration authors SHOULD use, and runtimes SHOULD understand, **`os`** entries listed in the Go Language document for [`$GOOS`][go-environment].
If an operating system is not included in the `$GOOS` documentation, it SHOULD be submitted to this specification for standardization.
* **`arch`** (string, required) specifies the instruction set for which the binaries in the image have been compiled.
The runtime MUST generate an error if it does not support the configured **`arch`**.
Expand Down
8 changes: 2 additions & 6 deletions glossary.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,8 @@
# Glossary

## Bundle

A [directory structure](bundle.md) that is written ahead of time, distributed, and used to seed the runtime for creating a [container](#container) and launching a process within it.

## Configuration

The [`config.json`](config.md) file in a [bundle](#bundle) which defines the intended [container](#container) and container process.
The [`config.json`](config.md) file which defines the intended [container](#container) and container process.

## Container

Expand All @@ -24,7 +20,7 @@ All configuration [JSON][] MUST be encoded in [UTF-8][].
## Runtime

An implementation of this specification.
It reads the [configuration files](#configuration) from a [bundle](#bundle), uses that information to create a [container](#container), launches a process inside the container, and performs other [lifecycle actions](runtime.md).
It performs [operations](runtime.md#operations) on [containers](#container).

## Runtime namespace

Expand Down
2 changes: 1 addition & 1 deletion implementations.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,5 @@ If you know of any associated projects that are not listed here, please file a p
## Testing & Tools

* [kunalkushwaha/octool](https://github.com/kunalkushwaha/octool) - A config linter and validator.
* [opencontainers/ocitools](https://github.com/opencontainers/ocitools) - A config generator and runtime/bundle testing framework.
* [opencontainers/ocitools](https://github.com/opencontainers/ocitools) - A config generator and runtime/configuration testing framework.
* [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime
4 changes: 2 additions & 2 deletions principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,15 @@ They are started in the same way whether they contain a postgres database, a php
## 3. Infrastructure-agnostic

Standard Containers are INFRASTRUCTURE-AGNOSTIC: they can be run in any OCI supported infrastructure.
For example, a standard container can be bundled on a laptop, uploaded to cloud storage, downloaded, run and snapshotted by a build server at a fiber hotel in Virginia, uploaded to 10 staging servers in a home-made private cloud cluster, then sent to 30 production instances across 3 public cloud regions.
For example, a standard container can be packaged on a laptop, uploaded to cloud storage, downloaded, run and snapshotted by a build server at a fiber hotel in Virginia, uploaded to 10 staging servers in a home-made private cloud cluster, then sent to 30 production instances across 3 public cloud regions.

## 4. Designed for automation

Standard Containers are DESIGNED FOR AUTOMATION: because they offer the same standard operations regardless of content and infrastructure, Standard Containers, 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 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.
Before Standard Containers, by the time a software component ran in production, it had been individually built, configured, packaged, 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.

Expand Down
13 changes: 6 additions & 7 deletions runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ There is no requirement that it be unique across hosts.
The ID is provided in the state because hooks will be executed with the state as the payload.
This allows the hooks to perform cleanup and teardown logic after the runtime destroys its own state.
* **`pid`**: (int) is the ID of the main process within the container, as seen by the host.
* **`bundlePath`**: (string) is the absolute path to the container's bundle directory.
* **`configPath`**: (string) is the absolute path to the container's [configuration](config.md).
This is provided so that consumers can find the container's configuration and root filesystem on the host.

When serialized in JSON, the format MUST adhere to the following pattern:
Expand All @@ -26,7 +26,7 @@ When serialized in JSON, the format MUST adhere to the following pattern:
"ociVersion": "0.2.0",
"id": "oci-container1",
"pid": 4422,
"bundlePath": "/containers/redis"
"configPath": "/containers/redis/config.json"
}
```

Expand All @@ -35,7 +35,7 @@ See [Query State](#query-state) for information on retrieving the state of a con
## Lifecycle
The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.

1. OCI compliant runtime is invoked with a reference to the location of the bundle.
1. OCI compliant runtime is invoked with a reference to the [configuration](config.md).
How this reference is passed to the runtime is an implementation detail.
2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md).
Any updates to `config.json` after container is running MUST not affect the container.
Expand Down Expand Up @@ -73,17 +73,16 @@ In particular, the state MUST be serialized as JSON.

### Start

`start <container-id> <path-to-bundle>`
`start <container-id> <path-to-configuration>`

This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container.
This operation MUST generate an error if it is not provided a path to the [configuration](config.md) and the container ID to associate with the container.
If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST generate an error.
Using the data in `config.json`, that are in the bundle's directory, this operation MUST create a new container.
This includes creating the relevant namespaces, resource limits, etc and configuring the appropriate capabilities for the container.
A new process within the scope of the container MUST be created as specified by the `config.json` file otherwise an error MUST be generated.

The runtime MAY validate `config.json` against this spec, either generically or with respect to the local system capabilities, before creating the container ([step 2](#lifecycle)).
If the runtime does not perform initial validation and triggers an error due to an invalid or incompatible configuration, it MUST generate an error and jump to cleanup ([step 7](#lifecycle)).
Runtime callers who are interested in pre-start validation can run [bundle-validation tools](implementations.md#testing--tools) before invoking the start operation.
Runtime callers who are interested in pre-start validation can run [configuration-validation tools](implementations.md#testing--tools) before invoking the start operation.

Attempting to start an already running container MUST have no effect on the container and MUST generate an error.

Expand Down
Loading