pyrox.dev
ociTools: init
authored by
Katharina Fey
and committed by
Alyssa Ross
18f7f19c
43dade23
+1
doc/functions.xml
+1
doc/functions.xml
+76
doc/functions/ocitools.xml
+76
doc/functions/ocitools.xml
···
···
1
+
<section xmlns="http://docbook.org/ns/docbook"
2
+
xmlns:xlink="http://www.w3.org/1999/xlink"
3
+
xmlns:xi="http://www.w3.org/2001/XInclude"
4
+
xml:id="sec-pkgs-ociTools">
5
+
<title>pkgs.ociTools</title>
6
+
7
+
<para>
8
+
<varname>pkgs.ociTools</varname> is a set of functions for creating
9
+
containers according to the
10
+
<link xlink:href="https://github.com/opencontainers/runtime-spec">OCI
11
+
container specification v1.0.0</link>. Beyond that it makes no assumptions
12
+
about the container runner you choose to use to run the created container.
13
+
</para>
14
+
15
+
<section xml:id="ssec-pkgs-ociTools-buildContainer">
16
+
<title>buildContainer</title>
17
+
18
+
<para>
19
+
This function creates a simple OCI container that runs a single command
20
+
inside of it. An OCI container consists of a <varname>config.json</varname>
21
+
and a rootfs directory.The nix store of the container will contain all
22
+
referenced dependencies of the given command.
23
+
</para>
24
+
25
+
<para>
26
+
The parameters of <varname>buildContainer</varname> with an example value
27
+
are described below:
28
+
</para>
29
+
30
+
<example xml:id='ex-ociTools-buildContainer'>
31
+
<title>Build Container</title>
32
+
<programlisting>
33
+
buildContainer {
34
+
cmd = with pkgs; writeScript "run.sh" ''
35
+
#!${bash}/bin/bash
36
+
${coreutils}/bin/exec ${bash}/bin/bash
37
+
''; <co xml:id='ex-ociTools-buildContainer-1' />
38
+
39
+
mounts = {
40
+
"/data" = {
41
+
type = "none";
42
+
source = "/var/lib/mydata";
43
+
options = [ "bind" ];
44
+
};
45
+
};<co xml:id='ex-ociTools-buildContainer-2' />
46
+
47
+
readonly = false; <co xml:id='ex-ociTools-buildContainer-3' />
48
+
}
49
+
50
+
</programlisting>
51
+
<calloutlist>
52
+
<callout arearefs='ex-ociTools-buildContainer-1'>
53
+
<para>
54
+
<varname>cmd</varname> specifies the program to run inside the container.
55
+
This is the only required argument for <varname>buildContainer</varname>.
56
+
All referenced packages inside the derivation will be made available
57
+
inside the container
58
+
</para>
59
+
</callout>
60
+
<callout arearefs='ex-ociTools-buildContainer-2'>
61
+
<para>
62
+
<varname>mounts</varname> specifies additional mount points chosen by the
63
+
user. By default only a minimal set of necessary filesystems are mounted
64
+
into the container (e.g procfs, cgroupfs)
65
+
</para>
66
+
</callout>
67
+
<callout arearefs='ex-ociTools-buildContainer-3'>
68
+
<para>
69
+
<varname>readonly</varname> makes the container's rootfs read-only if it is set to true.
70
+
The default value is false <literal>false</literal>.
71
+
</para>
72
+
</callout>
73
+
</calloutlist>
74
+
</example>
75
+
</section>
76
+
</section>
+78
pkgs/build-support/oci-tools/default.nix
+78
pkgs/build-support/oci-tools/default.nix
···
···
1
+
{ lib, writeText, runCommand, writeReferencesToFile }:
2
+
3
+
{
4
+
buildContainer =
5
+
{ args
6
+
, mounts ? {}
7
+
, os ? "linux"
8
+
, arch ? "x86_64"
9
+
, readonly ? false
10
+
}:
11
+
let
12
+
sysMounts = {
13
+
"/proc" = {
14
+
type = "proc";
15
+
source = "proc";
16
+
};
17
+
"/dev" = {
18
+
type = "tmpfs";
19
+
source = "tmpfs";
20
+
options = [ "nosuid" "strictatime" "mode=755" "size=65536k" ];
21
+
};
22
+
"/dev/pts" = {
23
+
type = "devpts";
24
+
source = "devpts";
25
+
options = [ "nosuid" "noexec" "newinstance" "ptmxmode=0666" "mode=755" "gid=5" ];
26
+
};
27
+
"/dev/shm" = {
28
+
type = "tmpfs";
29
+
source = "shm";
30
+
options = [ "nosuid" "noexec" "nodev" "mode=1777" "size=65536k" ];
31
+
};
32
+
"/dev/mqueue" = {
33
+
type = "mqueue";
34
+
source = "mqueue";
35
+
options = [ "nosuid" "noexec" "nodev" ];
36
+
};
37
+
"/sys" = {
38
+
type = "sysfs";
39
+
source = "sysfs";
40
+
options = [ "nosuid" "noexec" "nodev" "ro" ];
41
+
};
42
+
"/sys/fs/cgroup" = {
43
+
type = "cgroup";
44
+
source = "cgroup";
45
+
options = [ "nosuid" "noexec" "nodev" "realatime" "ro" ];
46
+
};
47
+
};
48
+
config = writeText "config.json" (builtins.toJSON {
49
+
ociVersion = "1.0.0";
50
+
platform = {
51
+
inherit os arch;
52
+
};
53
+
54
+
linux = {
55
+
namespaces = map (type: { inherit type; }) [ "pid" "network" "mount" "ipc" "uts" ];
56
+
};
57
+
58
+
root = { path = "rootfs"; inherit readonly; };
59
+
60
+
process = {
61
+
inherit args;
62
+
user = { uid = 0; gid = 0; };
63
+
cwd = "/";
64
+
};
65
+
66
+
mounts = lib.mapAttrsToList (destination: { type, source, options ? null }: {
67
+
inherit destination type source options;
68
+
}) sysMounts;
69
+
});
70
+
in
71
+
runCommand "join" {} ''
72
+
set -o pipefail
73
+
mkdir -p $out/rootfs/{dev,proc,sys}
74
+
cp ${config} $out/config.json
75
+
xargs tar c < ${writeReferencesToFile args} | tar -xC $out/rootfs/
76
+
'';
77
+
}
78
+
+2
pkgs/top-level/all-packages.nix
+2
pkgs/top-level/all-packages.nix