doc/build-helpers/images/ocitools.section.md

   1 # pkgs.ociTools {#sec-pkgs-ociTools}
   2
   3 `pkgs.ociTools` is a set of functions for creating runtime container bundles according to the [OCI runtime specification v1.0.0](https://github.com/opencontainers/runtime-spec/blob/v1.0.0/spec.md).
   4 It makes no assumptions about the container runner you choose to use to run the created container.
   5
   6 The set of functions in `pkgs.ociTools` currently does not handle the [OCI image specification](https://github.com/opencontainers/image-spec).
   7
   8 At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.
   9 At this point the OCI Runtime Bundle would be run by an OCI Runtime.
  10 `pkgs.ociTools` provides utilities to create OCI Runtime bundles.
  11
  12 ## buildContainer {#ssec-pkgs-ociTools-buildContainer}
  13
  14 This function creates an OCI runtime container (consisting of a `config.json` and a root filesystem directory) that runs a single command inside of it.
  15 The nix store of the container will contain all referenced dependencies of the given command.
  16
  17 This function has an assumption that the container will run on POSIX platforms, and sets configurations (such as the user running the process or certain mounts) according to this assumption.
  18 Because of this, a container built with `buildContainer` will not work on Windows or other non-POSIX platforms without modifications to the container configuration.
  19 These modifications aren't supported by `buildContainer`.
  20
  21 For `linux` platforms, `buildContainer` also configures the following namespaces (see {manpage}`unshare(1)`) to isolate the OCI container from the global namespace:
  22 PID, network, mount, IPC, and UTS.
  23
  24 Note that no user namespace is created, which means that you won't be able to run the container unless you are the `root` user.
  25
  26 ### Inputs {#ssec-pkgs-ociTools-buildContainer-inputs}
  27
  28 `buildContainer` expects an argument with the following attributes:
  29
  30 `args` (List of String)
  31
  32 : Specifies a set of arguments to run inside the container.
  33   Any packages referenced by `args` will be made available inside the container.
  34
  35 `mounts` (Attribute Set; _optional_)
  36
  37 : Would specify additional mounts that the runtime must make available to the container.
  38
  39   :::{.warning}
  40   As explained in [issue #290879](https://github.com/NixOS/nixpkgs/issues/290879), this attribute is currently ignored.
  41   :::
  42
  43   :::{.note}
  44   `buildContainer` includes a minimal set of necessary filesystems to be mounted into the container, and this set can't be changed with the `mounts` attribute.
  45   :::
  46
  47   _Default value:_ `{}`.
  48
  49 `readonly` (Boolean; _optional_)
  50
  51 : If `true`, sets the container's root filesystem as read-only.
  52
  53   _Default value:_ `false`.
  54
  55 `os` **DEPRECATED**
  56
  57 : Specifies the operating system on which the container filesystem is based on.
  58   If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
  59   According to the linked specification, all possible values for `$GOOS` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `darwin` or `linux`.
  60
  61   _Default value:_ `"linux"`.
  62
  63 `arch` **DEPRECATED**
  64
  65 : Used to specify the architecture for which the binaries in the container filesystem have been compiled.
  66   If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
  67   According to the linked specification, all possible values for `$GOARCH` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `386`, `amd64`, `arm`, or `arm64`.
  68
  69   _Default value:_ `x86_64`.
  70
  71 ### Examples {#ssec-pkgs-ociTools-buildContainer-examples}
  72
  73 ::: {.example #ex-ociTools-buildContainer-bash}
  74 # Creating an OCI runtime container that runs `bash`
  75
  76 This example uses `ociTools.buildContainer` to create a simple container that runs `bash`.
  77
  78 ```nix
  79 { ociTools, lib, bash }:
  80 ociTools.buildContainer {
  81   args = [
  82     (lib.getExe bash)
  83   ];
  84
  85   readonly = false;
  86 }
  87 ```
  88
  89 As an example of how to run the container generated by this package, we'll use `runc` to start the container.
  90 Any other tool that supports OCI containers could be used instead.
  91
  92 ```shell
  93 $ nix-build
  94 (some output removed for clarity)
  95 /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
  96
  97 $ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
  98 $ nix-shell -p runc
  99 [nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example
 100 help
 101 GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu)
 102 (some output removed for clarity)
 103 ```
 104 :::