Bump up github.com/opencontainers/specs to cf8dd12093
Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
This commit is contained in:
Mrunal Patel
parent
902c012e85
commit
f184a880a2
|
|
@ -53,8 +53,8 @@
|
|||
},
|
||||
{
|
||||
"ImportPath": "github.com/opencontainers/specs",
|
||||
"Comment": "v0.1.1-16-g96bcd04",
|
||||
"Rev": "96bcd043aa8a28f6f64c95ad61329765f01de1ba"
|
||||
"Comment": "v0.1.1-55-gcf8dd12",
|
||||
"Rev": "cf8dd120937acc3593708f99304c51cfd0f73240"
|
||||
},
|
||||
{
|
||||
"ImportPath": "github.com/seccomp/libseccomp-golang",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
language: go
|
||||
go:
|
||||
- 1.4.2
|
||||
- 1.5.1
|
||||
- 1.4.3
|
||||
- 1.3.3
|
||||
|
||||
sudo: false
|
||||
|
|
@ -8,11 +9,12 @@ sudo: false
|
|||
before_install:
|
||||
- go get golang.org/x/tools/cmd/vet
|
||||
- go get github.com/golang/lint/golint
|
||||
- go get github.com/vbatts/git-validation
|
||||
|
||||
install: true
|
||||
|
||||
script:
|
||||
- go vet -x ./...
|
||||
- $HOME/gopath/bin/golint ./...
|
||||
- go run .tools/validate.go -range ${TRAVIS_COMMIT_RANGE}
|
||||
- $HOME/gopath/bin/git-validation -run DCO,short-subject -v -range ${TRAVIS_COMMIT_RANGE}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +1,22 @@
|
|||
# Open Container Specifications
|
||||
|
||||
This project is where the [Open Container Initiative](http://www.opencontainers.org/) Specifications are written.
|
||||
This is a work in progress.
|
||||
[Open Container Initiative](http://www.opencontainers.org/) Specifications for standards on Operating System process and application containers.
|
||||
|
||||
|
||||
Table of Contents
|
||||
|
||||
- [Container Principles](principles.md)
|
||||
- [Filesystem Bundle](bundle.md)
|
||||
- [Container Configuration](config.md)
|
||||
- [Linux Specific Configuration](config-linux.md)
|
||||
- Configuration
|
||||
- [Container Configuration](config.md)
|
||||
- [Container Configuration (Linux-specific)](config-linux.md)
|
||||
- [Runtime Configuration](runtime-config.md)
|
||||
- [Runtime Configuration (Linux-specific)](runtime-config-linux.md)
|
||||
- [Runtime and Lifecycle](runtime.md)
|
||||
- [Linux Specific Runtime](runtime-linux.md)
|
||||
- [Implementations](implementations.md)
|
||||
|
||||
## Use Cases
|
||||
# Use Cases
|
||||
|
||||
To provide context for users the following section gives example use cases for each part of the spec.
|
||||
|
||||
|
|
@ -24,58 +29,6 @@ To provide context for users the following section gives example use cases for e
|
|||
There is a loose [Road Map](https://github.com/opencontainers/specs/wiki/RoadMap:) on the wiki.
|
||||
During the `0.x` series of OCI releases we make no backwards compatibility guarantees and intend to break the schema during this series.
|
||||
|
||||
# The 5 principles of Standard Containers
|
||||
|
||||
Define a unit of software delivery called a Standard Container.
|
||||
The goal of a Standard Container is to encapsulate a software component and all its dependencies in a format that is self-describing and portable, so that any compliant runtime can run it without extra dependencies, regardless of the underlying machine and the contents of the container.
|
||||
|
||||
The specification for Standard Containers is straightforward.
|
||||
It mostly defines 1) a file format, 2) a set of standard operations, and 3) an execution environment.
|
||||
|
||||
A great analogy for this is the shipping container.
|
||||
Just like how Standard Containers are a fundamental unit of software delivery, shipping containers are a fundamental unit of physical delivery.
|
||||
|
||||
## 1. Standard operations
|
||||
|
||||
Just like shipping containers, Standard Containers define a set of STANDARD OPERATIONS.
|
||||
Shipping containers can be lifted, stacked, locked, loaded, unloaded and labelled.
|
||||
Similarly, Standard Containers can be created, started, and stopped using standard container tools (what this spec is about); copied and snapshotted using standard filesystem tools; and downloaded and uploaded using standard network tools.
|
||||
|
||||
## 2. Content-agnostic
|
||||
|
||||
Just like shipping containers, Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents.
|
||||
A shipping container will be stacked in exactly the same way whether it contains Vietnamese powder coffee or spare Maserati parts.
|
||||
Similarly, Standard Containers are started or uploaded in the same way whether they contain a postgres database, a php application with its dependencies and application server, or Java build artifacts.
|
||||
|
||||
## 3. Infrastructure-agnostic
|
||||
|
||||
Both types of containers are INFRASTRUCTURE-AGNOSTIC: they can be transported to thousands of facilities around the world, and manipulated by a wide variety of equipment.
|
||||
A shipping container can be packed in a factory in Ukraine, transported by truck to the nearest routing center, stacked onto a train, loaded into a German boat by an Australian-built crane, stored in a warehouse at a US facility, etc.
|
||||
Similarly, a standard container can be bundled on my laptop, uploaded to S3, downloaded, run and snapshotted by a build server at Equinix in Virginia, uploaded to 10 staging servers in a home-made Openstack cluster, then sent to 30 production instances across 3 EC2 regions.
|
||||
|
||||
## 4. Designed for automation
|
||||
|
||||
Because they offer the same standard operations regardless of content and infrastructure, Standard Containers, just like their physical counterparts, are extremely well-suited for automation.
|
||||
In fact, you could say automation is their secret weapon.
|
||||
|
||||
Many things that once required time-consuming and error-prone human effort can now be programmed.
|
||||
Before shipping containers, a bag of powder coffee was hauled, dragged, dropped, rolled and stacked by 10 different people in 10 different locations by the time it reached its destination.
|
||||
1 out of 50 disappeared.
|
||||
1 out of 20 was damaged.
|
||||
The process was slow, inefficient and cost a fortune - and was entirely different depending on the facility and the type of goods.
|
||||
|
||||
Similarly, before Standard Containers, by the time a software component ran in production, it had been individually built, configured, bundled, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers.
|
||||
Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken.
|
||||
The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider.
|
||||
|
||||
## 5. Industrial-grade delivery
|
||||
|
||||
There are 17 million shipping containers in existence, packed with every physical good imaginable.
|
||||
Every single one of them can be loaded onto the same boats, by the same cranes, in the same facilities, and sent anywhere in the World with incredible efficiency.
|
||||
It is embarrassing to think that a 30 ton shipment of coffee can safely travel half-way across the World in *less time* than it takes a software team to deliver its code from one datacenter to another sitting 10 miles away.
|
||||
|
||||
With Standard Containers we can put an end to that embarrassment, by making INDUSTRIAL-GRADE DELIVERY of software a reality.
|
||||
|
||||
# Contributing
|
||||
|
||||
Development happens on GitHub for the spec.
|
||||
|
|
@ -103,7 +56,7 @@ When in doubt, start on the [mailing-list](#mailing-list).
|
|||
The contributors and maintainers of the project have a weekly meeting Wednesdays at 10:00 AM PST.
|
||||
Everyone is welcome to participate in the [BlueJeans call][BlueJeans].
|
||||
An initial agenda will be posted to the [mailing list](#mailing-list) earlier in the week, and everyone is welcome to propose additional topics or suggest other agenda alterations there.
|
||||
Minutes for the call will be posted to the [mailing list](#mailing-list) for those who are unable to join the call.
|
||||
Minutes are posted to the [mailing list](#mailing-list) and minutes from past calls are archived to the [wiki](https://github.com/opencontainers/specs/wiki) for those who are unable to join the call.
|
||||
|
||||
## Mailing List
|
||||
|
||||
|
|
|
|||
|
|
@ -1,34 +1,27 @@
|
|||
# Bundle Container Format
|
||||
# Filesystem Bundle
|
||||
|
||||
This section defines a format for encoding a container as a *bundle* - a directory organized in a certain way, and containing all the necessary data and metadata for any compliant runtime to perform all standard operations against it.
|
||||
## Container Format
|
||||
|
||||
This section defines a format for encoding a container as a *filesystem bundle* - a set of files organized in a certain way, and containing all the necessary data and metadata for any compliant runtime to perform all standard operations against it.
|
||||
See also [OS X application bundles](http://en.wikipedia.org/wiki/Bundle_%28OS_X%29) for a similar use of the term *bundle*.
|
||||
|
||||
The format does not define distribution.
|
||||
In other words, it only specifies how a container must be stored on a local filesystem, for consumption by a runtime.
|
||||
It does not specify how to transfer a container between computers, how to discover containers, or assign names or versions to them.
|
||||
Any distribution method capable of preserving the original layout of a container, as specified here, is considered compliant.
|
||||
The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local file system so that it can be consumed by a compliant runtime.
|
||||
|
||||
A standard container bundle is made of the following 3 parts:
|
||||
A Standard Container bundle contains all the information needed to load and run a container.
|
||||
This includes the following three artifacts which MUST all reside in the same directory on the local filesystem:
|
||||
|
||||
- A top-level directory holding everything else
|
||||
- One or more content directories
|
||||
- A configuration file
|
||||
1. `config.json` : immutable, host independent configuration.
|
||||
This REQUIRED file, which MUST be named `config.json`, contains settings that are host independent and application specific such as security permissions, environment variables and arguments.
|
||||
See [`config.json`](config.md) for more details.
|
||||
|
||||
# Directory layout
|
||||
2. `runtime.json` : mutable, host dependent configuration.
|
||||
This REQUIRED file, which MUST be named `runtime.json`, contains settings that are host specific such as memory limits, local device access and mount sources.
|
||||
The goal is that the bundle can be moved as a unit to another runtime and run the same application if `runtime.json` is reconfigured.
|
||||
See [`runtime.json`](runtime-config.md) for more details.
|
||||
|
||||
A Standard Container bundle is a directory containing all the content needed to load and run a container.
|
||||
This includes two configuration files `config.json` and `runtime.json`, and a rootfs directory.
|
||||
The `config.json` file contains settings that are host independent and application specific such as security permissions, environment variables and arguments.
|
||||
The `runtime.json` file contains settings that are host specific such as memory limits, local device access and mount points.
|
||||
The goal is that the bundle can be moved as a unit to another machine and run the same application if `runtime.json` is removed or reconfigured.
|
||||
3. A directory representing the root filesystem of the container.
|
||||
While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs`.
|
||||
This directory MUST be referenced from within the `config.json` file.
|
||||
|
||||
The syntax and semantics for `config.json` are described in [this specification](config.md).
|
||||
|
||||
A single `rootfs` directory MUST be in the same directory as the `config.json`.
|
||||
The names of the directories may be arbitrary, but users should consider using conventional names as in the example below.
|
||||
|
||||
```
|
||||
config.json
|
||||
runtime.json
|
||||
rootfs/
|
||||
```
|
||||
While these three artifacts MUST all be present in a single directory on the local filesytem, that directory itself is not part of the bundle.
|
||||
In other words, a tar archive of a *bundle* will have these artifacts at the root of the archive, not nested within a top-level directory.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,6 @@
|
|||
|
||||
Behave as a community member, follow the code of conduct.
|
||||
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
The OpenContainers community is made up of a mixture of professionals and volunteers from all over the world.
|
||||
|
|
@ -36,4 +35,3 @@ By adopting this Code of Conduct, project maintainers commit themselves to fairl
|
|||
Thanks to the [Fedora Code of Conduct](https://getfedora.org/code-of-conduct) and [Contributor Covenant](http://contributor-covenant.org) for inspiration and ideas.
|
||||
|
||||
Portions of this Code of Conduct are adapted from the Contributor Covenant, version 1.2.0, available at http://contributor-covenant.org/version/1/2/0/
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Linux-specific configuration
|
||||
# Linux-specific Container Configuration
|
||||
|
||||
The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and file system jails to fulfill the spec.
|
||||
Additional information is needed for Linux over the [default spec configuration](config.md) in order to configure these various kernel features.
|
||||
|
|
|
|||
|
|
@ -65,6 +65,6 @@ type State struct {
|
|||
ID string `json:"id"`
|
||||
// Pid is the process id for the container's main process.
|
||||
Pid int `json:"pid"`
|
||||
// Root is the path to the container's bundle directory.
|
||||
Root string `json:"root"`
|
||||
// BundlePath is the path to the container's bundle directory.
|
||||
BundlePath string `json:"bundlePath"`
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Configuration file
|
||||
# Container Configuration file
|
||||
|
||||
The container's top-level directory MUST contain a configuration file called `config.json`.
|
||||
For now the canonical schema is defined in [config.go](config.go) and [config_linux.go](config_linux.go), but this will be moved to a formal JSON schema over time.
|
||||
|
|
@ -10,7 +10,7 @@ Below is a detailed description of each field defined in the configuration forma
|
|||
|
||||
## Manifest version
|
||||
|
||||
* **version** (string, required) must be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OCF specification with which the container bundle complies. The Open Container spec follows semantic versioning and retains forward and backward compatibility within major versions. For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series.
|
||||
* **`version`** (string, required) must be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OCF specification with which the container bundle complies. The Open Container spec follows semantic versioning and retains forward and backward compatibility within major versions. For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series.
|
||||
|
||||
*Example*
|
||||
|
||||
|
|
@ -22,8 +22,8 @@ Below is a detailed description of each field defined in the configuration forma
|
|||
|
||||
Each container has exactly one *root filesystem*, specified in the *root* object:
|
||||
|
||||
* **path** (string, required) Specifies the path to the root filesystem for the container, relative to the path where the manifest is. A directory MUST exist at the relative path declared by the field.
|
||||
* **readonly** (bool, optional) If true then the root filesystem MUST be read-only inside the container. Defaults to false.
|
||||
* **`path`** (string, required) Specifies the path to the root filesystem for the container, relative to the path where the manifest is. A directory MUST exist at the relative path declared by the field.
|
||||
* **`readonly`** (bool, optional) If true then the root filesystem MUST be read-only inside the container. Defaults to false.
|
||||
|
||||
*Example*
|
||||
|
||||
|
|
@ -38,9 +38,10 @@ Each container has exactly one *root filesystem*, specified in the *root* object
|
|||
|
||||
You can add array of mount points inside container as `mounts`.
|
||||
Each record in this array must have configuration in [runtime config](runtime-config.md#mount-configuration).
|
||||
The runtime MUST mount entries in the listed order.
|
||||
|
||||
* **name** (string, required) Name of mount point. Used for config lookup.
|
||||
* **path** (string, required) Destination of mount point: path inside container.
|
||||
* **`name`** (string, required) Name of mount point. Used for config lookup.
|
||||
* **`path`** (string, required) Destination of mount point: path inside container.
|
||||
|
||||
*Example*
|
||||
|
||||
|
|
@ -67,17 +68,17 @@ Each record in this array must have configuration in [runtime config](runtime-co
|
|||
|
||||
## Process configuration
|
||||
|
||||
* **terminal** (bool, optional) specifies whether you want a terminal attached to that process. Defaults to false.
|
||||
* **cwd** (string, optional) is the working directory that will be set for the executable.
|
||||
* **env** (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution. Elements in the array are specified as Strings in the form "KEY=value". The left hand side must consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
|
||||
* **args** (string, required) executable to launch and any flags as an array. The executable is the first element and must be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable.
|
||||
* **`terminal`** (bool, optional) specifies whether you want a terminal attached to that process. Defaults to false.
|
||||
* **`cwd`** (string, optional) is the working directory that will be set for the executable.
|
||||
* **`env`** (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution. Elements in the array are specified as Strings in the form "KEY=value". The left hand side must consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
|
||||
* **`args`** (string, required) executable to launch and any flags as an array. The executable is the first element and must be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable.
|
||||
|
||||
The user for the process is a platform-specific structure that allows specific control over which user the process runs as.
|
||||
For Linux-based systems the user structure has the following fields:
|
||||
|
||||
* **uid** (int, required) specifies the user id.
|
||||
* **gid** (int, required) specifies the group id.
|
||||
* **additionalGids** (array of ints, optional) specifies additional group ids to be added to the process.
|
||||
* **`uid`** (int, required) specifies the user id.
|
||||
* **`gid`** (int, required) specifies the group id.
|
||||
* **`additionalGids`** (array of ints, optional) specifies additional group ids to be added to the process.
|
||||
|
||||
*Example (Linux)*
|
||||
|
||||
|
|
@ -103,7 +104,7 @@ For Linux-based systems the user structure has the following fields:
|
|||
|
||||
## Hostname
|
||||
|
||||
* **hostname** (string, optional) as it is accessible to processes running inside.
|
||||
* **`hostname`** (string, optional) as it is accessible to processes running inside.
|
||||
|
||||
*Example*
|
||||
|
||||
|
|
@ -113,8 +114,8 @@ For Linux-based systems the user structure has the following fields:
|
|||
|
||||
## Platform-specific configuration
|
||||
|
||||
* **os** (string, required) specifies the operating system family this image must run on. Values for os must be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment).
|
||||
* **arch** (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch must be in the list specified by the Go Language document for [`$GOARCH`](https://golang.org/doc/install/source#environment).
|
||||
* **`os`** (string, required) specifies the operating system family this image must run on. Values for os must be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment).
|
||||
* **`arch`** (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch must be in the list specified by the Go Language document for [`$GOARCH`](https://golang.org/doc/install/source#environment).
|
||||
|
||||
```json
|
||||
"platform": {
|
||||
|
|
|
|||
|
|
@ -17,9 +17,9 @@ type Linux struct {
|
|||
// main process.
|
||||
type User struct {
|
||||
// UID is the user id.
|
||||
UID int32 `json:"uid"`
|
||||
UID uint32 `json:"uid"`
|
||||
// GID is the group id.
|
||||
GID int32 `json:"gid"`
|
||||
GID uint32 `json:"gid"`
|
||||
// AdditionalGids are additional group ids set for the container's process.
|
||||
AdditionalGids []int32 `json:"additionalGids"`
|
||||
AdditionalGids []uint32 `json:"additionalGids"`
|
||||
}
|
||||
|
|
|
|||
46
Godeps/_workspace/src/github.com/opencontainers/specs/principles.md
generated
vendored
Normal file
46
Godeps/_workspace/src/github.com/opencontainers/specs/principles.md
generated
vendored
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# The 5 principles of Standard Containers
|
||||
|
||||
Define a unit of software delivery called a Standard Container.
|
||||
The goal of a Standard Container is to encapsulate a software component and all its dependencies in a format that is self-describing and portable, so that any compliant runtime can run it without extra dependencies, regardless of the underlying machine and the contents of the container.
|
||||
|
||||
The specification for Standard Containers defines:
|
||||
|
||||
1. configuration file formats
|
||||
2. a set of standard operations
|
||||
3. an execution environment.
|
||||
|
||||
A great analogy for this is the physical shipping container used by the transportation industry.
|
||||
Shipping containers are a fundamental unit of delivery, they can be lifted, stacked, locked, loaded, unloaded and labelled.
|
||||
Irrespective of their contents, by standardizing the container itself it allowed for a consistent, more streamlined and efficient set of processes to be defined.
|
||||
For software Standard Containers offer similar functionality by being the fundamental, standardized, unit of delivery for a software package.
|
||||
|
||||
## 1. Standard operations
|
||||
|
||||
Standard Containers define a set of STANDARD OPERATIONS.
|
||||
They can be created, started, and stopped using standard container tools; copied and snapshotted using standard filesystem tools; and downloaded and uploaded using standard network tools.
|
||||
|
||||
## 2. Content-agnostic
|
||||
|
||||
Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents.
|
||||
They are started in the same way whether they contain a postgres database, a php application with its dependencies and application server, or Java build artifacts.
|
||||
|
||||
## 3. Infrastructure-agnostic
|
||||
|
||||
Standard Containers are INFRASTRUCTURE-AGNOSTIC: they can be run in any OCI supported infrastructure.
|
||||
For example, a standard container can be bundled on a laptop, uploaded to cloud storage, downloaded, run and snapshotted by a build server at a fiber hotel in Virginia, uploaded to 10 staging servers in a home-made private cloud cluster, then sent to 30 production instances across 3 public cloud regions.
|
||||
|
||||
## 4. Designed for automation
|
||||
|
||||
Standard Containers are DESIGNED FOR AUTOMATION: because they offer the same standard operations regardless of content and infrastructure, Standard Containers, are extremely well-suited for automation.
|
||||
In fact, you could say automation is their secret weapon.
|
||||
|
||||
Many things that once required time-consuming and error-prone human effort can now be programmed.
|
||||
Before Standard Containers, by the time a software component ran in production, it had been individually built, configured, bundled, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers.
|
||||
Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken.
|
||||
The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider.
|
||||
|
||||
## 5. Industrial-grade delivery
|
||||
|
||||
Standard Containers make INDUSTRIAL-GRADE DELIVERY of software a reality.
|
||||
Leveraging all of the properties listed above, Standard Containers are enabling large and small enterprises to streamline and automate their software delivery pipelines.
|
||||
Whether it is in-house devOps flows, or external customer-based software delivery mechanisms, Standard Containers are changing the way the community thinks about software packaging and delivery.
|
||||
|
|
@ -1,3 +1,5 @@
|
|||
# Linux-specific Runtime Configuration
|
||||
|
||||
## Namespaces
|
||||
|
||||
A namespace wraps a global system resource in an abstraction that makes it appear to the processes within the namespace that they have their own isolated instance of the global resource.
|
||||
|
|
@ -36,13 +38,13 @@ Also, when a path is specified, a runtime MUST assume that the setup for that pa
|
|||
|
||||
#### Namespace types
|
||||
|
||||
* **pid** processes inside the container will only be able to see other processes inside the same container.
|
||||
* **network** the container will have its own network stack.
|
||||
* **mount** the container will have an isolated mount table.
|
||||
* **ipc** processes inside the container will only be able to communicate to other processes inside the same
|
||||
* **`pid`** processes inside the container will only be able to see other processes inside the same container.
|
||||
* **`network`** the container will have its own network stack.
|
||||
* **`mount`** the container will have an isolated mount table.
|
||||
* **`ipc`** processes inside the container will only be able to communicate to other processes inside the same
|
||||
container via system level IPC.
|
||||
* **uts** the container will be able to have its own hostname and domain name.
|
||||
* **user** the container will be able to remap user and group IDs from the host to local users and groups
|
||||
* **`uts`** the container will be able to have its own hostname and domain name.
|
||||
* **`user`** the container will be able to remap user and group IDs from the host to local users and groups
|
||||
within the container.
|
||||
|
||||
## Devices
|
||||
|
|
@ -50,16 +52,16 @@ within the container.
|
|||
Devices is an array specifying the list of devices to be created in the container.
|
||||
Next parameters can be specified:
|
||||
|
||||
* **type** - type of device: `c`, `b`, `u` or `p`. More info in `man mknod`
|
||||
* **path** - full path to device inside container
|
||||
* **major, minor** - major, minor numbers for device. More info in `man mknod`.
|
||||
* **`type`** - type of device: `c`, `b`, `u` or `p`. More info in `man mknod`
|
||||
* **`path`** - full path to device inside container
|
||||
* **`major, minor`** - major, minor numbers for device. More info in `man mknod`.
|
||||
There is special value: `-1`, which means `*` for `device`
|
||||
cgroup setup.
|
||||
* **permissions** - cgroup permissions for device. A composition of `r`
|
||||
* **`permissions`** - cgroup permissions for device. A composition of `r`
|
||||
(read), `w` (write), and `m` (mknod).
|
||||
* **fileMode** - file mode for device file
|
||||
* **uid** - uid of device owner
|
||||
* **gid** - gid of device owner
|
||||
* **`fileMode`** - file mode for device file
|
||||
* **`uid`** - uid of device owner
|
||||
* **`gid`** - gid of device owner
|
||||
|
||||
```json
|
||||
"devices": [
|
||||
|
|
@ -319,11 +321,44 @@ For more information about Apparmor, see [Apparmor documentation](https://wiki.u
|
|||
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.
|
||||
For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt)
|
||||
The actions and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values.
|
||||
The actions, architectures, and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values.
|
||||
A valid list of constants as of Libseccomp v2.2.3 is contained below.
|
||||
|
||||
Architecture Constants
|
||||
* `SCMP_ARCH_X86`
|
||||
* `SCMP_ARCH_X86_64`
|
||||
* `SCMP_ARCH_X32`
|
||||
* `SCMP_ARCH_ARM`
|
||||
* `SCMP_ARCH_AARCH64`
|
||||
* `SCMP_ARCH_MIPS`
|
||||
* `SCMP_ARCH_MIPS64`
|
||||
* `SCMP_ARCH_MIPS64N32`
|
||||
* `SCMP_ARCH_MIPSEL`
|
||||
* `SCMP_ARCH_MIPSEL64`
|
||||
* `SCMP_ARCH_MIPSEL64N32`
|
||||
|
||||
Action Constants:
|
||||
* `SCMP_ACT_KILL`
|
||||
* `SCMP_ACT_TRAP`
|
||||
* `SCMP_ACT_ERRNO`
|
||||
* `SCMP_ACT_TRACE`
|
||||
* `SCMP_ACT_ALLOW`
|
||||
|
||||
Operator Constants:
|
||||
* `SCMP_CMP_NE`
|
||||
* `SCMP_CMP_LT`
|
||||
* `SCMP_CMP_LE`
|
||||
* `SCMP_CMP_EQ`
|
||||
* `SCMP_CMP_GE`
|
||||
* `SCMP_CMP_GT`
|
||||
* `SCMP_CMP_MASKED_EQ`
|
||||
|
||||
```json
|
||||
"seccomp": {
|
||||
"defaultAction": "SCMP_ACT_ALLOW",
|
||||
"architectures": [
|
||||
"SCMP_ARCH_X86"
|
||||
],
|
||||
"syscalls": [
|
||||
{
|
||||
"name": "getcwd",
|
||||
|
|
|
|||
|
|
@ -1,3 +1,72 @@
|
|||
# Runtime Configuration
|
||||
|
||||
## Hooks
|
||||
|
||||
Lifecycle hooks allow custom events for different points in a container's runtime.
|
||||
Presently there are `Prestart`, `Poststart` and `Poststop`.
|
||||
|
||||
* [`Prestart`](#pre-start) is a list of hooks to be run before the container process is executed
|
||||
* [`Poststart`](#post-start) is a list of hooks to be run immediately after the container process is started
|
||||
* [`Poststop`](#post-stop) is a list of hooks to be run after the container process exits
|
||||
|
||||
Hooks allow one to run code before/after various lifecycle events of the container.
|
||||
Hooks MUST be called in the listed order.
|
||||
The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
|
||||
|
||||
Hook paths are absolute and are executed from the host's filesystem.
|
||||
|
||||
### Pre-start
|
||||
|
||||
The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed.
|
||||
They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container.
|
||||
In Linux, for e.g., the network namespace could be configured in this hook.
|
||||
|
||||
If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.
|
||||
|
||||
### Post-start
|
||||
|
||||
The post-start hooks are called after the user process is started.
|
||||
For example this hook can notify user that real process is spawned.
|
||||
|
||||
If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
|
||||
|
||||
### Post-stop
|
||||
|
||||
The post-stop hooks are called after the container process is stopped.
|
||||
Cleanup or debugging could be performed in such a hook.
|
||||
If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
|
||||
|
||||
*Example*
|
||||
|
||||
```json
|
||||
"hooks" : {
|
||||
"prestart": [
|
||||
{
|
||||
"path": "/usr/bin/fix-mounts",
|
||||
"args": ["arg1", "arg2"],
|
||||
"env": [ "key1=value1"]
|
||||
},
|
||||
{
|
||||
"path": "/usr/bin/setup-network"
|
||||
}
|
||||
],
|
||||
"poststart": [
|
||||
{
|
||||
"path": "/usr/bin/notify-start"
|
||||
}
|
||||
],
|
||||
"poststop": [
|
||||
{
|
||||
"path": "/usr/sbin/cleanup.sh",
|
||||
"args": ["-f"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`path` is required for a hook.
|
||||
`args` and `env` are optional.
|
||||
|
||||
## Mount Configuration
|
||||
|
||||
Additional filesystems can be declared as "mounts", specified in the *mounts* object.
|
||||
|
|
@ -6,9 +75,9 @@ Values are objects with configuration of mount points.
|
|||
The parameters are similar to the ones in [the Linux mount system call](http://man7.org/linux/man-pages/man2/mount.2.html).
|
||||
Only [mounts from the portable config](config.md#mount-points) will be mounted.
|
||||
|
||||
* **type** (string, required) Linux, *filesystemtype* argument supported by the kernel are listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). Windows: ntfs
|
||||
* **source** (string, required) a device name, but can also be a directory name or a dummy. Windows, the volume name that is the target of the mount point. \\?\Volume\{GUID}\ (on Windows source is called target)
|
||||
* **options** (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).
|
||||
* **`type`** (string, required) Linux, *filesystemtype* argument supported by the kernel are listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). Windows: ntfs
|
||||
* **`source`** (string, required) a device name, but can also be a directory name or a dummy. Windows, the volume name that is the target of the mount point. \\?\Volume\{GUID}\ (on Windows source is called target)
|
||||
* **`options`** (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).
|
||||
|
||||
*Example (Linux)*
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
# Linux Runtime
|
||||
|
||||
## File descriptors
|
||||
By default, only the `stdin`, `stdout` and `stderr` file descriptors are kept open for the application by the runtime.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,22 +2,26 @@
|
|||
|
||||
## State
|
||||
|
||||
The runtime state for a container is persisted on disk so that external tools can consume and act on this information.
|
||||
The runtime state is stored in a JSON encoded file.
|
||||
It is recommended that this file is stored in a temporary filesystem so that it can be removed on a system reboot.
|
||||
On Linux based systems the state information should be stored in `/run/opencontainer/containers`.
|
||||
The directory structure for a container is `/run/opencontainer/containers/<containerID>/state.json`.
|
||||
By providing a default location that container state is stored external applications can find all containers running on a system.
|
||||
Runtime MUST store container metadata on disk so that external tools can consume and act on this information.
|
||||
It is recommended that this data be stored in a temporary filesystem so that it can be removed on a system reboot.
|
||||
On Linux/Unix based systems the metadata MUST be stored under `/run/opencontainer/containers`.
|
||||
For non-Linux/Unix based systems the location of the root metadata directory is currently undefined.
|
||||
Within that directory there MUST be one directory for each container created, where the name of the directory MUST be the ID of the container.
|
||||
For example: for a Linux container with an ID of `173975398351`, there will be a corresponding directory: `/run/opencontainer/containers/173975398351`.
|
||||
Within each container's directory, there MUST be a JSON encoded file called `state.json` that contains the runtime state of the container.
|
||||
For example: `/run/opencontainer/containers/173975398351/state.json`.
|
||||
|
||||
* **version** (string) Version of the OCI specification used when creating the container.
|
||||
* **id** (string) ID is the container's ID.
|
||||
* **pid** (int) Pid is the ID of the main process within the container.
|
||||
* **root** (string) Root is the path to the container's bundle directory.
|
||||
The `state.json` file MUST contain all of the following properties:
|
||||
|
||||
* **`version`**: (string) is the OCF specification version used when creating the container.
|
||||
* **`id`**: (string) 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.
|
||||
The ID is provided in the state because hooks will be executed with the state as the payload.
|
||||
This allows the hook to perform clean and teardown logic after the runtime destroys its own state.
|
||||
|
||||
The root directory to the bundle is provided in the state so that consumers can find the container's configuration and rootfs where it is located on the host's filesystem.
|
||||
This allows the hooks to perform cleanup and teardown logic after the runtime destroys its own state.
|
||||
* **`pid`**: (int) is the ID of the main process within the container, as seen by the host.
|
||||
* **`bundlePath`**: (string) is the absolute path to the container's bundle directory.
|
||||
This is provided so that consumers can find the container's configuration and root filesystem on the host.
|
||||
|
||||
*Example*
|
||||
|
||||
|
|
@ -49,48 +53,4 @@ This event needs to be captured by runc to run onstop event handlers.
|
|||
|
||||
## Hooks
|
||||
|
||||
Hooks allow one to run code before/after various lifecycle events of the container.
|
||||
Hooks MUST be called in the listed order.
|
||||
The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
|
||||
|
||||
Hook paths are absolute and are executed from the host's filesystem.
|
||||
|
||||
### Pre-start
|
||||
|
||||
The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed.
|
||||
They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container.
|
||||
In Linux, for e.g., the network namespace could be configured in this hook.
|
||||
|
||||
If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.
|
||||
|
||||
### Post-stop
|
||||
|
||||
The post-stop hooks are called after the container process is stopped.
|
||||
Cleanup or debugging could be performed in such a hook.
|
||||
If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
|
||||
|
||||
*Example*
|
||||
|
||||
```json
|
||||
"hooks" : {
|
||||
"prestart": [
|
||||
{
|
||||
"path": "/usr/bin/fix-mounts",
|
||||
"args": ["arg1", "arg2"],
|
||||
"env": [ "key1=value1"]
|
||||
},
|
||||
{
|
||||
"path": "/usr/bin/setup-network"
|
||||
}
|
||||
],
|
||||
"poststop": [
|
||||
{
|
||||
"path": "/usr/sbin/cleanup.sh",
|
||||
"args": ["-f"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`path` is required for a hook.
|
||||
`args` and `env` are optional.
|
||||
See [runtime configuration for hooks](./runtime-config.md)
|
||||
|
|
|
|||
|
|
@ -22,6 +22,8 @@ type Hooks struct {
|
|||
// Prestart is a list of hooks to be run before the container process is executed.
|
||||
// On Linux, they are run after the container namespaces are created.
|
||||
Prestart []Hook `json:"prestart"`
|
||||
// Poststart is a list of hooks to be run after the container process is started.
|
||||
Poststart []Hook `json:"poststart"`
|
||||
// Poststop is a list of hooks to be run after the container process exits.
|
||||
Poststop []Hook `json:"poststop"`
|
||||
}
|
||||
|
|
|
|||
|
|
@ -73,11 +73,11 @@ const (
|
|||
// IDMapping specifies UID/GID mappings
|
||||
type IDMapping struct {
|
||||
// HostID is the UID/GID of the host user or group
|
||||
HostID int32 `json:"hostID"`
|
||||
HostID uint32 `json:"hostID"`
|
||||
// ContainerID is the UID/GID of the container's user or group
|
||||
ContainerID int32 `json:"containerID"`
|
||||
ContainerID uint32 `json:"containerID"`
|
||||
// Size is the length of the range of IDs mapped between the two namespaces
|
||||
Size int32 `json:"size"`
|
||||
Size uint32 `json:"size"`
|
||||
}
|
||||
|
||||
// Rlimit type and restrictions
|
||||
|
|
@ -235,15 +235,52 @@ type Device struct {
|
|||
// Seccomp represents syscall restrictions
|
||||
type Seccomp struct {
|
||||
DefaultAction Action `json:"defaultAction"`
|
||||
Architectures []Arch `json:"architectures"`
|
||||
Syscalls []*Syscall `json:"syscalls"`
|
||||
}
|
||||
|
||||
// Additional architectures permitted to be used for system calls
|
||||
// By default only the native architecture of the kernel is permitted
|
||||
type Arch string
|
||||
|
||||
const (
|
||||
ArchX86 Arch = "SCMP_ARCH_X86"
|
||||
ArchX86_64 Arch = "SCMP_ARCH_X86_64"
|
||||
ArchX32 Arch = "SCMP_ARCH_X32"
|
||||
ArchARM Arch = "SCMP_ARCH_ARM"
|
||||
ArchAARCH64 Arch = "SCMP_ARCH_AARCH64"
|
||||
ArchMIPS Arch = "SCMP_ARCH_MIPS"
|
||||
ArchMIPS64 Arch = "SCMP_ARCH_MIPS64"
|
||||
ArchMIPS64N32 Arch = "SCMP_ARCH_MIPS64N32"
|
||||
ArchMIPSEL Arch = "SCMP_ARCH_MIPSEL"
|
||||
ArchMIPSEL64 Arch = "SCMP_ARCH_MIPSEL64"
|
||||
ArchMIPSEL64N32 Arch = "SCMP_ARCH_MIPSEL64N32"
|
||||
)
|
||||
|
||||
// Action taken upon Seccomp rule match
|
||||
type Action string
|
||||
|
||||
const (
|
||||
ActKill Action = "SCMP_ACT_KILL"
|
||||
ActTrap Action = "SCMP_ACT_TRAP"
|
||||
ActErrno Action = "SCMP_ACT_ERRNO"
|
||||
ActTrace Action = "SCMP_ACT_TRACE"
|
||||
ActAllow Action = "SCMP_ACT_ALLOW"
|
||||
)
|
||||
|
||||
// Operator used to match syscall arguments in Seccomp
|
||||
type Operator string
|
||||
|
||||
const (
|
||||
OpNotEqual Operator = "SCMP_CMP_NE"
|
||||
OpLessThan Operator = "SCMP_CMP_LT"
|
||||
OpLessEqual Operator = "SCMP_CMP_LE"
|
||||
OpEqualTo Operator = "SCMP_CMP_EQ"
|
||||
OpGreaterEqual Operator = "SCMP_CMP_GE"
|
||||
OpGreaterThan Operator = "SCMP_CMP_GT"
|
||||
OpMaskedEqual Operator = "SCMP_CMP_MASKED_EQ"
|
||||
)
|
||||
|
||||
// Arg used for matching specific syscall arguments in Seccomp
|
||||
type Arg struct {
|
||||
Index uint `json:"index"`
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ const (
|
|||
// VersionMajor is for an API incompatible changes
|
||||
VersionMajor = 0
|
||||
// VersionMinor is for functionality in a backwards-compatible manner
|
||||
VersionMinor = 1
|
||||
VersionMinor = 2
|
||||
// VersionPatch is for backwards-compatible bug fixes
|
||||
VersionPatch = 0
|
||||
)
|
||||
|
|
|
|||
Loading…
Reference in New Issue