diff --git a/README.md b/README.md index 903eee258..c2b355c33 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ Read more on [How to Write a Git Commit Message][how-to-git-commit] or the Discu 5. Use the imperative mood in the subject line 6. Wrap the body at 72 characters 7. Use the body to explain what and why vs. how - * If there was important/useful/essential conversation or information, copy or include a reference + * If there was important/useful/essential conversation or information, copy or include a reference 8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...") diff --git a/RELEASES.md b/RELEASES.md index e220042c8..a28e086a7 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -43,9 +43,9 @@ Specifications have a variety of different timelines in their lifecycle. * Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback. * Major specification releases MUST release at least three release candidates spaced a minimum of one week apart. - This means a major release like a v1.0.0 or v2.0.0 release will take 1 month at minimum: one week for rc1, one week for rc2, one week for rc3, and one week for the major release itself. - Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced. - For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0. + This means a major release like a v1.0.0 or v2.0.0 release will take 1 month at minimum: one week for rc1, one week for rc2, one week for rc3, and one week for the major release itself. + Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced. + For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0. - Minor and patch releases SHOULD be made on an as-needed basis. [charter]: https://www.opencontainers.org/about/governance diff --git a/bundle.md b/bundle.md index dbb12b3e6..2cd4bb985 100644 --- a/bundle.md +++ b/bundle.md @@ -11,11 +11,12 @@ A Standard Container bundle contains all the information needed to load and run This includes the following artifacts: 1. `config.json`: contains configuration data. -This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`. -See [`config.json`](config.md) for more details. + This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`. + See [`config.json`](config.md) for more details. 2. A directory representing the root filesystem of the container. - On Windows, for Windows Server containers, this directory is REQUIRED. For Hyper-V containers, it MUST be omitted. + On Windows, for Windows Server containers, this directory is REQUIRED. + For Hyper-V containers, it MUST be omitted. On all other platforms, this field is REQUIRED. diff --git a/config-linux.md b/config-linux.md index ee91c64a3..d457184e4 100644 --- a/config-linux.md +++ b/config-linux.md @@ -115,12 +115,12 @@ The runtime may supply them however it likes (with [mknod][mknod.2], by bind mou Each entry has the following structure: * **`type`** *(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`. - More info in [mknod(1)][mknod.1]. + More info in [mknod(1)][mknod.1]. * **`path`** *(string, REQUIRED)* - full path to device inside container. - If a [file][] already exists at `path` that does not match the requested device, the runtime MUST generate an error. + If a [file][] already exists at `path` that does not match the requested device, the runtime MUST generate an error. * **`major, minor`** *(int64, REQUIRED unless `type` is `p`)* - [major, minor numbers][devices] for the device. * **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device. - You can also control access to devices [with cgroups](#device-whitelist). + You can also control access to devices [with cgroups](#device-whitelist). * **`uid`** *(uint32, OPTIONAL)* - id of device owner. * **`gid`** *(uint32, OPTIONAL)* - id of device group. @@ -129,7 +129,7 @@ The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices. ### Example ```json - "devices": [ + "devices": [ { "path": "/dev/fuse", "type": "c", @@ -194,18 +194,18 @@ Runtimes MAY attach the container process to additional cgroup controllers beyon ### Example ```json - "cgroupsPath": "/myRuntime/myContainer", - "resources": { - "memory": { - "limit": 100000, - "reservation": 200000 - }, - "devices": [ - { - "allow": false, - "access": "rwm" - } - ] + "cgroupsPath": "/myRuntime/myContainer", + "resources": { + "memory": { + "limit": 100000, + "reservation": 200000 + }, + "devices": [ + { + "allow": false, + "access": "rwm" + } + ] } ``` @@ -218,16 +218,16 @@ Each entry has the following structure: * **`allow`** *(boolean, REQUIRED)* - whether the entry is allowed or denied. * **`type`** *(string, OPTIONAL)* - type of device: `a` (all), `c` (char), or `b` (block). - Unset values mean "all", mapping to `a`. + Unset values mean "all", mapping to `a`. * **`major, minor`** *(int64, OPTIONAL)* - [major, minor numbers][devices] for the device. - Unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices]. + Unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices]. * **`access`** *(string, OPTIONAL)* - cgroup permissions for device. - A composition of `r` (read), `w` (write), and `m` (mknod). + A composition of `r` (read), `w` (write), and `m` (mknod). #### Example ```json - "devices": [ + "devices": [ { "allow": false, "access": "rwm" @@ -273,15 +273,10 @@ For more information, see the kernel cgroups documentation about [memory][cgroup The following parameters can be specified to set up the controller: * **`limit`** *(uint64, OPTIONAL)* - sets limit of memory usage in bytes - * **`reservation`** *(uint64, OPTIONAL)* - sets soft limit of memory usage in bytes - * **`swap`** *(uint64, OPTIONAL)* - sets limit of memory+Swap usage - * **`kernel`** *(uint64, OPTIONAL)* - sets hard limit for kernel memory - * **`kernelTCP`** *(uint64, OPTIONAL)* - sets hard limit in bytes for kernel TCP buffer memory - * **`swappiness`** *(uint64, OPTIONAL)* - sets swappiness parameter of vmscan (See sysctl's vm.swappiness) #### Example @@ -305,17 +300,11 @@ For more information, see the kernel cgroups documentation about [cpusets][cgrou The following parameters can be specified to set up the controller: * **`shares`** *(uint64, OPTIONAL)* - specifies a relative share of CPU time available to the tasks in a cgroup - * **`quota`** *(int64, OPTIONAL)* - specifies the total amount of time in microseconds for which all tasks in a cgroup can run during one period (as defined by **`period`** below) - * **`period`** *(uint64, OPTIONAL)* - specifies a period of time in microseconds for how regularly a cgroup's access to CPU resources should be reallocated (CFS scheduler only) - * **`realtimeRuntime`** *(int64, OPTIONAL)* - specifies a period of time in microseconds for the longest continuous period in which the tasks in a cgroup have access to CPU resources - * **`realtimePeriod`** *(uint64, OPTIONAL)* - same as **`period`** but applies to realtime scheduler only - * **`cpus`** *(string, OPTIONAL)* - list of CPUs the container will run in - * **`mems`** *(string, OPTIONAL)* - list of Memory Nodes the container will run in #### Example @@ -340,9 +329,7 @@ For more information, see the kernel cgroups documentation about [blkio][cgroup- The following parameters can be specified to set up the controller: * **`blkioWeight`** *(uint16, OPTIONAL)* - specifies per-cgroup weight. This is default weight of the group on all devices until and unless overridden by per-device rules. - * **`blkioLeafWeight`** *(uint16, OPTIONAL)* - equivalents of `blkioWeight` for the purpose of deciding how much weight tasks in the given cgroup has while competing with the cgroup's child cgroups. - * **`blkioWeightDevice`** *(array of objects, OPTIONAL)* - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device: * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. More info in [mknod(1)][mknod.1] man page. * **`weight`** *(uint16, OPTIONAL)* - bandwidth rate for the device. @@ -351,7 +338,7 @@ The following parameters can be specified to set up the controller: You MUST specify at least one of `weight` or `leafWeight` in a given entry, and MAY specify both. * **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array of objects, OPTIONAL)* - specify the list of devices which will be IO rate limited. - The following parameters can be specified per-device: + The following parameters can be specified per-device: * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. More info in [mknod(1)][mknod.1] man page. * **`rate`** *(uint64, REQUIRED)* - IO rate limit for the device @@ -400,13 +387,12 @@ For more information, see the kernel cgroups documentation about [HugeTLB][cgrou Each entry has the following structure: * **`pageSize`** *(string, REQUIRED)* - hugepage size - * **`limit`** *(uint64, REQUIRED)* - limit in bytes of *hugepagesize* HugeTLB usage #### Example ```json - "hugepageLimits": [ + "hugepageLimits": [ { "pageSize": "2MB", "limit": 209715200 @@ -422,16 +408,15 @@ For more information, see the kernel cgroups documentations about [net\_cls cgro The following parameters can be specified to set up the controller: * **`classID`** *(uint32, OPTIONAL)* - is the network class identifier the cgroup's network packets will be tagged with - * **`priorities`** *(array of objects, OPTIONAL)* - specifies a list of objects of the priorities assigned to traffic originating from processes in the group and egressing the system on various interfaces. - The following parameters can be specified per-priority: + The following parameters can be specified per-priority: * **`name`** *(string, REQUIRED)* - interface name in [runtime network namespace](glossary.md#runtime-namespace) * **`priority`** *(uint32, REQUIRED)* - priority applied to the interface #### Example ```json - "network": { + "network": { "classID": 1048577, "priorities": [ { @@ -458,7 +443,7 @@ The following parameters can be specified to set up the controller: #### Example ```json - "pids": { + "pids": { "limit": 32771 } ``` @@ -499,7 +484,7 @@ For more information, see the [sysctl(8)][sysctl.8] man page. ### Example ```json - "sysctl": { + "sysctl": { "net.ipv4.ip_forward": "1", "net.core.somaxconn": "256" } @@ -549,7 +534,6 @@ The following parameters can be specified to set up seccomp: * **`names`** *(array of strings, REQUIRED)* - the names of the syscalls. `names` MUST contain at least one entry. - * **`action`** *(string, REQUIRED)* - the action for seccomp rules. A valid list of constants as of libseccomp v2.3.2 is shown below. @@ -564,11 +548,8 @@ The following parameters can be specified to set up seccomp: Each entry has the following structure: * **`index`** *(uint, REQUIRED)* - the index for syscall arguments in seccomp. - * **`value`** *(uint64, REQUIRED)* - the value for syscall arguments in seccomp. - * **`valueTwo`** *(uint64, REQUIRED)* - the value for syscall arguments in seccomp. - * **`op`** *(string, REQUIRED)* - the operator for syscall arguments in seccomp. A valid list of constants as of libseccomp v2.3.2 is shown below. @@ -583,29 +564,29 @@ The following parameters can be specified to set up seccomp: ### Example ```json - "seccomp": { - "defaultAction": "SCMP_ACT_ALLOW", - "architectures": [ - "SCMP_ARCH_X86", - "SCMP_ARCH_X32" - ], - "syscalls": [ - { - "names": [ - "getcwd", - "chmod" - ], - "action": "SCMP_ACT_ERRNO" - } - ] - } + "seccomp": { + "defaultAction": "SCMP_ACT_ALLOW", + "architectures": [ + "SCMP_ARCH_X86", + "SCMP_ARCH_X32" + ], + "syscalls": [ + { + "names": [ + "getcwd", + "chmod" + ], + "action": "SCMP_ACT_ERRNO" + } + ] + } ``` ## Rootfs Mount Propagation **`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation. -Its value is either slave, private, shared or unbindable. -The [Shared Subtrees][sharedsubtree] article in the kernel documentation has more information about mount propagation. + Its value is either slave, private, shared or unbindable. + The [Shared Subtrees][sharedsubtree] article in the kernel documentation has more information about mount propagation. ### Example @@ -616,7 +597,7 @@ The [Shared Subtrees][sharedsubtree] article in the kernel documentation has mor ## 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](glossary.md#container_namespace). + The values MUST be absolute paths in the [container namespace](glossary.md#container_namespace). ### Example @@ -629,7 +610,7 @@ The values MUST be absolute paths in the [container namespace](glossary.md#conta ## 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](glossary.md#container-namespace). + The values MUST be absolute paths in the [container namespace](glossary.md#container-namespace). ### Example diff --git a/config-solaris.md b/config-solaris.md index 12ec2150d..4446a166a 100644 --- a/config-solaris.md +++ b/config-solaris.md @@ -83,21 +83,21 @@ For additional information on properties, check the [zonecfg(1M)][zonecfg.1m_2] * **`linkname`** *(string, OPTIONAL)* Specify a name for the automatically created VNIC datalink. * **`lowerLink`** *(string, OPTIONAL)* Specify the link over which the VNIC will be created. Mapped to `lower-link` in the [zonecfg(1M)][zonecfg.1m_2] man page. -* **`allowedAddress`** *(string, OPTIONAL)* The set of IP addresses that the container can use might be constrained by specifying the allowedAddress property. -If allowedAddress has not been specified, then they can use any IP address on the associated physical interface for the network resource. -Otherwise, when allowedAddress is specified, the container cannot use IP addresses that are not in the allowedAddress list for the physical address. -Mapped to `allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page. -* **`configureAllowedAddress`** *(string, OPTIONAL)* If configureAllowedAddress is set to true, the addresses specified by allowedAddress are automatically configured on the interface each time the container starts. -When it is set to false, the allowedAddress will not be configured on container start. -Mapped to `configure-allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page. +* **`allowedAddress`** *(string, OPTIONAL)* The set of IP addresses that the container can use might be constrained by specifying the `allowedAddress` property. + If `allowedAddress` has not been specified, then they can use any IP address on the associated physical interface for the network resource. + Otherwise, when `allowedAddress` is specified, the container cannot use IP addresses that are not in the `allowedAddress` list for the physical address. + Mapped to `allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page. +* **`configureAllowedAddress`** *(string, OPTIONAL)* If `configureAllowedAddress` is set to true, the addresses specified by `allowedAddress` are automatically configured on the interface each time the container starts. + When it is set to false, the `allowedAddress` will not be configured on container start. + Mapped to `configure-allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page. * **`defrouter`** *(string, OPTIONAL)* The value for the OPTIONAL default router. * **`macAddress`** *(string, OPTIONAL)* Set the VNIC's MAC addresses based on the specified value or keyword. -If not a keyword, it is interpreted as a unicast MAC address. -For a list of the supported keywords please refer to the [zonecfg(1M)][zonecfg.1m_2] man page of the respective Solaris release. -Mapped to `mac-address` in the [zonecfg(1M)][zonecfg.1m_2] man page. + If not a keyword, it is interpreted as a unicast MAC address. + For a list of the supported keywords please refer to the [zonecfg(1M)][zonecfg.1m_2] man page of the respective Solaris release. + Mapped to `mac-address` in the [zonecfg(1M)][zonecfg.1m_2] man page. * **`linkProtection`** *(string, OPTIONAL)* Enables one or more types of link protection using comma-separated values. -See the protection property in dladm(8) for supported values in respective release of Solaris. -Mapped to `link-protection` in the [zonecfg(1M)][zonecfg.1m_2] man page. + See the protection property in dladm(8) for supported values in respective release of Solaris. + Mapped to `link-protection` in the [zonecfg(1M)][zonecfg.1m_2] man page. #### Example ```json diff --git a/config-windows.md b/config-windows.md index b2a0c695d..2c5dda921 100644 --- a/config-windows.md +++ b/config-windows.md @@ -50,9 +50,7 @@ The following parameters can be specified: The following parameters can be specified: * **`count`** *(uint64, OPTIONAL)* - specifies the number of CPUs available to the container. - * **`shares`** *(uint16, OPTIONAL)* - specifies the relative weight to other containers with CPU shares. - * **`maximum`** *(uint, OPTIONAL)* - specifies the portion of processor cycles that this container can use as a percentage times 100. #### Example @@ -74,9 +72,7 @@ The following parameters can be specified: The following parameters can be specified: * **`iops`** *(uint64, OPTIONAL)* - specifies the maximum IO operations per second for the system drive of the container. - * **`bps`** *(uint64, OPTIONAL)* - specifies the maximum bytes per second for the system drive of the container. - * **`sandboxSize`** *(uint64, OPTIONAL)* - specifies the minimum size of the system drive in bytes. #### Example @@ -158,11 +154,15 @@ You can indicate that a container should be started in an a mode where disk flus ## HyperV -`hyperv` is an OPTIONAL field of the Windows configuration. If present, the container MUST be run with Hyper-V isolation. If omitted, the container MUST be run as a Windows Server container. +`hyperv` is an OPTIONAL field of the Windows configuration. +If present, the container MUST be run with Hyper-V isolation. +If omitted, the container MUST be run as a Windows Server container. The following parameters can be specified: -* **`utilityVMPath`** *(string, OPTIONAL)* - specifies the path to the image used for the utility VM. This would be specified if using a base image which does not contain a utility VM image. If not supplied, the runtime will search the container filesystem layers from the bottom-most layer upwards, until it locates "UtilityVM", and default to that path. +* **`utilityVMPath`** *(string, OPTIONAL)* - specifies the path to the image used for the utility VM. + This would be specified if using a base image which does not contain a utility VM image. + If not supplied, the runtime will search the container filesystem layers from the bottom-most layer upwards, until it locates "UtilityVM", and default to that path. ### Example @@ -172,4 +172,4 @@ The following parameters can be specified: "utilityVMPath": "C:\\path\\to\\utilityvm" } } -``` \ No newline at end of file +``` diff --git a/config.md b/config.md index 4fa7578bd..78de158cf 100644 --- a/config.md +++ b/config.md @@ -15,8 +15,8 @@ For all platform-specific configuration values, the scope defined below in the [ ## Specification version * **`ociVersion`** (string, REQUIRED) MUST be in [SemVer v2.0.0][semver-v2.0.0] 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. -For example, if a configuration is compliant with version 1.1 of this specification, it is compatible with all runtimes that support any 1.1 or later release of this specification, but is not compatible with a runtime that supports 1.0 and not 1.1. + The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions. + For example, if a configuration is compliant with version 1.1 of this specification, it is compatible with all runtimes that support any 1.1 or later release of this specification, but is not compatible with a runtime that supports 1.0 and not 1.1. ### Example @@ -28,17 +28,18 @@ For example, if a configuration is compliant with version 1.1 of this specificat **`root`** (object, REQUIRED) specifies the container's root filesystem. -* **`path`** (string, OPTIONAL) Specifies the path to the root filesystem for the container. The path is either an absolute path or a relative path to the bundle. +* **`path`** (string, OPTIONAL) Specifies the path to the root filesystem for the container. + The path is either an absolute path or a relative path to the bundle. Users SHOULD consider using a conventional name, such as `rootfs`. - On Windows, for Windows Server Containers, this field is REQUIRED and MUST be specified as a [volume GUID path][naming-a-volume]. For Hyper-V Containers, this field MUST be omitted. - - On all other platforms, this field is REQUIRED. - - On Linux, for example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`. + * On Windows, for Windows Server Containers, this field is REQUIRED and MUST be specified as a [volume GUID path][naming-a-volume]. + For Hyper-V Containers, this field MUST be omitted. + * On all other platforms, this field is REQUIRED. + * On Linux, for example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`. If defined, a directory MUST exist at the path declared by the field. -* **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false. On Windows, this field must be omitted or false. +* **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false. + * On Windows, this field MUST be omitted or false. ### Example (POSIX) @@ -60,25 +61,25 @@ For example, if a configuration is compliant with version 1.1 of this specificat ## Mounts **`mounts`** (array of objects, OPTIONAL) specifies additional mounts beyond [`root`](#root). -The runtime MUST mount entries in the listed order. -For Linux, the parameters are as documented in [mount(2)][mount.2] system call man page. -For Solaris, the mount entry corresponds to the 'fs' resource in the [zonecfg(1M)][zonecfg.1m] man page. + The runtime MUST mount entries in the listed order. + For Linux, the parameters are as documented in [mount(2)][mount.2] system call man page. + For Solaris, the mount entry corresponds to the 'fs' resource in the [zonecfg(1M)][zonecfg.1m] man page. * **`destination`** (string, REQUIRED) Destination of mount point: path inside container. - This value MUST be an absolute path. - * Windows: one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar). - * Solaris: corresponds to "dir" of the fs resource in [zonecfg(1M)][zonecfg.1m]. + This value MUST be an absolute path. + * Windows: one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar). + * Solaris: corresponds to "dir" of the fs resource in [zonecfg(1M)][zonecfg.1m]. * **`type`** (string, OPTIONAL) The type of the filesystem to be mounted. - * Linux: filesystem types supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). - * Windows: this field MUST NOT be supplied. - * Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m]. + * Linux: filesystem types supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). + * Windows: this field MUST NOT be supplied. + * Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m]. * **`source`** (string, OPTIONAL) A device name, but can also be a directory name or a dummy. - * Windows: a local directory on the filesystem of the container host. UNC paths and mapped drives are not supported. - * Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m]. + * Windows: a local directory on the filesystem of the container host. UNC paths and mapped drives are not supported. + * Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m]. * **`options`** (array of strings, OPTIONAL) Mount options of the filesystem to be used. - * Linux: supported options are listed in the [mount(8)][mount.8] man page. Note both [filesystem-independent][mount.8-filesystem-independent] and [filesystem-specific][mount.8-filesystem-specific] options are listed. - * Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m]. + * Linux: supported options are listed in the [mount(8)][mount.8] man page. Note both [filesystem-independent][mount.8-filesystem-independent] and [filesystem-specific][mount.8-filesystem-specific] options are listed. + * Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m]. ### Example (Linux) @@ -132,41 +133,45 @@ For Solaris, the mount entry corresponds to the 'fs' resource in the [zonecfg(1M ## Process **`process`** (object, OPTIONAL) specifies the container process. - This property is REQUIRED when [`start`](runtime.md#start) is called. + This property is REQUIRED when [`start`](runtime.md#start) is called. * **`terminal`** (bool, OPTIONAL) specifies whether a terminal is attached to that process, defaults to false. - As an example, if set to true on Linux a pseudoterminal pair is allocated for the container process and the pseudoterminal slave is duplicated on the container process's [standard streams][stdin.3]. + As an example, if set to true on Linux a pseudoterminal pair is allocated for the container process and the pseudoterminal slave is duplicated on the container process's [standard streams][stdin.3]. * **`consoleSize`** (object, OPTIONAL) specifies the console size in characters of the terminal if attached, containing the following properties: * **`height`** (uint, REQUIRED) * **`width`** (uint, REQUIRED) * **`cwd`** (string, REQUIRED) is the working directory that will be set for the executable. - This value MUST be an absolute path. + This value MUST be an absolute path. * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2001's `environ`][ieee-1003.1-2001-xbd-c8.1]. * **`args`** (array of strings, REQUIRED) with similar semantics to [IEEE Std 1003.1-2001 `execvp`'s *argv*][ieee-1003.1-2001-xsh-exec]. - This specification extends the IEEE standard in that at least one entry is REQUIRED, and that entry is used with the same semantics as `execvp`'s *file*. -* **`capabilities`** (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process(es) inside the container. Valid values are platform-specific. For example, valid values for Linux are defined in the [capabilities(7)][capabilities.7] man page, such as `CAP_CHOWN`. Any value which cannot be mapped to a relevant kernel interface MUST cause an error. - capabilities contains the following properties: + This specification extends the IEEE standard in that at least one entry is REQUIRED, and that entry is used with the same semantics as `execvp`'s *file*. +* **`capabilities`** (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process(es) inside the container. + Valid values are platform-specific. + For example, valid values for Linux are defined in the [capabilities(7)][capabilities.7] man page, such as `CAP_CHOWN`. + Any value which cannot be mapped to a relevant kernel interface MUST cause an error. + capabilities contains the following properties: * **`effective`** (array of strings, OPTIONAL) - the `effective` field is an array of effective capabilities that are kept for the process. * **`bounding`** (array of strings, OPTIONAL) - the `bounding` field is an array of bounding capabilities that are kept for the process. * **`inheritable`** (array of strings, OPTIONAL) - the `inheritable` field is an array of inheritable capabilities that are kept for the process. * **`permitted`** (array of strings, OPTIONAL) - the `permitted` field is an array of permitted capabilities that are kept for the process. * **`ambient`** (array of strings, OPTIONAL) - the `ambient` field is an array of ambient capabilities that are kept for the process. * **`rlimits`** (array of objects, OPTIONAL) allows setting resource limits for a process inside the container. - Each entry has the following structure: + Each entry has the following structure: * **`type`** (string, REQUIRED) - the platform resource being limited, for example on Linux as defined in the [setrlimit(2)][setrlimit.2] man page. * **`soft`** (uint64, REQUIRED) - the value of the limit enforced for the corresponding resource. - * **`hard`** (uint64, REQUIRED) - the ceiling for the soft limit that could be set by an unprivileged process. Only a privileged process (e.g. under Linux: one with the CAP_SYS_RESOURCE capability) can raise a hard limit. + * **`hard`** (uint64, REQUIRED) - the ceiling for the soft limit that could be set by an unprivileged process. + Only a privileged process (e.g. under Linux: one with the CAP_SYS_RESOURCE capability) can raise a hard limit. If `rlimits` contains duplicated entries with same `type`, the runtime MUST error out. * **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges. - As an example, the ['no_new_privs'][no-new-privs] article in the kernel documentation has information on how this is achieved using a prctl system call on Linux. + As an example, the ['no_new_privs'][no-new-privs] article in the kernel documentation has information on how this is achieved using a prctl system call on Linux. For Linux-based systems the process structure supports the following process-specific fields. * **`apparmorProfile`** (string, OPTIONAL) specifies the name of the AppArmor profile to be applied to processes in the container. - For more information about AppArmor, see [AppArmor documentation][apparmor]. + For more information about AppArmor, see [AppArmor documentation][apparmor]. * **`oomScoreAdj`** *(int, OPTIONAL)* adjusts the oom-killer score in `[pid]/oom_score_adj` for the container process's `[pid]` in a [proc pseudo-filesystem][procfs]. If `oomScoreAdj` is set, the runtime MUST set `oom_score_adj` to the given value. If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`. @@ -174,7 +179,7 @@ For Linux-based systems the process structure supports the following process-spe This is a per-process setting, where as [`disableOOMKiller`](config-linux.md#disable-out-of-memory-killer) is scoped for a memory cgroup. For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory_2]. * **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label to be applied to the processes in the container. - For more information about SELinux, see [SELinux documentation][selinux]. + For more information about SELinux, see [SELinux documentation][selinux]. ### User @@ -301,8 +306,8 @@ For Windows based systems the user structure has the following fields: ## 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](glossary.md#container-namespace) [UTS namespace][uts-namespace.7]. - Depending on your [namespace configuration](config-linux.md#namespaces), the container UTS namespace may be the [runtime](glossary.md#runtime-namespace) [UTS namespace][uts-namespace.7]. + On Linux, for example, this will change the hostname in the [container](glossary.md#container-namespace) [UTS namespace][uts-namespace.7]. + Depending on your [namespace configuration](config-linux.md#namespaces), the container UTS namespace may be the [runtime](glossary.md#runtime-namespace) [UTS namespace][uts-namespace.7]. ### Example @@ -315,13 +320,13 @@ For Windows based systems the user structure has the following fields: **`platform`** (object, REQUIRED) specifies the configuration's target platform. * **`os`** (string, REQUIRED) specifies the operating system family of the container configuration's specified [`root`](#root) file system bundle. - The runtime MUST generate an error if it does not support the specified **`os`**. - Bundles 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. + The runtime MUST generate an error if it does not support the specified **`os`**. + Bundles 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 specified [`root`](#root) file system bundle have been compiled. - The runtime MUST generate an error if it does not support the specified **`arch`**. - Values for **`arch`** SHOULD use, and runtimes SHOULD understand, **`arch`** entries listed in the Go Language document for [`GOARCH`][go-environment]. - If an architecture is not included in the `GOARCH` documentation, it SHOULD be submitted to this specification for standardization. + The runtime MUST generate an error if it does not support the specified **`arch`**. + Values for **`arch`** SHOULD use, and runtimes SHOULD understand, **`arch`** entries listed in the Go Language document for [`GOARCH`][go-environment]. + If an architecture is not included in the `GOARCH` documentation, it SHOULD be submitted to this specification for standardization. ### Example @@ -335,14 +340,14 @@ For Windows based systems the user structure has the following fields: ## 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. * **`linux`** (object, OPTIONAL) [Linux-specific configuration](config-linux.md). - This MAY be set if **`platform.os`** is `linux` and MUST NOT be set otherwise. + This MAY be set if **`platform.os`** is `linux` and MUST NOT be set otherwise. * **`windows`** (object, OPTIONAL) [Windows-specific configuration](config-windows.md). - This MUST be set if **`platform.os`** is `windows` and MUST NOT be set otherwise. + This MUST be set if **`platform.os`** is `windows` and MUST NOT be set otherwise. * **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md). - This MAY be set if **`platform.os`** is `solaris` and MUST NOT be set otherwise. + This MAY be set if **`platform.os`** is `solaris` and MUST NOT be set otherwise. ### Example (Linux) @@ -354,9 +359,9 @@ Runtime implementations MAY support any valid values for platform-specific field }, "linux": { "namespaces": [ - { - "type": "pid" - } + { + "type": "pid" + } ] } } @@ -432,19 +437,19 @@ Cleanup or debugging functions are examples of such a hook. ## Annotations **`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container. -This information MAY be structured or unstructured. -Annotations MUST be a key-value map. -If there are no annotations then this property MAY either be absent or an empty map. + This information MAY be structured or unstructured. + Annotations MUST be a key-value map. + If there are no annotations then this property MAY either be absent or an empty map. -Keys MUST be strings. -Keys MUST be unique within this map. -Keys MUST NOT be an empty string. -Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`. -Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications. -Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key. + Keys MUST be strings. + Keys MUST be unique within this map. + Keys MUST NOT be an empty string. + Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`. + Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications. + Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key. -Values MUST be strings. -Values MAY be an empty string. + Values MUST be strings. + Values MAY be an empty string. ```json "annotations": { @@ -453,6 +458,7 @@ Values MAY be an empty string. ``` ## 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. diff --git a/runtime.md b/runtime.md index a1fad879a..b9c3b94d7 100644 --- a/runtime.md +++ b/runtime.md @@ -11,10 +11,10 @@ The state of a container includes the following properties: * **`ociVersion`** (string, REQUIRED) is the OCI specification version used when creating the container. * **`id`** (string, REQUIRED) is the container's ID. -This MUST be unique across all containers on this host. -There is no requirement that it be unique across hosts. + This MUST be unique across all containers on this host. + There is no requirement that it be unique across hosts. * **`status`** (string, REQUIRED) is the runtime state of the container. -The value MAY be one of: + The value MAY be one of: * `creating`: the container is being created (step 2 in the [lifecycle](#lifecycle)) * `created`: the runtime has finished the [create operation](#create) (after step 2 in the [lifecycle](#lifecycle)), and the container process has neither exited nor executed the user-specified program @@ -24,9 +24,9 @@ The value MAY be one of: Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above. * **`pid`** (int, REQUIRED when `status` is `created` or `running`) is the ID of the container process, as seen by the host. * **`bundle`** (string, REQUIRED) is the absolute path to the container's bundle directory. -This is provided so that consumers can find the container's configuration and root filesystem on the host. + This is provided so that consumers can find the container's configuration and root filesystem on the host. * **`annotations`** (map, OPTIONAL) contains the list of annotations associated with the container. -If no annotations were provided then this property MAY either be absent or an empty map. + If no annotations were provided then this property MAY either be absent or an empty map. The state MAY include additional properties. @@ -52,17 +52,17 @@ The lifecycle describes the timeline of events that happen from when a container 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. 2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md). - If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST [generate an error](#errors). - While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified program (from [`process`](config.md#process)) MUST NOT be run at this time. - Any updates to [`config.json`](config.md) after this step MUST NOT affect the container. + If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST [generate an error](#errors). + While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified program (from [`process`](config.md#process)) MUST NOT be run at this time. + Any updates to [`config.json`](config.md) after this step MUST NOT affect the container. 3. Runtime's [`start`](runtime.md#start) command is invoked with the unique identifier of the container. 4. The [prestart hooks](config.md#prestart) MUST be invoked by the runtime. - If any prestart hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 9. + If any prestart hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 9. 5. The runtime MUST run the user-specified program, as specified by [`process`](config.md#process). 6. The [poststart hooks](config.md#poststart) MUST be invoked by the runtime. - If any poststart hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded. + If any poststart hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded. 7. The container process exits. - This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked. + This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked. 8. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container. 9. The container MUST be destroyed by undoing the steps performed during create phase (step 2). 10. The [poststop hooks](config.md#poststop) MUST be invoked by the runtime.