Skip to content

Commit c57abfc

Browse files
vbattsvbatts
committed
proto: initial protobuf for structures
To have a less source based, and more consumable example of structures, this is an initial pass at protobuf structures for the structures in the specs golang source. There is some exercise needed in platform specific structures. For the sake of example, the Makefile defaults to outputing golang source, but has a 'c' target (`make c`) for C source, a `make py` and `make all` target. This User structure does not map to the cleanliness of the current go structure, but will allow the definition to be all in one place, regardless of the host that is doing the compilation. All field rules to `optional` for now. Per vish and the docs, https://developers.google.com/protocol-buffers/docs/proto?csw=1#specifying-field-rules "! Required Is Forever" There are a couple of concessions, but is pretty much lined up. Signed-off-by: Vincent Batts <[email protected]>
1 parent dca1dfd commit c57abfc

File tree

4 files changed

+393
-0
lines changed

4 files changed

+393
-0
lines changed

‎proto/Makefile‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
2+
DESTDIR ?= .
3+
PROTO_FILES := $(wildcard *.proto)
4+
GO_FILES := $(patsubst %.proto,%.pb.go,$(PROTO_FILES))
5+
C_FILES := $(patsubst %.proto,%.pb-c.c,$(PROTO_FILES))
6+
C_HDR_FILES := $(patsubst %.proto,%.pb-c.h,$(PROTO_FILES))
7+
PY_FILES := $(patsubst %.proto,%_pb2.py,$(PROTO_FILES))
8+
9+
default: go
10+
11+
all: go py c
12+
13+
go: $(GO_FILES)
14+
15+
%.pb.go: %.proto
16+
protoc --go_out=$(DESTDIR) $^
17+
18+
c: $(C_FILES)
19+
20+
%.pb-c.c: %.proto
21+
protoc-c --c_out=$(DESTDIR) $^
22+
23+
py: $(PY_FILES)
24+
25+
%_pb2.py: %.proto
26+
protoc --python_out=$(DESTDIR) $^
27+
28+
29+
clean:
30+
rm -rf *~ $(GO_FILES) $(C_FILES) $(C_HDR_FILES) $(PY_FILES)
31+

‎proto/config.proto‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
//package oci.config.bundle;
2+
package oci;
3+
4+
// Spec is the base configuration for the container. It specifies platform
5+
// independent configuration.
6+
message Spec {
7+
// Version is the version of the specification that is supported.
8+
optional string Version = 1;
9+
// Platform is the host information for OS and Arch.
10+
optional Platform Platform = 2; // [default=77];
11+
// Process is the container's main process.
12+
optional Process Process = 3;
13+
// Root is the root information for the container's filesystem.
14+
optional Root Root = 4;
15+
// Hostname is the container's host name.
16+
optional string Hostname = 5;
17+
// Mounts profile configuration for adding mounts to the container's filesystem.
18+
repeated MountPoint Mounts = 6;
19+
}
20+
21+
22+
// LinuxSpec is the full specification for linux containers.
23+
message LinuxSpec {
24+
optional Spec Spec = 1;
25+
// LinuxConfig is platform specific configuration for linux based containers.
26+
optional LinuxConfig LinuxConfig = 2;
27+
}
28+
29+
// LinuxConfig contains platform specific configuration for linux based containers.
30+
message LinuxConfig {
31+
// Capabilities are linux capabilities that are kept for the container.
32+
repeated string Capabilities = 1;
33+
}
34+
35+
// Platform specifies OS and arch information for the host system that the container
36+
// is created for.
37+
message Platform {
38+
// OS is the operating system.
39+
optional string OS = 1;
40+
// Arch is the architecture
41+
optional string Arch = 2;
42+
}
43+
44+
// Process contains information to start a specific application inside the container.
45+
message Process {
46+
// Terminal creates an interactive terminal for the container.
47+
optional bool Terminal = 1;
48+
// User specifies user information for the process.
49+
optional User User = 2;
50+
// Args specifies the binary and arguments for the application to execute.
51+
repeated string Args = 3;
52+
// Env populates the process environment for the process.
53+
repeated string Env = 4;
54+
// Cwd is the current working directory for the process and must be
55+
// relative to the container's root.
56+
optional string Cwd = 5;
57+
}
58+
59+
enum PlatformType {
60+
LINUX = 1;
61+
}
62+
63+
// User specifies user information for the process.
64+
message User {
65+
// Type so that receivers of this message can `switch` for the fields expected
66+
optional PlatformType Type = 1 [default = LINUX];
67+
// LinuxUserFields are to be used when Type is LINUX
68+
optional linuxUserFields LinuxUserFields = 2;
69+
}
70+
71+
// User specifies linux specific user and group information for the container's
72+
// main process.
73+
message linuxUserFields {
74+
// UID is the user id.
75+
optional int32 UID = 1;
76+
// GID is the group id.
77+
optional int32 GID = 2;
78+
repeated int32 AdditionalGids = 3;
79+
}
80+
81+
// Root contains information about the container's root filesystem on the host.
82+
message Root {
83+
// Path is the absolute path to the container's root filesystem.
84+
optional string Path = 1;
85+
// Readonly makes the root filesystem for the container readonly before the process is executed.
86+
optional bool Readonly = 2;
87+
}
88+
89+
// MountPoint describes a directory that may be fullfilled by a mount in the runtime.json.
90+
message MountPoint {
91+
// Name is a unique descriptive identifier for this mount point.
92+
optional string Name = 1;
93+
// Path specifies the path of the mount. The path and child directories MUST exist, a runtime MUST NOT create directories automatically to a mount point.
94+
optional string Path = 2;
95+
}

‎proto/runtime_config.proto‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
//package oci.config.runtime;
2+
package oci;
3+
4+
import "runtime_config_linux.proto";
5+
6+
// RuntimeSpec is the generic runtime state information on a running container
7+
message RuntimeSpec {
8+
// Mounts is a mapping of names to mount configurations.
9+
// Which mounts will be mounted and where should be chosen with MountPoints
10+
// in Spec.
11+
repeated MountFieldEntry Mounts = 1;
12+
// Hooks are the commands run at various lifecycle events of the container.
13+
optional Hooks Hooks = 2;
14+
}
15+
16+
// LinuxRuntimeSpec is the full specification for linux containers.
17+
message LinuxRuntimeSpec {
18+
optional RuntimeSpec RuntimeSpec = 1;
19+
// LinuxRuntime is platform specific configuration for linux based containers.
20+
optional oci.LinuxRuntime Linux = 2;
21+
}
22+
23+
// MountFieldEntry is more backwards compatible protobuf associative map (than map<string, Mount>)
24+
message MountFieldEntry {
25+
required string key = 1;
26+
required Mount value = 2;
27+
}
28+
29+
// Mount specifies a mount for a container
30+
message Mount {
31+
// Type specifies the mount kind.
32+
optional string Type = 1;
33+
// Source specifies the source path of the mount. In the case of bind mounts on
34+
// linux based systems this would be the file on the host.
35+
optional string Source = 2;
36+
// Options are fstab style mount options.
37+
repeated string Options = 3;
38+
}
39+
40+
// Hook specifies a command that is run at a particular event in the lifecycle of a container
41+
message Hook {
42+
optional string Path = 1;
43+
repeated string Args = 2;
44+
repeated string Env = 3;
45+
}
46+
47+
// Hooks for container setup and teardown
48+
message Hooks {
49+
// Prestart is a list of hooks to be run before the container process is executed.
50+
// On Linux, they are run after the container namespaces are created.
51+
repeated Hook Prestart = 1;
52+
// Poststop is a list of hooks to be run after the container process exits.
53+
repeated Hook Poststop = 2;
54+
}

‎proto/runtime_config_linux.proto‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
package oci;
2+
3+
// LinuxStateDirectory holds the container's state information
4+
message DefaultState {
5+
// TODO(vbatts) not as elegant in some ways, but there is not a concept of const here
6+
optional string Directory = 1 [default = "/run/opencontainer/containers"];
7+
}
8+
9+
// LinuxRuntime hosts the Linux-only runtime information
10+
message LinuxRuntime {
11+
// UIDMapping specifies user mappings for supporting user namespaces on linux.
12+
repeated IDMapping UIDMapping = 1;
13+
// GIDMapping specifies group mappings for supporting user namespaces on linux.
14+
repeated IDMapping GIDMapping = 2;
15+
// Rlimits specifies rlimit options to apply to the container's process.
16+
repeated Rlimit Rlimits = 3;
17+
// Sysctl are a set of key value pairs that are set for the container on start
18+
repeated StringStringEntry Sysctl = 4;
19+
// Resources contain cgroup information for handling resource constraints
20+
// for the container
21+
optional Resources Resources = 5;
22+
// CgroupsPath specifies the path to cgroups that are created and/or joined by the container.
23+
// The path is expected to be relative to the cgroups mountpoint.
24+
// If resources are specified, the cgroups at CgroupsPath will be updated based on resources.
25+
optional string CgroupsPath = 6;
26+
// Namespaces contains the namespaces that are created and/or joined by the container
27+
repeated Namespace Namespaces = 7;
28+
// Devices are a list of device nodes that are created and enabled for the container
29+
repeated Device Devices = 8;
30+
// ApparmorProfile specified the apparmor profile for the container.
31+
optional string ApparmorProfile = 9;
32+
// SelinuxProcessLabel specifies the selinux context that the container process is run as.
33+
optional string SelinuxProcessLabel = 10;
34+
// Seccomp specifies the seccomp security settings for the container.
35+
optional Seccomp Seccomp = 11;
36+
// RootfsPropagation is the rootfs mount propagation mode for the container
37+
optional string RootfsPropagation = 12;
38+
}
39+
40+
// IDMapping specifies UID/GID mappings
41+
message IDMapping {
42+
// HostID is the UID/GID of the host user or group
43+
optional int32 HostID = 1;
44+
// ContainerID is the UID/GID of the container's user or group
45+
optional int32 ContainerID = 2;
46+
// Size is the length of the range of IDs mapped between the two namespaces
47+
optional int32 Size = 3;
48+
}
49+
50+
// Rlimit type and restrictions
51+
message Rlimit {
52+
// Type of the rlimit to set
53+
optional string Type = 1;
54+
// Hard is the hard limit for the specified type
55+
optional uint64 Hard = 2;
56+
// Soft is the soft limit for the specified type
57+
optional uint64 Soft = 3;
58+
}
59+
60+
// StringStringEntry is more backwards compatible protobuf associative map (than map<string, Mount>)
61+
message StringStringEntry {
62+
required string key = 1;
63+
required string value = 2;
64+
}
65+
66+
// Resources has container runtime resource constraints
67+
message Resources {
68+
// DisableOOMKiller disables the OOM killer for out of memory conditions
69+
optional bool DisableOOMKiller = 1;
70+
// Memory restriction configuration
71+
optional Memory Memory = 2;
72+
// CPU resource restriction configuration
73+
optional CPU CPU = 3;
74+
// Task resource restriction configuration.
75+
optional Pids Pids = 4;
76+
// BlockIO restriction configuration
77+
optional BlockIO BlockIO = 5;
78+
// Hugetlb limit (in bytes)
79+
repeated HugepageLimit HugepageLimits = 6;
80+
// Network restriction configuration
81+
optional Network Network = 7;
82+
}
83+
84+
// Memory for Linux cgroup 'memory' resource management
85+
message Memory {
86+
// Memory limit (in bytes)
87+
optional int64 Limit = 1;
88+
// Memory reservation or soft_limit (in bytes)
89+
optional int64 Reservation = 2;
90+
// Total memory usage (memory + swap); set `-1' to disable swap
91+
optional int64 Swap = 3;
92+
// Kernel memory limit (in bytes)
93+
optional int64 Kernel = 4;
94+
// How aggressive the kernel will swap memory pages. Range from 0 to 100. Set -1 to use system default
95+
optional int64 Swappiness = 5;
96+
}
97+
98+
// CPU for Linux cgroup 'cpu' resource management
99+
message CPU {
100+
// CPU shares (relative weight vs. other cgroups with cpu shares)
101+
optional int64 Shares = 1;
102+
// CPU hardcap limit (in usecs). Allowed cpu time in a given period
103+
optional int64 Quota = 2;
104+
// CPU period to be used for hardcapping (in usecs). 0 to use system default
105+
optional int64 Period = 3;
106+
// How many time CPU will use in realtime scheduling (in usecs)
107+
optional int64 RealtimeRuntime = 4;
108+
// CPU period to be used for realtime scheduling (in usecs)
109+
optional int64 RealtimePeriod = 5;
110+
// CPU to use within the cpuset
111+
optional string Cpus = 6;
112+
// MEM to use within the cpuset
113+
optional string Mems = 7;
114+
}
115+
116+
// Pids for Linux cgroup 'pids' resource management (Linux 4.3)
117+
message Pids {
118+
// Maximum number of PIDs. A value < 0 implies "no limit".
119+
optional int64 Limit = 1;
120+
}
121+
122+
// BlockIO for Linux cgroup 'blockio' resource management
123+
message BlockIO {
124+
// Specifies per cgroup weight, range is from 10 to 1000
125+
optional int64 Weight = 1;
126+
// Weight per cgroup per device, can override BlkioWeight
127+
optional string WeightDevice = 2;
128+
// IO read rate limit per cgroup per device, bytes per second
129+
optional string ThrottleReadBpsDevice = 3;
130+
// IO write rate limit per cgroup per divice, bytes per second
131+
optional string ThrottleWriteBpsDevice = 4;
132+
// IO read rate limit per cgroup per device, IO per second
133+
optional string ThrottleReadIOpsDevice = 5;
134+
// IO write rate limit per cgroup per device, IO per second
135+
optional string ThrottleWriteIOpsDevice = 6;
136+
}
137+
138+
// HugepageLimit structure corresponds to limiting kernel hugepages
139+
message HugepageLimit {
140+
optional string Pagesize = 1;
141+
optional int32 Limit = 2;
142+
}
143+
144+
// Network identification and priority configuration
145+
message Network {
146+
// Set class identifier for container's network packets
147+
optional string ClassID = 1;
148+
// Set priority of network traffic for container
149+
repeated InterfacePriority Priorities = 2;
150+
}
151+
152+
// InterfacePriority for network interfaces
153+
message InterfacePriority {
154+
// Name is the name of the network interface
155+
optional string Name = 1;
156+
// Priority for the interface
157+
optional int64 Priority = 2;
158+
}
159+
160+
// Namespace is the configuration for a linux namespace
161+
message Namespace {
162+
// Type is the type of Linux namespace
163+
optional string Type = 1;
164+
// Path is a path to an existing namespace persisted on disk that can be joined
165+
// and is of the same type
166+
optional string Path = 2;
167+
}
168+
169+
// Device represents the information on a Linux special device file
170+
message Device {
171+
// Path to the device.
172+
optional string Path = 1;
173+
// Device type, block, char, etc.
174+
// TODO(vbatts) ensure int32 is fine here, instead of golang's rune
175+
optional int32 Type = 2;
176+
// Major is the device's major number.
177+
optional int64 Major = 3;
178+
// Minor is the device's minor number.
179+
optional int64 Minor = 4;
180+
// Cgroup permissions format, rwm.
181+
optional string Permissions = 5;
182+
// FileMode permission bits for the device.
183+
// TODO(vbatts) os.FileMode is an octal uint32
184+
optional uint32 FileMode = 6;
185+
// UID of the device.
186+
optional uint32 UID = 7;
187+
// Gid of the device.
188+
optional uint32 GID = 8;
189+
}
190+
191+
// Seccomp represents syscall restrictions
192+
message Seccomp {
193+
// TODO(vbatts) string instead of "Action" type
194+
optional string DefaultAction = 1;
195+
repeated Syscall Syscalls = 2;
196+
}
197+
198+
// Syscall is used to match a syscall in Seccomp
199+
message Syscall {
200+
optional string Name = 1;
201+
optional string Action = 2;
202+
repeated Arg Args = 3;
203+
}
204+
205+
// Arg used for matching specific syscall arguments in Seccomp
206+
message Arg {
207+
optional uint32 Index = 1;
208+
optional uint64 Value = 2;
209+
optional uint64 ValueTwo = 3;
210+
// Op is the operator string
211+
optional string Op = 4;
212+
}
213+

0 commit comments

Comments
 (0)