From d01ef9a80605925119cdf0bc1c51e8bb07ec6a78 Mon Sep 17 00:00:00 2001 From: Mrunal Patel Date: Thu, 2 Mar 2017 11:00:31 -0800 Subject: [PATCH 1/3] Add anchors to config and config linux Signed-off-by: Mrunal Patel --- config-linux.md | 44 ++++++++++++++++++++++---------------------- config.md | 34 +++++++++++++++++----------------- 2 files changed, 39 insertions(+), 39 deletions(-) diff --git a/config-linux.md b/config-linux.md index b02741c7..d7776563 100644 --- a/config-linux.md +++ b/config-linux.md @@ -1,9 +1,9 @@ -# Linux-specific Container Configuration +# Linux Container Configuration 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. -## Default Filesystems +## Default Filesystems 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. @@ -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/shm | [tmpfs](https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt) | -## Namespaces +## 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. 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 +## User namespace mappings **`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. @@ -104,7 +104,7 @@ Note that the number of mapping entries MAY be limited by the [kernel][user-name ] ``` -## Devices +## Devices **`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.). @@ -148,7 +148,7 @@ The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices. ] ``` -###### Default Devices +###### Default Devices 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]. A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts]. -## Control groups +## Control groups 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. @@ -207,7 +207,7 @@ However, a runtime MAY attach the container process to additional cgroup control } ``` -#### Device whitelist +#### Device whitelist **`devices`** (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices]. The runtime MUST apply entries in the listed order. @@ -247,7 +247,7 @@ Each entry has the following structure: ] ``` -#### Disable out-of-memory killer +#### Disable out-of-memory killer `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. @@ -263,7 +263,7 @@ For more information, see [the memory cgroup man page][cgroup-v1-memory]. "disableOOMKiller": false ``` -#### Set oom_score_adj +#### Set oom_score_adj `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). @@ -278,7 +278,7 @@ For more information on how these two settings work together, see [the memory cg "oomScoreAdj": 100 ``` -#### Memory +#### Memory **`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]. @@ -310,7 +310,7 @@ The following parameters can be specified to setup the controller: } ``` -#### CPU +#### CPU **`cpu`** (object, OPTIONAL) represents the cgroup subsystems `cpu` and `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 +#### Block IO **`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]. @@ -404,7 +404,7 @@ The following parameters can be specified to setup the controller: } ``` -#### Huge page limits +#### Huge page limits **`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. @@ -427,7 +427,7 @@ Each entry has the following structure: ] ``` -#### Network +#### Network **`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]. @@ -459,7 +459,7 @@ The following parameters can be specified to setup the controller: } ``` -#### PIDs +#### PIDs **`pids`** (object, OPTIONAL) represents the cgroup subsystem `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 +## Sysctl **`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) @@ -490,7 +490,7 @@ For more information, see [the man page](http://man7.org/linux/man-pages/man8/sy } ``` -## seccomp +## Seccomp 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. @@ -554,7 +554,7 @@ Operator Constants: } ``` -## Rootfs Mount Propagation +## Rootfs Mount Propagation **`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation. Its value is either slave, private, or shared. @@ -566,7 +566,7 @@ Its value is either slave, private, or shared. "rootfsPropagation": "slave", ``` -## Masked Paths +## Masked Paths **`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]. @@ -579,7 +579,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa ] ``` -## Readonly Paths +## Readonly Paths **`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]. @@ -592,7 +592,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa ] ``` -## Mount Label +## Mount Label **`mountLabel`** (string, OPTIONAL) will set the Selinux context for the mounts in the container. diff --git a/config.md b/config.md index 72bae554..aeffae31 100644 --- a/config.md +++ b/config.md @@ -1,4 +1,4 @@ -# Container Configuration file +# Container Configuration file 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). @@ -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. -## Specification version +## 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. 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" ``` -## Root Configuration +## Root **`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 +## Mounts **`mounts`** (array, OPTIONAL) specifies additional mounts beyond [`root`](#root-configuration). 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 +## 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. For more information about SELinux, see [SELinux documentation](http://selinuxproject.org/page/Main_Page) -### User +### User 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 +#### Linux and Solaris User 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 +#### Windows User 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 +## Hostname * **`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]. @@ -292,7 +292,7 @@ For Windows based systems the user structure has the following fields: "hostname": "mrsdalloway" ``` -## Platform +## 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 +## 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. @@ -345,7 +345,7 @@ Implementations MUST error out when invalid values are encountered and MUST gene } ``` -## Hooks +## Hooks 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. 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 +### Prestart 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). 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 +### Poststart 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. If a hook returns a non-zero exit code, then an error MUST be logged and the remaining hooks are executed. -### Poststop +### Poststop The post-stop hooks MUST be called after the container process is stopped. 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 +## Annotations **`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container. This information MAY be structured or unstructured. @@ -438,7 +438,7 @@ Values MAY be an empty string. } ``` -## Extensibility +## Extensibility 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. From 4b0755490ea964de08d36372b0fe7eb5100a82bf Mon Sep 17 00:00:00 2001 From: Mrunal Patel Date: Thu, 2 Mar 2017 11:00:53 -0800 Subject: [PATCH 2/3] Add anchors to runtime Signed-off-by: Mrunal Patel --- runtime.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/runtime.md b/runtime.md index e43ad897..84dce36e 100644 --- a/runtime.md +++ b/runtime.md @@ -1,11 +1,11 @@ -# Runtime and Lifecycle +# Runtime and Lifecycle -## Scope of a Container +## 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. Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification. -## State +## State 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. -## Lifecycle +## 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'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. The container MUST be destroyed by undoing the steps performed during create phase (step 2). -## Errors +## 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. 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 +## Operations 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. -### Query State +### Query State `state ` @@ -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. This operation MUST return the state of a container as specified in the [State](#state) section. -### Create +### Create `create ` @@ -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. -### Start +### Start `start ` 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`. -### Kill +### Kill `kill ` 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`. -### Delete +### Delete `delete ` 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. -## Hooks +## Hooks 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. From c942816d76bc3c57844fec72ae9db7e7b49f6323 Mon Sep 17 00:00:00 2001 From: Mrunal Patel Date: Thu, 2 Mar 2017 11:01:18 -0800 Subject: [PATCH 3/3] Add anchors to misc. docs Signed-off-by: Mrunal Patel --- implementations.md | 8 ++++---- project.md | 4 ++-- spec.md | 10 +++++----- style.md | 14 +++++++------- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/implementations.md b/implementations.md index 218bb8c5..c4076b62 100644 --- a/implementations.md +++ b/implementations.md @@ -1,18 +1,18 @@ -# 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. 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) +## Runtime (Container) * [opencontainers/runc](https://github.com/opencontainers/runc) - Reference implementation of OCI runtime -## Runtime (Virtual Machine) +## Runtime (Virtual Machine) * [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 -## Testing & Tools +## Testing & Tools * [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 diff --git a/project.md b/project.md index 2f8f0767..f58f8f53 100644 --- a/project.md +++ b/project.md @@ -1,6 +1,6 @@ -# Project docs +# Project docs -## Release Process +## Release Process * Increment version in [`specs-go/version.go`](specs-go/version.go) * `git commit` version increment diff --git a/spec.md b/spec.md index 159efb01..38ae7a13 100644 --- a/spec.md +++ b/spec.md @@ -1,15 +1,15 @@ -# Open Container Initiative Runtime Specification +# Open Container Initiative Runtime Specification The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers. -# Abstract +# Abstract 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. 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 +# Platforms 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). * `windows`: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md). -# Table of Contents +# Table of Contents - [Introduction](spec.md) - [Notational Conventions](#notational-conventions) @@ -31,7 +31,7 @@ Platforms defined by this specification are: - [Windows-specific Configuration](config-windows.md) - [Glossary](glossary.md) -# Notational Conventions +# 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]. diff --git a/style.md b/style.md index bb5bced4..f2879e22 100644 --- a/style.md +++ b/style.md @@ -1,29 +1,29 @@ -# Style and conventions +# Style and conventions -## One sentence per line +## 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. For example, this paragraph will span three lines in the Markdown source. -## Traditionally hex settings should use JSON integers, not JSON strings +## Traditionally hex settings should use JSON integers, not JSON strings 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]). -## Constant names should keep redundant prefixes +## Constant names should keep redundant prefixes 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]). -## Optional settings should not have pointer Go types +## 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]). 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 -### Anchoring +### Anchoring 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. @@ -47,7 +47,7 @@ To use Some Topic, ... ``` -### Content +### Content Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention.