jasder
/
runc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #707 from mrunalp/anchor_tags 

Anchor tags
This commit is contained in:
Michael Crosby 2017-03-03 09:38:08 -08:00 committed by GitHub
parent 40474dd78c c942816d76
commit 41839d7f95
7 changed files with 69 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
config-linux.md
View File

@ -1,9 +1,9 @@
# Linux-specific Container Configuration # <a name="linuxContainerConfiguration" />Linux Container Configuration
This document describes the schema for the [Linux-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md). This document describes the schema for the [Linux-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md).
The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and filesystem jails to fulfill the spec. The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and filesystem jails to fulfill the spec.
## Default Filesystems ## <a name="configLinuxDefaultFilesystems" />Default Filesystems
The Linux ABI includes both syscalls and several special file paths. The Linux ABI includes both syscalls and several special file paths.
Applications expecting a Linux environment will very likely expect these file paths to be setup correctly. Applications expecting a Linux environment will very likely expect these file paths to be setup correctly.
@ -17,7 +17,7 @@ The following filesystems SHOULD be made available in each container's filesyste
| /dev/pts | [devpts](https://www.kernel.org/doc/Documentation/filesystems/devpts.txt) | | /dev/pts | [devpts](https://www.kernel.org/doc/Documentation/filesystems/devpts.txt) |
| /dev/shm | [tmpfs](https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt) | | /dev/shm | [tmpfs](https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt) |
## Namespaces ## <a name="configLinuxNamespaces" />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. 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.
Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes.
@ -71,7 +71,7 @@ If a `namespaces` field contains duplicated namespaces with same `type`, the run
] ]
``` ```
## User namespace mappings ## <a name="configLinuxUserNamespaceMappings" />User namespace mappings
**`uidMappings`** (array of objects, OPTIONAL) describes the user namespace uid mappings from the host to the container. **`uidMappings`** (array of objects, OPTIONAL) describes the user namespace uid mappings from the host to the container.
**`gidMappings`** (array of objects, OPTIONAL) describes the user namespace gid mappings from the host to the container. **`gidMappings`** (array of objects, OPTIONAL) describes the user namespace gid mappings from the host to the container.
@ -104,7 +104,7 @@ Note that the number of mapping entries MAY be limited by the [kernel][user-name
] ]
``` ```
## Devices ## <a name="configLinuxDevices" />Devices
**`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container. **`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container.
The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.). The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.).
@ -148,7 +148,7 @@ The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices.
] ]
``` ```
###### Default Devices ###### <a name="configLinuxDefaultDevices" />Default Devices
In addition to any devices configured with this setting, the runtime MUST also supply: In addition to any devices configured with this setting, the runtime MUST also supply:
@ -162,7 +162,7 @@ In addition to any devices configured with this setting, the runtime MUST also s
* [`/dev/ptmx`][pts.4]. * [`/dev/ptmx`][pts.4].
A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts]. A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts].
## Control groups ## <a name="configLinuxControlGroups" />Control groups
Also known as cgroups, they are used to restrict resource usage for a container and handle device access. Also known as cgroups, they are used to restrict resource usage for a container and handle device access.
cgroups provide controls (through controllers) to restrict cpu, memory, IO, pids and network for the container. cgroups provide controls (through controllers) to restrict cpu, memory, IO, pids and network for the container.
@ -207,7 +207,7 @@ However, a runtime MAY attach the container process to additional cgroup control
} }
``` ```
#### Device whitelist #### <a name="configLinuxDeviceWhitelist" />Device whitelist
**`devices`** (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices]. **`devices`** (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices].
The runtime MUST apply entries in the listed order. The runtime MUST apply entries in the listed order.
@ -247,7 +247,7 @@ Each entry has the following structure:
] ]
``` ```
#### Disable out-of-memory killer #### <a name="configLinuxDisableOutOfMemoryKiller" />Disable out-of-memory killer
`disableOOMKiller` contains a boolean (`true` or `false`) that enables or disables the Out of Memory killer for a cgroup. `disableOOMKiller` contains a boolean (`true` or `false`) that enables or disables the Out of Memory killer for a cgroup.
If enabled (`false`), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer. If enabled (`false`), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer.
@ -263,7 +263,7 @@ For more information, see [the memory cgroup man page][cgroup-v1-memory].
"disableOOMKiller": false "disableOOMKiller": false
``` ```
#### Set oom_score_adj #### <a name="configLinuxSetOomScoreAdj" />Set oom_score_adj
`oomScoreAdj` sets heuristic regarding how the process is evaluated by the kernel during memory pressure. `oomScoreAdj` sets heuristic regarding how the process is evaluated by the kernel during memory pressure.
For more information, see [the proc filesystem documentation section 3.1](https://www.kernel.org/doc/Documentation/filesystems/proc.txt). For more information, see [the proc filesystem documentation section 3.1](https://www.kernel.org/doc/Documentation/filesystems/proc.txt).
@ -278,7 +278,7 @@ For more information on how these two settings work together, see [the memory cg
"oomScoreAdj": 100 "oomScoreAdj": 100
``` ```
#### Memory #### <a name="configLinuxMemory" />Memory
**`memory`** (object, OPTIONAL) represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage. **`memory`** (object, OPTIONAL) represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage.
For more information, see [the memory cgroup man page][cgroup-v1-memory]. For more information, see [the memory cgroup man page][cgroup-v1-memory].
@ -310,7 +310,7 @@ The following parameters can be specified to setup the controller:
} }
``` ```
#### CPU #### <a name="configLinuxCPU" />CPU
**`cpu`** (object, OPTIONAL) represents the cgroup subsystems `cpu` and `cpusets`. **`cpu`** (object, OPTIONAL) represents the cgroup subsystems `cpu` and `cpusets`.
For more information, see [the cpusets cgroup man page][cgroup-v1-cpusets]. For more information, see [the cpusets cgroup man page][cgroup-v1-cpusets].
@ -345,7 +345,7 @@ The following parameters can be specified to setup the controller:
} }
``` ```
#### Block IO Controller #### <a name="configLinuxBlockIO" />Block IO
**`blockIO`** (object, OPTIONAL) represents the cgroup subsystem `blkio` which implements the block IO controller. **`blockIO`** (object, OPTIONAL) represents the cgroup subsystem `blkio` which implements the block IO controller.
For more information, see [the kernel cgroups documentation about blkio][cgroup-v1-blkio]. For more information, see [the kernel cgroups documentation about blkio][cgroup-v1-blkio].
@ -404,7 +404,7 @@ The following parameters can be specified to setup the controller:
} }
``` ```
#### Huge page limits #### <a name="configLinuxHugePageLimits" />Huge page limits
**`hugepageLimits`** (array of objects, OPTIONAL) represents the `hugetlb` controller which allows to limit the **`hugepageLimits`** (array of objects, OPTIONAL) represents the `hugetlb` controller which allows to limit the
HugeTLB usage per control group and enforces the controller limit during page fault. HugeTLB usage per control group and enforces the controller limit during page fault.
@ -427,7 +427,7 @@ Each entry has the following structure:
] ]
``` ```
#### Network #### <a name="configLinuxNetwork" />Network
**`network`** (object, OPTIONAL) represents the cgroup subsystems `net_cls` and `net_prio`. **`network`** (object, OPTIONAL) represents the cgroup subsystems `net_cls` and `net_prio`.
For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and [the net\_prio cgroup man page][cgroup-v1-net-prio]. For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and [the net\_prio cgroup man page][cgroup-v1-net-prio].
@ -459,7 +459,7 @@ The following parameters can be specified to setup the controller:
} }
``` ```
#### PIDs #### <a name="configLinuxPIDS" />PIDs
**`pids`** (object, OPTIONAL) represents the cgroup subsystem `pids`. **`pids`** (object, OPTIONAL) represents the cgroup subsystem `pids`.
For more information, see [the pids cgroup man page][cgroup-v1-pids]. For more information, see [the pids cgroup man page][cgroup-v1-pids].
@ -476,7 +476,7 @@ The following parameters can be specified to setup the controller:
} }
``` ```
## Sysctl ## <a name="configLinuxSysctl" />Sysctl
**`sysctl`** (object, OPTIONAL) allows kernel parameters to be modified at runtime for the container. **`sysctl`** (object, OPTIONAL) allows kernel parameters to be modified at runtime for the container.
For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html) For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html)
@ -490,7 +490,7 @@ For more information, see [the man page](http://man7.org/linux/man-pages/man8/sy
} }
``` ```
## seccomp ## <a name="configLinuxSeccomp" />Seccomp
Seccomp provides application sandboxing mechanism in the Linux kernel. Seccomp provides application sandboxing mechanism in the Linux kernel.
Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows matching on values passed as arguments to syscalls. Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows matching on values passed as arguments to syscalls.
@ -554,7 +554,7 @@ Operator Constants:
} }
``` ```
## Rootfs Mount Propagation ## <a name="configLinuxRootfsMountPropagation" />Rootfs Mount Propagation
**`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation. **`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation.
Its value is either slave, private, or shared. Its value is either slave, private, or shared.
@ -566,7 +566,7 @@ Its value is either slave, private, or shared.
"rootfsPropagation": "slave", "rootfsPropagation": "slave",
``` ```
## Masked Paths ## <a name="configLinuxMaskedPaths" />Masked Paths
**`maskedPaths`** (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read. **`maskedPaths`** (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read.
The values MUST be absolute paths in the [container namespace][container-namespace2]. The values MUST be absolute paths in the [container namespace][container-namespace2].
@ -579,7 +579,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa
] ]
``` ```
## Readonly Paths ## <a name="configLinuxReadonlyPaths" />Readonly Paths
**`readonlyPaths`** (array of strings, OPTIONAL) will set the provided paths as readonly inside the container. **`readonlyPaths`** (array of strings, OPTIONAL) will set the provided paths as readonly inside the container.
The values MUST be absolute paths in the [container namespace][container-namespace2]. The values MUST be absolute paths in the [container namespace][container-namespace2].
@ -592,7 +592,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa
] ]
``` ```
## Mount Label ## <a name"configLinuxMountLabel" />Mount Label
**`mountLabel`** (string, OPTIONAL) will set the Selinux context for the mounts in the container. **`mountLabel`** (string, OPTIONAL) will set the Selinux context for the mounts in the container.

34
config.md
View File

@ -1,4 +1,4 @@
# Container Configuration file # <a name="containerConfigurationFile" />Container Configuration file
The container's top-level directory MUST contain a configuration file called `config.json`. The container's top-level directory MUST contain a configuration file called `config.json`.
The canonical schema is defined in this document, but there is a JSON Schema in [`schema/config-schema.json`](schema/config-schema.json) and Go bindings in [`specs-go/config.go`](specs-go/config.go). The canonical schema is defined in this document, but there is a JSON Schema in [`schema/config-schema.json`](schema/config-schema.json) and Go bindings in [`specs-go/config.go`](specs-go/config.go).
@ -13,7 +13,7 @@ Platform-specific fields are identified as such.
For all platform-specific configuration values, the scope defined below in the [Platform-specific configuration](#platform-specific-configuration) section applies. For all platform-specific configuration values, the scope defined below in the [Platform-specific configuration](#platform-specific-configuration) section applies.
## Specification version ## <a name="configSpecificationVersion" />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 Open Container Runtime 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 Open Container Runtime Specification with which the bundle complies.
The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions. The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions.
@ -25,7 +25,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
"ociVersion": "0.1.0" "ociVersion": "0.1.0"
``` ```
## Root Configuration ## <a name="configRoot" />Root
**`root`** (object, REQUIRED) specifies the container's root filesystem. **`root`** (object, REQUIRED) specifies the container's root filesystem.
@ -44,7 +44,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
} }
``` ```
## Mounts ## <a name="configMounts" />Mounts
**`mounts`** (array, OPTIONAL) specifies additional mounts beyond [`root`](#root-configuration). **`mounts`** (array, OPTIONAL) specifies additional mounts beyond [`root`](#root-configuration).
The runtime MUST mount entries in the listed order. The runtime MUST mount entries in the listed order.
@ -118,7 +118,7 @@ For Windows, see links for details about [mountvol](http://ss64.com/nt/mountvol.
] ]
``` ```
## Process ## <a name="configProcess" />Process
**`process`** (object, REQUIRED) specifies the container process. **`process`** (object, REQUIRED) specifies the container process.
@ -158,11 +158,11 @@ For Linux-based systems the process structure supports the following process spe
* **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label to be applied to the processes in the container. * **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label to be applied to the processes in the container.
For more information about SELinux, see [SELinux documentation](http://selinuxproject.org/page/Main_Page) For more information about SELinux, see [SELinux documentation](http://selinuxproject.org/page/Main_Page)
### User ### <a name="configUser" />User
The user for the process is a platform-specific structure that allows specific control over which user the process runs as. The user for the process is a platform-specific structure that allows specific control over which user the process runs as.
#### Linux and Solaris User #### <a name="configLinuxAndSolarisUser" />Linux and Solaris User
For Linux and Solaris based systems the user structure has the following fields: For Linux and Solaris based systems the user structure has the following fields:
@ -255,7 +255,7 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are
} }
``` ```
#### Windows User #### <a name="configWindowsUser" />Windows User
For Windows based systems the user structure has the following fields: For Windows based systems the user structure has the following fields:
@ -280,7 +280,7 @@ For Windows based systems the user structure has the following fields:
``` ```
## Hostname ## <a name="configHostname" />Hostname
* **`hostname`** (string, OPTIONAL) specifies the container's hostname as seen by processes running inside the container. * **`hostname`** (string, OPTIONAL) specifies the container's hostname as seen by processes running inside the container.
On Linux, for example, this will change the hostname in the [container][container-namespace] [UTS namespace][uts-namespace]. On Linux, for example, this will change the hostname in the [container][container-namespace] [UTS namespace][uts-namespace].
@ -292,7 +292,7 @@ For Windows based systems the user structure has the following fields:
"hostname": "mrsdalloway" "hostname": "mrsdalloway"
``` ```
## Platform ## <a name="configPlatform" />Platform
**`platform`** (object, REQUIRED) specifies the configuration's target platform. **`platform`** (object, REQUIRED) specifies the configuration's target platform.
@ -314,7 +314,7 @@ For Windows based systems the user structure has the following fields:
} }
``` ```
## Platform-specific configuration ## <a name="configPlatformSpecificConfiguration" />Platform-specific configuration
[**`platform.os`**](#platform) is used to specify platform-specific configuration. [**`platform.os`**](#platform) is used to specify platform-specific configuration.
Runtime implementations MAY support any valid values for platform-specific fields as part of this configuration. Runtime implementations MAY support any valid values for platform-specific fields as part of this configuration.
@ -345,7 +345,7 @@ Implementations MUST error out when invalid values are encountered and MUST gene
} }
``` ```
## Hooks ## <a name="configHooks" />Hooks
Hooks allow for the configuration of custom actions related to the [lifecycle](runtime.md#lifecycle) of the container. Hooks allow for the configuration of custom actions related to the [lifecycle](runtime.md#lifecycle) of the container.
@ -366,21 +366,21 @@ Hooks allow users to specify programs to run before or after various lifecycle e
Hooks MUST be called in the listed order. Hooks MUST be called in the listed order.
The [state](runtime.md#state) of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container. The [state](runtime.md#state) of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container.
### Prestart ### <a name="configHooksPrestart" />Prestart
The pre-start hooks MUST be called after the container has been created, but before the user supplied command is executed. The pre-start hooks MUST be called after the container has been created, but before the user supplied command is executed.
On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook). On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
If a hook returns a non-zero exit code, an error including the exit code and the stderr MUST be returned to the caller and the container MUST be destroyed. If a hook returns a non-zero exit code, an error including the exit code and the stderr MUST be returned to the caller and the container MUST be destroyed.
### Poststart ### <a name="configHooksPoststart" />Poststart
The post-start hooks MUST be called after the user process is started. The post-start hooks MUST be called after the user process is started.
For example, this hook can notify the user that the container process is spawned. For example, this hook can notify the user that the container process is spawned.
If a hook returns a non-zero exit code, then an error MUST be logged and the remaining hooks are executed. If a hook returns a non-zero exit code, then an error MUST be logged and the remaining hooks are executed.
### Poststop ### <a name="configHooksPoststop" />Poststop
The post-stop hooks MUST be called after the container process is stopped. The post-stop hooks MUST be called after the container process is stopped.
Cleanup or debugging functions are examples of such a hook. Cleanup or debugging functions are examples of such a hook.
@ -415,7 +415,7 @@ If a hook returns a non-zero exit code, then an error MUST be logged and the rem
} }
``` ```
## Annotations ## <a name="configAnnotations" />Annotations
**`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container. **`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container.
This information MAY be structured or unstructured. This information MAY be structured or unstructured.
@ -438,7 +438,7 @@ Values MAY be an empty string.
} }
``` ```
## Extensibility ## <a name="configExtensibility" />Extensibility
Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown property. Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown property.
Instead they MUST ignore unknown properties. Instead they MUST ignore unknown properties.

