Skip to content

Commit 1df9fa9

Browse files
kershawmehtakershawmehta
committed
zos updates - add zos namespaces, remove zos devices
This PR proposes updates to the OCI runtime spec with z/OS platform-specific details, including adding namespaces, adding noNewPrivileges flag, and removing devices. These changes are currently in use by the IBM z/OS Container Platform (zOSCP) product - details can be found here: https://www.ibm.com/products/zos-container-platform. Signed-off-by: Neil Johnson <[email protected]> Signed-off-by: Kershaw Mehta <[email protected]>
1 parent 09fcb39 commit 1df9fa9

File tree

6 files changed

+237
-76
lines changed

6 files changed

+237
-76
lines changed

‎config-zos.md

+48-12
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,56 @@
1-
_This document is a work in progress._
2-
31
# <a name="ZOSContainerConfiguration" />z/OS Container Configuration
42

53
This document describes the schema for the [z/OS-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md).
4+
The z/OS container specification uses z/OS UNIX kernel features like namespaces and filesystem jails to fulfill the spec.
5+
6+
Applications expecting a z/OS environment will very likely expect these file paths to be set up correctly.
7+
8+
The following filesystems SHOULD be made available in each container's filesystem:
9+
10+
| Path | Type |
11+
| -------- | ------ |
12+
| /proc | [proc][] |
13+
14+
## <a name="configZOSNamespaces" />Namespaces
15+
16+
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.
17+
Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes.
18+
For more information, see https://www.ibm.com/docs/zos/latest?topic=planning-namespaces-zos-unix.
19+
20+
Namespaces are specified as an array of entries inside the `namespaces` root field.
21+
The following parameters can be specified to set up namespaces:
622

7-
## <a name="configZOSDevices" />Devices
23+
* **`type`** *(string, REQUIRED)* - namespace type. The following namespace types SHOULD be supported:
24+
* **`pid`** processes inside the container will only be able to see other processes inside the same container or inside the same pid namespace.
25+
* **`mount`** the container will have an isolated mount table.
26+
* **`ipc`** processes inside the container will only be able to communicate to other processes inside the same container via system level IPC.
27+
* **`uts`** the container will be able to have its own hostname and domain name.
28+
* **`path`** *(string, OPTIONAL)* - namespace file.
29+
This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace).
30+
The runtime MUST place the container process in the namespace associated with that `path`.
31+
The runtime MUST [generate an error](runtime.md#errors) if `path` is not associated with a namespace of type `type`.
832

9-
**`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container.
10-
The runtime MAY supply them however it likes.
33+
If `path` is not specified, the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`.
1134

12-
Each entry has the following structure:
35+
If a namespace type is not specified in the `namespaces` array, the container MUST inherit the [runtime namespace](glossary.md#runtime-namespace) of that type.
36+
If a `namespaces` field contains duplicated namespaces with same `type`, the runtime MUST [generate an error](runtime.md#errors).
1337

14-
* **`type`** *(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`.
15-
* **`path`** *(string, REQUIRED)* - full path to device inside container.
16-
If a file already exists at `path` that does not match the requested device, the runtime MUST generate an error.
17-
* **`major, minor`** *(int64, REQUIRED unless `type` is `p`)* - major, minor numbers for the device.
18-
* **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device.
38+
### Example
1939

20-
The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices.
40+
```json
41+
"namespaces": [
42+
{
43+
"type": "pid",
44+
"path": "/proc/1234/ns/pid"
45+
},
46+
{
47+
"type": "mount"
48+
},
49+
{
50+
"type": "ipc"
51+
},
52+
{
53+
"type": "uts"
54+
}
55+
]
56+
```

‎config.md

+6
Original file line numberDiff line numberDiff line change
@@ -353,6 +353,12 @@ For Linux-based systems, the `process` object supports the following process-spe
353353
CPU affinity after the process is moved to container's cgroup, and the
354354
final affinity is determined by the Linux kernel.
355355

356+
### <a name="configZOSProcess" />z/OS Process
357+
358+
For z/OS-based systems, the `process` object supports the following process-specific properties.
359+
360+
* **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the process from gaining additional privileges.
361+
356362
### <a name="configUser" />User
357363

358364
The user for the process is a platform-specific structure that allows specific control over which user the process runs as.

‎schema/config-zos.json

+6-2
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,14 @@
33
"description": "z/OS platform-specific configurations",
44
"type": "object",
55
"properties": {
6-
"devices": {
6+
"namespaces": {
77
"type": "array",
88
"items": {
9-
"$ref": "defs-zos.json#/definitions/Device"
9+
"anyOf": [
10+
{
11+
"$ref": "defs-zos.json#/definitions/NamespaceReference"
12+
}
13+
]
1014
}
1115
}
1216
}

‎schema/defs-zos.json

+15-43
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,27 @@
11
{
22
"definitions": {
3-
"Major": {
4-
"description": "major device number",
5-
"$ref": "defs.json#/definitions/int64"
6-
},
7-
"Minor": {
8-
"description": "minor device number",
9-
"$ref": "defs.json#/definitions/int64"
10-
},
11-
"FileMode": {
12-
"description": "File permissions mode (typically an octal value)",
13-
"type": "integer",
14-
"minimum": 0,
15-
"maximum": 512
16-
},
17-
"FileType": {
18-
"description": "Type of a block or special character device",
3+
"NamespaceType": {
194
"type": "string",
20-
"pattern": "^[cbup]$"
5+
"enum": [
6+
"mount",
7+
"pid",
8+
"uts",
9+
"ipc"
10+
]
2111
},
22-
"Device": {
12+
"NamespaceReference": {
2313
"type": "object",
24-
"required": [
25-
"type",
26-
"path",
27-
"major",
28-
"minor"
29-
],
3014
"properties": {
31-
"path": {
32-
"$ref": "defs.json#/definitions/FilePath"
33-
},
3415
"type": {
35-
"$ref": "#/definitions/FileType"
16+
"$ref": "#/definitions/NamespaceType"
3617
},
37-
"major": {
38-
"$ref": "#/definitions/Major"
39-
},
40-
"minor": {
41-
"$ref": "#/definitions/Minor"
42-
},
43-
"fileMode": {
44-
"$ref": "#/definitions/FileMode"
45-
},
46-
"uid": {
47-
"$ref": "defs.json#/definitions/UID"
48-
},
49-
"gid": {
50-
"$ref": "defs.json#/definitions/GID"
18+
"path": {
19+
"$ref": "defs.json#/definitions/FilePath"
5120
}
52-
}
21+
},
22+
"required": [
23+
"type"
24+
]
5325
}
5426
}
5527
}

‎schema/test/config/good/zos-example.json

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
{
2+
"ociVersion": "0.5.0-dev",
3+
"process": {
4+
"terminal": true,
5+
"user": {
6+
"uid": 1,
7+
"gid": 1,
8+
"additionalGids": [
9+
5,
10+
6
11+
]
12+
},
13+
"args": [
14+
"sh"
15+
],
16+
"env": [
17+
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/bin",
18+
"TERM=xterm"
19+
],
20+
"cwd": "/",
21+
"rlimits": [
22+
{
23+
"type": "RLIMIT_NOFILE",
24+
"hard": 1024,
25+
"soft": 1024
26+
}
27+
],
28+
"noNewPrivileges": true
29+
},
30+
"root": {
31+
"path": "rootfs"
32+
},
33+
"hostname": "slartibartfast",
34+
"mounts": [
35+
{
36+
"destination": "/proc",
37+
"type": "proc",
38+
"source": "proc"
39+
},
40+
{
41+
"destination": "/dev",
42+
"type": "tfs",
43+
"source": "tmpfs",
44+
"options": [
45+
"nosuid",
46+
"-p 1755",
47+
"-s 64"
48+
]
49+
}
50+
],
51+
"hooks": {
52+
"prestart": [
53+
{
54+
"path": "/usr/bin/fix-mounts",
55+
"args": [
56+
"fix-mounts",
57+
"arg1",
58+
"arg2"
59+
],
60+
"env": [
61+
"key1=value1"
62+
]
63+
},
64+
{
65+
"path": "/usr/bin/setup-network"
66+
}
67+
],
68+
"createRuntime": [
69+
{
70+
"path": "/usr/bin/fix-mounts",
71+
"args": [
72+
"fix-mounts",
73+
"arg1",
74+
"arg2"
75+
],
76+
"env": [
77+
"key1=value1"
78+
]
79+
},
80+
{
81+
"path": "/usr/bin/setup-network"
82+
}
83+
],
84+
"createContainer": [
85+
{
86+
"path": "/usr/bin/mount-hook",
87+
"args": [
88+
"-mount",
89+
"arg1",
90+
"arg2"
91+
],
92+
"env": [
93+
"key1=value1"
94+
]
95+
}
96+
],
97+
"startContainer": [
98+
{
99+
"path": "/usr/bin/refresh-ldcache"
100+
}
101+
],
102+
"poststart": [
103+
{
104+
"path": "/usr/bin/notify-start",
105+
"timeout": 5
106+
}
107+
],
108+
"poststop": [
109+
{
110+
"path": "/usr/sbin/cleanup.sh",
111+
"args": [
112+
"cleanup.sh",
113+
"-f"
114+
]
115+
}
116+
]
117+
},
118+
"zos": {
119+
"namespaces": [
120+
{
121+
"type": "pid"
122+
},
123+
{
124+
"type": "ipc"
125+
},
126+
{
127+
"type": "uts"
128+
},
129+
{
130+
"type": "mount"
131+
}
132+
]
133+
},
134+
"annotations": {
135+
"com.example.key1": "value1",
136+
"com.example.key2": "value2"
137+
}
138+
}

‎specs-go/config.go

+24-19
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ type Process struct {
8383
// Rlimits specifies rlimit options to apply to the process.
8484
Rlimits []POSIXRlimit `json:"rlimits,omitempty" platform:"linux,solaris,zos"`
8585
// NoNewPrivileges controls whether additional privileges could be gained by processes in the container.
86-
NoNewPrivileges bool `json:"noNewPrivileges,omitempty" platform:"linux"`
86+
NoNewPrivileges bool `json:"noNewPrivileges,omitempty" platform:"linux,zos"`
8787
// ApparmorProfile specifies the apparmor profile for the container.
8888
ApparmorProfile string `json:"apparmorProfile,omitempty" platform:"linux"`
8989
// Specify an oom_score_adj for the container.
@@ -846,28 +846,33 @@ type LinuxIntelRdt struct {
846846

847847
// ZOS contains platform-specific configuration for z/OS based containers.
848848
type ZOS struct {
849-
// Devices are a list of device nodes that are created for the container
850-
Devices []ZOSDevice `json:"devices,omitempty"`
849+
// Namespaces contains the namespaces that are created and/or joined by the container
850+
Namespaces []ZOSNamespace `json:"namespaces,omitempty"`
851851
}
852852

853-
// ZOSDevice represents the mknod information for a z/OS special device file
854-
type ZOSDevice struct {
855-
// Path to the device.
856-
Path string `json:"path"`
857-
// Device type, block, char, etc.
858-
Type string `json:"type"`
859-
// Major is the device's major number.
860-
Major int64 `json:"major"`
861-
// Minor is the device's minor number.
862-
Minor int64 `json:"minor"`
863-
// FileMode permission bits for the device.
864-
FileMode *os.FileMode `json:"fileMode,omitempty"`
865-
// UID of the device.
866-
UID *uint32 `json:"uid,omitempty"`
867-
// Gid of the device.
868-
GID *uint32 `json:"gid,omitempty"`
853+
// ZOSNamespace is the configuration for a z/OS namespace
854+
type ZOSNamespace struct {
855+
// Type is the type of namespace
856+
Type ZOSNamespaceType `json:"type"`
857+
// Path is a path to an existing namespace persisted on disk that can be joined
858+
// and is of the same type
859+
Path string `json:"path,omitempty"`
869860
}
870861

862+
// ZOSNamespaceType is one of the z/OS namespaces
863+
type ZOSNamespaceType string
864+
865+
const (
866+
// PIDNamespace for isolating process IDs
867+
ZOSPIDNamespace ZOSNamespaceType = "pid"
868+
// MountNamespace for isolating mount points
869+
ZOSMountNamespace ZOSNamespaceType = "mount"
870+
// IPCNamespace for isolating System V IPC, POSIX message queues
871+
ZOSIPCNamespace ZOSNamespaceType = "ipc"
872+
// UTSNamespace for isolating hostname and NIS domain name
873+
ZOSUTSNamespace ZOSNamespaceType = "uts"
874+
)
875+
871876
// LinuxSchedulerPolicy represents different scheduling policies used with the Linux Scheduler
872877
type LinuxSchedulerPolicy string
873878

0 commit comments

Comments
 (0)