From cccd9fc3206c44b7db7b49230b8aeaef9296424c Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 3 May 2016 20:26:58 -0700 Subject: [PATCH 1/2] schema: Replace "bundle" with "runtime configuration" The bundle contains 'config.json' and other things, but this schema is just for 'config.json'. This is mostly: $ sed -i 's|/bundle|/runtime/config|' schema/*.json for the 'id' fields, but I also tweaked 'root.description' and the schema.json 'description'. Signed-off-by: W. Trevor King --- schema/schema-linux.json | 90 +++++++++++++++++++------------------- schema/schema-solaris.json | 14 +++--- schema/schema.json | 64 +++++++++++++-------------- 3 files changed, 84 insertions(+), 84 deletions(-) diff --git a/schema/schema-linux.json b/schema/schema-linux.json index ed89b8bed..cfb3ea9e8 100644 --- a/schema/schema-linux.json +++ b/schema/schema-linux.json @@ -1,11 +1,11 @@ { "linux": { "description": "Linux platform-specific configurations", - "id": "https://opencontainers.org/schema/bundle/linux", + "id": "https://opencontainers.org/schema/runtime/config/linux", "type": "object", "properties": { "devices": { - "id": "https://opencontainers.org/schema/bundle/linux/devices", + "id": "https://opencontainers.org/schema/runtime/config/linux/devices", "oneOf": [ { "type": "array", @@ -19,7 +19,7 @@ ] }, "uidMappings": { - "id": "https://opencontainers.org/schema/bundle/linux/uidMappings", + "id": "https://opencontainers.org/schema/runtime/config/linux/uidMappings", "oneOf": [ { "type": "array", @@ -33,7 +33,7 @@ ] }, "gidMappings": { - "id": "https://opencontainers.org/schema/bundle/linux/gidMappings", + "id": "https://opencontainers.org/schema/runtime/config/linux/gidMappings", "oneOf": [ { "type": "array", @@ -47,7 +47,7 @@ ] }, "namespaces": { - "id": "https://opencontainers.org/schema/bundle/linux/namespaces", + "id": "https://opencontainers.org/schema/runtime/config/linux/namespaces", "type": "array", "items": { "anyOf": [ @@ -58,38 +58,38 @@ } }, "resources": { - "id": "https://opencontainers.org/schema/bundle/linux/resources", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources", "type": "object", "properties": { "oomScoreAdj": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/oomScoreAdj", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/oomScoreAdj", "type": "integer", "minimum": -1000, "maximum": 1000 }, "pids": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/pids", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/pids", "properties": { "limit": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/pids/limit", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/pids/limit", "$ref": "defs.json#/definitions/int64" } } }, "blockIO": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/blockIO", "type": "object", "properties": { "blkioWeight": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioWeight", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/blockIO/blkioWeight", "$ref": "defs-linux.json#/definitions/blkioWeightPointer" }, "blkioLeafWeight": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioLeafWeight", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/blockIO/blkioLeafWeight", "$ref": "defs-linux.json#/definitions/blkioWeightPointer" }, "blkioThrottleReadBpsDevice": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleReadBpsDevice", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/blockIO/blkioThrottleReadBpsDevice", "oneOf": [ { "type": "array", @@ -105,7 +105,7 @@ ] }, "blkioThrottleWriteBpsDevice": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleWriteBpsDevice", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/blockIO/blkioThrottleWriteBpsDevice", "oneOf": [ { "type": "array", @@ -119,7 +119,7 @@ ] }, "blkioThrottleReadIopsDevice": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleReadIopsDevice", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/blockIO/blkioThrottleReadIopsDevice", "oneOf": [ { "type": "array", @@ -133,7 +133,7 @@ ] }, "blkioThrottleWriteIopsDevice": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleWriteIopsDevice", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/blockIO/blkioThrottleWriteIopsDevice", "oneOf": [ { "type": "array", @@ -147,7 +147,7 @@ ] }, "blkioWeightDevice": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioWeightDevice", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/blockIO/blkioWeightDevice", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/blockIODeviceWeightPointer" @@ -156,45 +156,45 @@ } }, "cpu": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/cpu", "properties": { "cpus": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/cpus", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/cpu/cpus", "$ref": "defs.json#/definitions/stringPointer" }, "mems": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/mems", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/cpu/mems", "$ref": "defs.json#/definitions/stringPointer" }, "period": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/period", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/cpu/period", "$ref": "defs.json#/definitions/uint64Pointer" }, "quota": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/quota", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/cpu/quota", "$ref": "defs.json#/definitions/uint64Pointer" }, "realtimePeriod": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/realtimePeriod", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/cpu/realtimePeriod", "$ref": "defs.json#/definitions/uint64Pointer" }, "realtimeRuntime": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/realtimeRuntime", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/cpu/realtimeRuntime", "$ref": "defs.json#/definitions/uint64Pointer" }, "shares": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/shares", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/cpu/shares", "$ref": "defs.json#/definitions/uint64Pointer" } }, "type": "object" }, "disableOOMKiller": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/disableOOMKiller", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/disableOOMKiller", "type": "boolean" }, "hugepageLimits": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/hugepageLimits", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/hugepageLimits", "oneOf": [ { "type": "array", @@ -216,41 +216,41 @@ ] }, "memory": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/memory", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/memory", "type": "object", "properties": { "kernel": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/kernel", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/memory/kernel", "$ref": "defs.json#/definitions/uint64Pointer" }, "limit": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/limit", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/memory/limit", "$ref": "defs.json#/definitions/uint64Pointer" }, "reservation": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/reservation", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/memory/reservation", "$ref": "defs.json#/definitions/uint64Pointer" }, "swap": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/swap", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/memory/swap", "$ref": "defs.json#/definitions/uint64Pointer" }, "swappiness": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/swappiness", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/memory/swappiness", "$ref": "defs.json#/definitions/uint64Pointer" } } }, "network": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/network", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/network", "type": "object", "properties": { "classID": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/network/classId", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/network/classId", "$ref": "defs.json#/definitions/uint32" }, "priorities": { - "id": "https://opencontainers.org/schema/bundle/linux/resources/network/priorities", + "id": "https://opencontainers.org/schema/runtime/config/linux/resources/network/priorities", "oneOf": [ { "type": "array", @@ -278,18 +278,18 @@ ] }, "rootfsPropagation": { - "id": "https://opencontainers.org/schema/bundle/linux/rootfsPropagation", + "id": "https://opencontainers.org/schema/runtime/config/linux/rootfsPropagation", "type": "string" }, "seccomp": { - "id": "https://opencontainers.org/schema/bundle/linux/seccomp", + "id": "https://opencontainers.org/schema/runtime/config/linux/seccomp", "properties": { "defaultAction": { - "id": "https://opencontainers.org/schema/bundle/linux/seccomp/defaultAction", + "id": "https://opencontainers.org/schema/runtime/config/linux/seccomp/defaultAction", "type": "string" }, "architectures": { - "id": "https://opencontainers.org/schema/bundle/linux/seccomp/architectures", + "id": "https://opencontainers.org/schema/runtime/config/linux/seccomp/architectures", "oneOf": [ { "type": "array", @@ -303,7 +303,7 @@ ] }, "syscalls": { - "id": "https://opencontainers.org/schema/bundle/linux/seccomp/syscalls", + "id": "https://opencontainers.org/schema/runtime/config/linux/seccomp/syscalls", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/Syscall" @@ -313,7 +313,7 @@ "type": "object" }, "sysctl": { - "id": "https://opencontainers.org/schema/bundle/linux/sysctl", + "id": "https://opencontainers.org/schema/runtime/config/linux/sysctl", "oneOf": [ { "$ref": "defs.json#/definitions/mapStringString" @@ -324,15 +324,15 @@ ] }, "maskedPaths": { - "id": "https://opencontainers.org/schema/bundle/linux/maskedPaths", + "id": "https://opencontainers.org/schema/runtime/config/linux/maskedPaths", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "readonlyPaths": { - "id": "https://opencontainers.org/schema/bundle/linux/readonlyPaths", + "id": "https://opencontainers.org/schema/runtime/config/linux/readonlyPaths", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "mountLabel": { - "id": "https://opencontainers.org/schema/bundle/linux/mountLabel", + "id": "https://opencontainers.org/schema/runtime/config/linux/mountLabel", "type": "string" } } diff --git a/schema/schema-solaris.json b/schema/schema-solaris.json index fbc5977e0..cb5fb80e5 100644 --- a/schema/schema-solaris.json +++ b/schema/schema-solaris.json @@ -1,31 +1,31 @@ { "solaris": { "description": "Solaris platform-specific configurations", - "id": "https://opencontainers.org/schema/bundle/solaris", + "id": "https://opencontainers.org/schema/runtime/config/solaris", "type": "object", "properties": { "milestone": { - "id": "https://opencontainers.org/schema/bundle/solaris/milestone", + "id": "https://opencontainers.org/schema/runtime/config/solaris/milestone", "type": "string" }, "limitpriv": { - "id": "https://opencontainers.org/schema/bundle/solaris/limitpriv", + "id": "https://opencontainers.org/schema/runtime/config/solaris/limitpriv", "type": "string" }, "maxShmMemory": { - "id": "https://opencontainers.org/schema/bundle/solaris/maxShmMemory", + "id": "https://opencontainers.org/schema/runtime/config/solaris/maxShmMemory", "type": "string" }, "cappedCPU": { - "id": "https://opencontainers.org/schema/bundle/solaris/cappedCPU", + "id": "https://opencontainers.org/schema/runtime/config/solaris/cappedCPU", "$ref": "defs.json#/definitions/mapStringString" }, "cappedMemory": { - "id": "https://opencontainers.org/schema/bundle/solaris/cappedMemory", + "id": "https://opencontainers.org/schema/runtime/config/solaris/cappedMemory", "$ref": "defs.json#/definitions/mapStringString" }, "anet": { - "id": "https://opencontainers.org/schema/bundle/solaris/anet", + "id": "https://opencontainers.org/schema/runtime/config/solaris/anet", "type": "array", "items": { "$ref": "defs.json#/definitions/mapStringString" diff --git a/schema/schema.json b/schema/schema.json index 5211c141f..e7bef9f7b 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -1,16 +1,16 @@ { - "description": "Schema for OpenContainer bundle configuration file", + "description": "Schema for OpenContainer runtime configuration file", "$schema": "http://json-schema.org/draft-04/schema#", - "id": "https://opencontainers.org/schema/bundle", + "id": "https://opencontainers.org/schema/runtime/config", "type": "object", "properties": { "ociVersion": { "description": "The version of OpenContainer specification configuration complies with", - "id": "https://opencontainers.org/schema/bundle/ociVersion", + "id": "https://opencontainers.org/schema/runtime/config/ociVersion", "type": "string" }, "hooks": { - "id": "https://opencontainers.org/schema/bundle/hooks", + "id": "https://opencontainers.org/schema/runtime/config/hooks", "type": "object", "properties": { "prestart": { @@ -25,7 +25,7 @@ } }, "annotations": { - "id": "https://opencontainers.org/schema/bundle/annotations", + "id": "https://opencontainers.org/schema/runtime/config/annotations", "oneOf": [ { "$ref": "defs.json#/definitions/mapStringString" @@ -36,18 +36,18 @@ ] }, "hostname": { - "id": "https://opencontainers.org/schema/bundle/hostname", + "id": "https://opencontainers.org/schema/runtime/config/hostname", "type": "string" }, "mounts": { - "id": "https://opencontainers.org/schema/bundle/mounts", + "id": "https://opencontainers.org/schema/runtime/config/mounts", "type": "array", "items": { "$ref": "defs.json#/definitions/Mount" } }, "platform": { - "id": "https://opencontainers.org/schema/bundle/platform", + "id": "https://opencontainers.org/schema/runtime/config/platform", "type": "object", "required": [ "arch", @@ -55,32 +55,32 @@ ], "properties": { "arch": { - "id": "https://opencontainers.org/schema/bundle/platform/arch", + "id": "https://opencontainers.org/schema/runtime/config/platform/arch", "type": "string" }, "os": { - "id": "https://opencontainers.org/schema/bundle/platform/os", + "id": "https://opencontainers.org/schema/runtime/config/platform/os", "type": "string" } } }, "root": { - "description": "the root filesystem the container's bundle", - "id": "https://opencontainers.org/schema/bundle/root", + "description": "the container's root filesystem", + "id": "https://opencontainers.org/schema/runtime/config/root", "type": "object", "properties": { "path": { - "id": "https://opencontainers.org/schema/bundle/root/path", + "id": "https://opencontainers.org/schema/runtime/config/root/path", "$ref": "defs.json#/definitions/FilePath" }, "readonly": { - "id": "https://opencontainers.org/schema/bundle/root/readonly", + "id": "https://opencontainers.org/schema/runtime/config/root/readonly", "type": "boolean" } } }, "process": { - "id": "https://opencontainers.org/schema/bundle/process", + "id": "https://opencontainers.org/schema/runtime/config/process", "type": "object", "required": [ "cwd", @@ -88,75 +88,75 @@ ], "properties": { "args": { - "id": "https://opencontainers.org/schema/bundle/process/args", + "id": "https://opencontainers.org/schema/runtime/config/process/args", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "cwd": { - "id": "https://opencontainers.org/schema/bundle/process/cwd", + "id": "https://opencontainers.org/schema/runtime/config/process/cwd", "type": "string" }, "env": { - "id": "https://opencontainers.org/schema/bundle/process/env", + "id": "https://opencontainers.org/schema/runtime/config/process/env", "$ref": "defs.json#/definitions/Env" }, "terminal": { - "id": "https://opencontainers.org/schema/bundle/process/terminal", + "id": "https://opencontainers.org/schema/runtime/config/process/terminal", "type": "boolean" }, "user": { - "id": "https://opencontainers.org/schema/bundle/process/user", + "id": "https://opencontainers.org/schema/runtime/config/process/user", "type": "object", "properties": { "uid": { - "id": "https://opencontainers.org/schema/bundle/process/user/uid", + "id": "https://opencontainers.org/schema/runtime/config/process/user/uid", "$ref": "defs.json#/definitions/UID" }, "gid": { - "id": "https://opencontainers.org/schema/bundle/process/user/gid", + "id": "https://opencontainers.org/schema/runtime/config/process/user/gid", "$ref": "defs.json#/definitions/GID" }, "additionalGids": { - "id": "https://opencontainers.org/schema/bundle/process/user/additionalGids", + "id": "https://opencontainers.org/schema/runtime/config/process/user/additionalGids", "$ref": "defs.json#/definitions/ArrayOfGIDs" } } }, "capabilities": { - "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities", + "id": "https://opencontainers.org/schema/runtime/config/process/linux/capabilities", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/Capability" } }, "apparmorProfile": { - "id": "https://opencontainers.org/schema/bundle/process/linux/apparmorProfile", + "id": "https://opencontainers.org/schema/runtime/config/process/linux/apparmorProfile", "type": "string" }, "selinuxLabel": { - "id": "https://opencontainers.org/schema/bundle/process/linux/selinuxLabel", + "id": "https://opencontainers.org/schema/runtime/config/process/linux/selinuxLabel", "type": "string" }, "noNewPrivileges": { - "id": "https://opencontainers.org/schema/bundle/process/linux/noNewPrivileges", + "id": "https://opencontainers.org/schema/runtime/config/process/linux/noNewPrivileges", "type": "boolean" }, "rlimits": { - "id": "https://opencontainers.org/schema/bundle/linux/rlimits", + "id": "https://opencontainers.org/schema/runtime/config/linux/rlimits", "type": "array", "items": { - "id": "https://opencontainers.org/schema/bundle/linux/rlimits/0", + "id": "https://opencontainers.org/schema/runtime/config/linux/rlimits/0", "type": "object", "properties": { "hard": { - "id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/hard", + "id": "https://opencontainers.org/schema/runtime/config/linux/rlimits/0/hard", "$ref": "defs.json#/definitions/uint64" }, "soft": { - "id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/soft", + "id": "https://opencontainers.org/schema/runtime/config/linux/rlimits/0/soft", "$ref": "defs.json#/definitions/uint64" }, "type": { - "id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/type", + "id": "https://opencontainers.org/schema/runtime/config/linux/rlimits/0/type", "type": "string", "pattern": "^RLIMIT_[A-Z]+$" } From bc306b5fe2bc9c87afb92be3323b3862175684fa Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 3 May 2016 16:07:42 -0700 Subject: [PATCH 2/2] *: Remove "bundle" and go straight to config.json Some history behind bundle requirements: * 77d44b10 (Update runtime.md, 2015-06-16) lands the initial reference to a root filesystem, requiring a relative path. It also lands the "bundle" construct, which at this point includes content directories, signatures, and the configuration file. The content directories "at least" include the root filesystem. * 5d2eb180 (*: re-org the spec, 2015-06-24) shifts the bundle docs to bundle.md and demotes signatures to "other related content". * 91f5ad7c (bundle.md: various updates to latest spec, 2015-07-02, #55) finishes the signature demotion and strengthens the root-inclusion requirement with another "must include". * 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) split out runtime.json, required the root directory to exist at `rootfs`, and dropped most references to "content directories". * 106ec2da (Cleanup bundle.md, 2015-10-02, #210) kept the requirement for a rootfs directory in the bundle root, but relaxed the name requirement to allow other single-component names (e.g. `my-rootfs`). Dropped the last reference to "content directories". * cb2da543 (config: Single, unified config file, 2015-12-28, #284) rolled runtime.json back into config.json. * b2e9154a (Remove requirement for rootfs path to be relative, 2016-04-22, #394) allowed absolute paths for root.path and removed some "same directory" language while leaving other "same directory" language. I think the root filesystem should be optional [1], but even folks who disagree on that point have come to the conclusion that it doesn't need to be in the bundle [2]. #394 seems partially unfinished, but I think the intention was clear. Once you relax the "bundle must contain the root filesystem" requirement, the only thing that the bundle must contain is config.json. It doesn't seem to be worth the trouble to name a "bundle" construct if its only meaning is "the directory that holds config.json", so this commit removes all remaining references to the term "bundle". [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/6ZKMNWujDhU Subject: Dropping the rootfs requirement and restoring arbitrary bundle content Date: Wed, 26 Aug 2015 12:54:47 -0700 Message-ID: <20150826195447.GX21585@odin.tremily.us> [2]: https://github.com/opencontainers/runtime-spec/issues/389#issue-149584747 Signed-off-by: W. Trevor King --- Makefile | 1 - README.md | 11 +++++------ bundle.md | 24 ------------------------ config.md | 6 +++--- glossary.md | 8 ++------ implementations.md | 2 +- principles.md | 4 ++-- runtime.md | 13 ++++++------- specs-go/state.go | 4 ++-- 9 files changed, 21 insertions(+), 52 deletions(-) delete mode 100644 bundle.md diff --git a/Makefile b/Makefile index e9de822a9..1360cd762 100644 --- a/Makefile +++ b/Makefile @@ -11,7 +11,6 @@ DOC_FILES := \ ROADMAP.md \ implementations.md \ project.md \ - bundle.md \ runtime.md \ runtime-linux.md \ config.md \ diff --git a/README.md b/README.md index bd21985b6..3e6813451 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,6 @@ Table of Contents - [Roadmap](ROADMAP.md) - [Implementations](implementations.md) - [project](project.md) -- [Filesystem Bundle](bundle.md) - Runtime and Lifecycle - [General Runtime and Lifecycle](runtime.md) - [Linux-specific Runtime and Lifecycle](runtime-linux.md) @@ -31,11 +30,11 @@ An implementation that satisfies all the MUST or REQUIRED and all the SHOULD req To provide context for users the following section gives example use cases for each part of the spec. -#### Application Bundle Builders +#### Application Publishers -Application bundle builders can create a [bundle](bundle.md) directory that includes all of the files required for launching an application as a container. -The bundle contains an OCI [configuration file](config.md) where the builder can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](config.md#mounts) locations, [hook](config.md#hooks) paths, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups). -Because the configuration includes host-specific settings, application bundle directories copied between two hosts may require configuration adjustments. +Application publishers distribute OCI [configuration files](config.md) and related resources (for example, [referenced filesystems](config.md#root-configuration) for launching an application as a [container](glossary.md#container). +The publisher can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](config.md#mounts) locations, [hook](config.md#hooks) paths, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups). +Because the configuration includes host-specific settings, configurations copied between two hosts may require local adjustments. #### Hook Developers @@ -44,7 +43,7 @@ Example use cases include sophisticated network configuration, volume garbage co #### Runtime Developers -Runtime developers can build runtime implementations that run OCI-compliant bundles and container configuration, containing low-level OS and host specific details, on a particular platform. +Runtime developers can build runtime implementations that perform [operations](runtime.md#operations) on [containers](glossary.md#container) on a particular platform. # Releases diff --git a/bundle.md b/bundle.md deleted file mode 100644 index 159efc35b..000000000 --- a/bundle.md +++ /dev/null @@ -1,24 +0,0 @@ -# Filesystem Bundle - -## 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 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 contains all the information needed to load and run a container. -This MUST include 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`. -When the bundle is packaged up for distribution, this file MUST be included. -See [`config.json`](config.md) for more details. - -2. 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`. -When the bundle is packaged up for distribution, this directory MUST be included. -This directory MUST be referenced from within the `config.json` file. - -While these artifacts MUST all be present in a single directory on the local filesystem, 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. diff --git a/config.md b/config.md index bd42af426..cf3f17d92 100644 --- a/config.md +++ b/config.md @@ -10,7 +10,7 @@ Below is a detailed description of each field defined in the configuration forma ## Specification version -* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OpenContainer specification with which the bundle complies. +* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OpenContainer specification with which the configuration complies. The OpenContainer spec follows semantic versioning and retains forward and backward compatibility within major versions. For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series. NOTE that there is no guarantee for forward or backward compatibility for version 0.x. @@ -180,7 +180,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th ## Hostname -* **`hostname`** (string, optional) as it is accessible to processes running inside. On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace]. +* **`hostname`** (string, optional) as it is accessible to processes running inside. On Linux, you can only set this if your configuration creates a new [UTS namespace][uts-namespace]. ### Example @@ -192,7 +192,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th * **`os`** (string, required) specifies the operating system family this image targets. The runtime MUST generate an error if it does not support the configured **`os`**. - Bundles SHOULD use, and runtimes SHOULD understand, **`os`** entries listed in the Go Language document for [`$GOOS`][go-environment]. + Configuration authors SHOULD use, and runtimes SHOULD understand, **`os`** entries listed in the Go Language document for [`$GOOS`][go-environment]. If an operating system is not included in the `$GOOS` documentation, it SHOULD be submitted to this specification for standardization. * **`arch`** (string, required) specifies the instruction set for which the binaries in the image have been compiled. The runtime MUST generate an error if it does not support the configured **`arch`**. diff --git a/glossary.md b/glossary.md index 6b6eb5949..c72bc77a4 100644 --- a/glossary.md +++ b/glossary.md @@ -1,12 +1,8 @@ # Glossary -## Bundle - -A [directory structure](bundle.md) that is written ahead of time, distributed, and used to seed the runtime for creating a [container](#container) and launching a process within it. - ## Configuration -The [`config.json`](config.md) file in a [bundle](#bundle) which defines the intended [container](#container) and container process. +The [`config.json`](config.md) file which defines the intended [container](#container) and container process. ## Container @@ -24,7 +20,7 @@ All configuration [JSON][] MUST be encoded in [UTF-8][]. ## Runtime An implementation of this specification. -It reads the [configuration files](#configuration) from a [bundle](#bundle), uses that information to create a [container](#container), launches a process inside the container, and performs other [lifecycle actions](runtime.md). +It performs [operations](runtime.md#operations) on [containers](#container). ## Runtime namespace diff --git a/implementations.md b/implementations.md index 1a6d75429..a89ddb03f 100644 --- a/implementations.md +++ b/implementations.md @@ -14,5 +14,5 @@ If you know of any associated projects that are not listed here, please file a p ## Testing & Tools * [kunalkushwaha/octool](https://github.com/kunalkushwaha/octool) - A config linter and validator. -* [opencontainers/ocitools](https://github.com/opencontainers/ocitools) - A config generator and runtime/bundle testing framework. +* [opencontainers/ocitools](https://github.com/opencontainers/ocitools) - A config generator and runtime/configuration testing framework. * [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime diff --git a/principles.md b/principles.md index 5dbab1699..ee6986d98 100644 --- a/principles.md +++ b/principles.md @@ -27,7 +27,7 @@ They are started in the same way whether they contain a postgres database, a php ## 3. Infrastructure-agnostic Standard Containers are INFRASTRUCTURE-AGNOSTIC: they can be run in any OCI supported infrastructure. -For example, a standard container can be bundled on a laptop, uploaded to cloud storage, downloaded, run and snapshotted by a build server at a fiber hotel in Virginia, uploaded to 10 staging servers in a home-made private cloud cluster, then sent to 30 production instances across 3 public cloud regions. +For example, a standard container can be packaged on a laptop, uploaded to cloud storage, downloaded, run and snapshotted by a build server at a fiber hotel in Virginia, uploaded to 10 staging servers in a home-made private cloud cluster, then sent to 30 production instances across 3 public cloud regions. ## 4. Designed for automation @@ -35,7 +35,7 @@ Standard Containers are DESIGNED FOR AUTOMATION: because they offer the same sta In fact, you could say automation is their secret weapon. Many things that once required time-consuming and error-prone human effort can now be programmed. -Before Standard Containers, by the time a software component ran in production, it had been individually built, configured, bundled, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers. +Before Standard Containers, by the time a software component ran in production, it had been individually built, configured, packaged, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers. Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken. The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider. diff --git a/runtime.md b/runtime.md index 59f3b2c73..d0fee84b6 100644 --- a/runtime.md +++ b/runtime.md @@ -16,7 +16,7 @@ There is no requirement that it be unique across hosts. The ID is provided in the state because hooks will be executed with the state as the payload. This allows the hooks to perform cleanup and teardown logic after the runtime destroys its own state. * **`pid`**: (int) is the ID of the main process within the container, as seen by the host. -* **`bundlePath`**: (string) is the absolute path to the container's bundle directory. +* **`configPath`**: (string) is the absolute path to the container's [configuration](config.md). This is provided so that consumers can find the container's configuration and root filesystem on the host. When serialized in JSON, the format MUST adhere to the following pattern: @@ -26,7 +26,7 @@ When serialized in JSON, the format MUST adhere to the following pattern: "ociVersion": "0.2.0", "id": "oci-container1", "pid": 4422, - "bundlePath": "/containers/redis" + "configPath": "/containers/redis/config.json" } ``` @@ -35,7 +35,7 @@ See [Query State](#query-state) for information on retrieving the state of a con ## Lifecycle The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist. -1. OCI compliant runtime is invoked with a reference to the location of the bundle. +1. OCI compliant runtime is invoked with a reference to the [configuration](config.md). How this reference is passed to the runtime is an implementation detail. 2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md). Any updates to `config.json` after container is running MUST not affect the container. @@ -73,17 +73,16 @@ In particular, the state MUST be serialized as JSON. ### Start -`start ` +`start ` -This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container. +This operation MUST generate an error if it is not provided a path to the [configuration](config.md) and the container ID to associate with the container. If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST generate an error. -Using the data in `config.json`, that are in the bundle's directory, this operation MUST create a new container. This includes creating the relevant namespaces, resource limits, etc and configuring the appropriate capabilities for the container. A new process within the scope of the container MUST be created as specified by the `config.json` file otherwise an error MUST be generated. The runtime MAY validate `config.json` against this spec, either generically or with respect to the local system capabilities, before creating the container ([step 2](#lifecycle)). If the runtime does not perform initial validation and triggers an error due to an invalid or incompatible configuration, it MUST generate an error and jump to cleanup ([step 7](#lifecycle)). -Runtime callers who are interested in pre-start validation can run [bundle-validation tools](implementations.md#testing--tools) before invoking the start operation. +Runtime callers who are interested in pre-start validation can run [configuration-validation tools](implementations.md#testing--tools) before invoking the start operation. Attempting to start an already running container MUST have no effect on the container and MUST generate an error. diff --git a/specs-go/state.go b/specs-go/state.go index d3ad79d9c..25d2b9d32 100644 --- a/specs-go/state.go +++ b/specs-go/state.go @@ -8,6 +8,6 @@ type State struct { ID string `json:"id"` // Pid is the process id for the container's main process. Pid int `json:"pid"` - // BundlePath is the path to the container's bundle directory. - BundlePath string `json:"bundlePath"` + // ConfigPath is the path to the container's configuration. + ConfigPath string `json:"configPath"` }