8
implementations.md
View File

@ -1,18 +1,18 @@
# Implementations # <a name="implementations" />Implementations
The following sections link to associated projects, some of which are maintained by the OCI and some of which are maintained by external organizations. The following sections link to associated projects, some of which are maintained by the OCI and some of which are maintained by external organizations.
If you know of any associated projects that are not listed here, please file a pull request adding a link to that project. If you know of any associated projects that are not listed here, please file a pull request adding a link to that project.
## Runtime (Container) ## <a name"implementationsRuntimeContainer" />Runtime (Container)
* [opencontainers/runc](https://github.com/opencontainers/runc) - Reference implementation of OCI runtime * [opencontainers/runc](https://github.com/opencontainers/runc) - Reference implementation of OCI runtime
## Runtime (Virtual Machine) ## <a name="implementationsRuntimeVirtualMachine" />Runtime (Virtual Machine)
* [hyperhq/runv](https://github.com/hyperhq/runv) - Hypervisor-based runtime for OCI * [hyperhq/runv](https://github.com/hyperhq/runv) - Hypervisor-based runtime for OCI
* [01org/cc-oci-runtime](https://github.com/01org/cc-oci-runtime) - Hypervisor-based OCI runtime for Intel® Architecture * [01org/cc-oci-runtime](https://github.com/01org/cc-oci-runtime) - Hypervisor-based OCI runtime for Intel® Architecture
## Testing & Tools ## <a name="implementationsTestingTools" />Testing & Tools
* [kunalkushwaha/octool](https://github.com/kunalkushwaha/octool) - A config linter and validator. * [kunalkushwaha/octool](https://github.com/kunalkushwaha/octool) - A config linter and validator.
* [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime * [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime

4
project.md
View File

@ -1,6 +1,6 @@
# Project docs # <a name="projectDocs" />Project docs
## Release Process ## <a name="projectReleaseProcess" />Release Process
* Increment version in [`specs-go/version.go`](specs-go/version.go) * Increment version in [`specs-go/version.go`](specs-go/version.go)
* `git commit` version increment * `git commit` version increment

24
runtime.md
View File

@ -1,11 +1,11 @@
# Runtime and Lifecycle # <a name="runtimeAndLifecycle" />Runtime and Lifecycle
## Scope of a Container ## <a name="runtimeScopeContainer" />Scope of a Container
Barring access control concerns, the entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container. Barring access control concerns, the entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container.
Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification. Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification.
## State ## <a name="runtimeState" />State
The state of a container includes the following properties: The state of a container includes the following properties:
@ -47,7 +47,7 @@ When serialized in JSON, the format MUST adhere to the following pattern:
See [Query State](#query-state) for information on retrieving the state of a container. See [Query State](#query-state) for information on retrieving the state of a container.
## Lifecycle ## <a name="runtimeLifecycle" />Lifecycle
The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist. 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's [`create`](runtime.md#create) command is invoked with a reference to the location of the bundle and a unique identifier. 1. OCI compliant runtime's [`create`](runtime.md#create) command is invoked with a reference to the location of the bundle and a unique identifier.
@ -64,18 +64,18 @@ The lifecycle describes the timeline of events that happen from when a container
6. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container. 6. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container.
The container MUST be destroyed by undoing the steps performed during create phase (step 2). The container MUST be destroyed by undoing the steps performed during create phase (step 2).
## Errors ## <a name="runtimeErrors" />Errors
In cases where the specified operation generates an error, this specification does not mandate how, or even if, that error is returned or exposed to the user of an implementation. In cases where the specified operation generates an error, this specification does not mandate how, or even if, that error is returned or exposed to the user of an implementation.
Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging. Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging.
## Operations ## <a name="runtimeOperations" />Operations
OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system. OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.
Note: these operations are not specifying any command-line APIs, and the parameters are inputs for general operations. Note: these operations are not specifying any command-line APIs, and the parameters are inputs for general operations.
### Query State ### <a name="runtimeQueryState" />Query State
`state <container-id>` `state <container-id>`
@ -83,7 +83,7 @@ This operation MUST generate an error if it is not provided the ID of a containe
Attempting to query a container that does not exist MUST generate an error. Attempting to query a container that does not exist MUST generate an error.
This operation MUST return the state of a container as specified in the [State](#state) section. This operation MUST return the state of a container as specified in the [State](#state) section.
### Create ### <a name="runtimeCreate" />Create
`create <container-id> <path-to-bundle>` `create <container-id> <path-to-bundle>`
@ -100,7 +100,7 @@ Runtime callers who are interested in pre-create validation can run [bundle-vali
Any changes made to the [`config.json`](config.md) file after this operation will not have an effect on the container. Any changes made to the [`config.json`](config.md) file after this operation will not have an effect on the container.
### Start ### <a name="runtimeStart" />Start
`start <container-id>` `start <container-id>`
This operation MUST generate an error if it is not provided the container ID. This operation MUST generate an error if it is not provided the container ID.
@ -110,7 +110,7 @@ This operation MUST run the user-specified program as specified by [`process`](c
Upon successful completion of this operation the `status` property of this container MUST be `running`. Upon successful completion of this operation the `status` property of this container MUST be `running`.
### Kill ### <a name="runtimeKill" />Kill
`kill <container-id> <signal>` `kill <container-id> <signal>`
This operation MUST generate an error if it is not provided the container ID. This operation MUST generate an error if it is not provided the container ID.
@ -119,7 +119,7 @@ This operation MUST send the specified signal to the process in the container.
When the process in the container is stopped, irrespective of it being as a result of a `kill` operation or any other reason, the `status` property of this container MUST be `stopped`. When the process in the container is stopped, irrespective of it being as a result of a `kill` operation or any other reason, the `status` property of this container MUST be `stopped`.
### Delete ### <a name="runtimeDelete" />Delete
`delete <container-id>` `delete <container-id>`
This operation MUST generate an error if it is not provided the container ID. This operation MUST generate an error if it is not provided the container ID.
@ -130,6 +130,6 @@ Note that resources associated with the container, but not created by this conta
Once a container is deleted its ID MAY be used by a subsequent container. Once a container is deleted its ID MAY be used by a subsequent container.
## Hooks ## <a name="runtimeHooks" />Hooks
Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation. Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation.
See [runtime configuration for hooks](./config.md#hooks) for more information. See [runtime configuration for hooks](./config.md#hooks) for more information.

10
spec.md
View File

@ -1,15 +1,15 @@
# Open Container Initiative Runtime Specification # <a name="openContainerInitiativeRuntimeSpecification" />Open Container Initiative Runtime Specification
The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers. The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers.
# Abstract # <a name="ociRuntimeSpecAbstract" />Abstract
The OCI Runtime Specification aims to specify the configuration, execution environment, and lifecycle a container. The OCI Runtime Specification aims to specify the configuration, execution environment, and lifecycle a container.
A container's configuration is specified as the `config.json` for the supported platforms and details the fields that enable the creation of a container. A container's configuration is specified as the `config.json` for the supported platforms and details the fields that enable the creation of a container.
The execution environment is specified to ensure that applications running inside a container have a consistent environment between runtimes along with common actions defined for the container's lifecycle. The execution environment is specified to ensure that applications running inside a container have a consistent environment between runtimes along with common actions defined for the container's lifecycle.
# Platforms # <a name="ociRuntimeSpecPlatforms" />Platforms
Platforms defined by this specification are: Platforms defined by this specification are:
@ -17,7 +17,7 @@ Platforms defined by this specification are:
* `solaris`: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md). * `solaris`: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md).
* `windows`: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md). * `windows`: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md).
# Table of Contents # <a name="ociRuntimeSpecTOC" />Table of Contents
- [Introduction](spec.md) - [Introduction](spec.md)
- [Notational Conventions](#notational-conventions) - [Notational Conventions](#notational-conventions)
@ -31,7 +31,7 @@ Platforms defined by this specification are:
- [Windows-specific Configuration](config-windows.md) - [Windows-specific Configuration](config-windows.md)
- [Glossary](glossary.md) - [Glossary](glossary.md)
# Notational Conventions # <a name="ociRuntimeSpecNotationalConventions" />Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119]. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119].

14
style.md
View File

@ -1,29 +1,29 @@
# Style and conventions # <a name="styleAndConventions" />Style and conventions
## One sentence per line ## <a name="styleOneSentence" />One sentence per line
To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line. 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. 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. For example, this paragraph will span three lines in the Markdown source.
## Traditionally hex settings should use JSON integers, not JSON strings ## <a name="styleHex" />Traditionally hex settings should use JSON integers, not JSON strings
For example, [`"classID": 1048577`][class-id] instead of `"classID": "0x100001"`. For example, [`"classID": 1048577`][class-id] instead of `"classID": "0x100001"`.
The config JSON isn't enough of a UI to be worth jumping through string <-> integer hoops to support an 0x… form ([source][integer-over-hex]). The config JSON isn't enough of a UI to be worth jumping through string <-> integer hoops to support an 0x… form ([source][integer-over-hex]).
## Constant names should keep redundant prefixes ## <a name="styleConstantNames" />Constant names should keep redundant prefixes
For example, `CAP_KILL` instead of `KILL` in [**`linux.capabilities`**][capabilities]. For example, `CAP_KILL` instead of `KILL` in [**`linux.capabilities`**][capabilities].
The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]). The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]).
## Optional settings should not have pointer Go types ## <a name="styleOptionalSettings" />Optional settings should not have pointer Go types
Because in many cases the Go default for the type is a no-op in the spec (sources [here][no-pointer-for-strings], [here][no-pointer-for-slices], and [here][no-pointer-for-boolean]). Because in many cases the Go default for the type is a no-op in the spec (sources [here][no-pointer-for-strings], [here][no-pointer-for-slices], and [here][no-pointer-for-boolean]).
The exceptions are entries where we need to distinguish between “not set” and “set to the Go default for that type” ([source][pointer-when-updates-require-changes]), and this decision should be made on a per-setting case. The exceptions are entries where we need to distinguish between “not set” and “set to the Go default for that type” ([source][pointer-when-updates-require-changes]), and this decision should be made on a per-setting case.
## Examples ## Examples
### Anchoring ### <a name="styleAnchoring" />Anchoring
For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers]. For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers].
The level of header should be such that it is a subheader of the header it is an example of. The level of header should be such that it is a subheader of the header it is an example of.
@ -47,7 +47,7 @@ To use Some Topic, ...
``` ```
### Content ### <a name="styleContent" />Content
Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention. Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention.