commit 67e55070ebaf0bf2d12e23c743a6fabebdebf731 · pyrox.dev/nixpkgs

+87 -20

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

···

       1
       1
        
       # pkgs.ociTools {#sec-pkgs-ociTools}

     

       2
       2
        
       

     

       3
       3
       -
       `pkgs.ociTools` is a set of functions for creating containers according to the [OCI container specification v1.0.0](https://github.com/opencontainers/runtime-spec). Beyond that, it makes no assumptions about the container runner you choose to use to run the created container.

     

       3
       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
       4
       +
       It makes no assumptions about the container runner you choose to use to run the created container.

     

       5
       5
       +
       

     

       6
       6
       +
       The set of functions in `pkgs.ociTools` currently does not handle the [OCI image specification](https://github.com/opencontainers/image-spec).

     

       7
       7
       +
       

     

       8
       8
       +
       At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.

     

       9
       9
       +
       At this point the OCI Runtime Bundle would be run by an OCI Runtime.

     

       10
       10
       +
       `pkgs.ociTools` provides utilities to create OCI Runtime bundles.

     

       4
       11
        
       

     

       5
       12
        
       ## buildContainer {#ssec-pkgs-ociTools-buildContainer}

     

       6
       13
        
       

     

       7
       7
       -
       This function creates a simple OCI container that runs a single command inside of it. An OCI container consists of a `config.json` and a rootfs directory. The nix store of the container will contain all referenced dependencies of the given command.

     

       14
       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
       15
       +
       The nix store of the container will contain all referenced dependencies of the given command.

     

       16
       16
       +
       

     

       17
       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
       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
       19
       +
       These modifications aren't supported by `buildContainer`.

     

       20
       20
       +
       

     

       21
       21
       +
       For `linux` platforms, `buildContainer` also configures the following namespaces (see {manpage}`unshare(1)`) to isolate the OCI container from the global namespace:

     

       22
       22
       +
       PID, network, mount, IPC, and UTS.

     

       23
       23
       +
       

     

       24
       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
       25
       +
       

     

       26
       26
       +
       ### Inputs {#ssec-pkgs-ociTools-buildContainer-inputs}

     

       27
       27
       +
       

     

       28
       28
       +
       `buildContainer` expects an argument with the following attributes:

     

       29
       29
       +
       

     

       30
       30
       +
       `args` (List of String)

     

       31
       31
       +
       

     

       32
       32
       +
       : Specifies a set of arguments to run inside the container.

     

       33
       33
       +
         Any packages referenced by `args` will be made available inside the container.

     

       34
       34
       +
       

     

       35
       35
       +
       `mounts` (Attribute Set; _optional_)

     

       36
       36
       +
       

     

       37
       37
       +
       : Would specify additional mounts that the runtime must make available to the container.

     

       38
       38
       +
       

     

       39
       39
       +
         :::{.warning}

     

       40
       40
       +
         As explained in [issue #290879](https://github.com/NixOS/nixpkgs/issues/290879), this attribute is currently ignored.

     

       41
       41
       +
         :::

     

       42
       42
       +
       

     

       43
       43
       +
         :::{.note}

     

       44
       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
       45
       +
         :::

     

       46
       46
       +
       

     

       47
       47
       +
         _Default value:_ `{}`.

     

       48
       48
       +
       

     

       49
       49
       +
       `readonly` (Boolean; _optional_)

     

       50
       50
       +
       

     

       51
       51
       +
       : If `true`, sets the container's root filesystem as read-only.

     

       52
       52
       +
       

     

       53
       53
       +
         _Default value:_ `false`.

     

       54
       54
       +
       

     

       55
       55
       +
       `os` **DEPRECATED**

     

       56
       56
       +
       

     

       57
       57
       +
       : Specifies the operating system on which the container filesystem is based on.

     

       58
       58
       +
         If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).

     

       59
       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
       60
       +
       

     

       61
       61
       +
         _Default value:_ `"linux"`.

     

       62
       62
       +
       

     

       63
       63
       +
       `arch` **DEPRECATED**

     

       64
       64
       +
       

     

       65
       65
       +
       : Used to specify the architecture for which the binaries in the container filesystem have been compiled.

     

       66
       66
       +
         If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).

     

       67
       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
       68
       +
       

     

       69
       69
       +
         _Default value:_ `x86_64`.

     

       70
       70
       +
       

     

       71
       71
       +
       ### Examples {#ssec-pkgs-ociTools-buildContainer-examples}

     

       72
       72
       +
       

     

       73
       73
       +
       ::: {.example #ex-ociTools-buildContainer-bash}

     

       74
       74
       +
       # Creating an OCI runtime container that runs `bash`

     

       8
       75
        
       

     

       9
       9
       -
       The parameters of `buildContainer` with an example value are described below:

     

       76
       76
       +
       This example uses `ociTools.buildContainer` to create a simple container that runs `bash`.

     

       10
       77
        
       

     

       11
       78
        
       ```nix

     

       12
       12
       -
       buildContainer {

     

       79
       79
       +
       { ociTools, lib, bash }:

     

       80
       80
       +
       ociTools.buildContainer {

     

       13
       81
        
         args = [

     

       14
       14
       -
           (with pkgs;

     

       15
       15
       -
             writeScript "run.sh" ''

     

       16
       16
       -
               #!${bash}/bin/bash

     

       17
       17
       -
               exec ${bash}/bin/bash

     

       18
       18
       -
             '').outPath

     

       82
       82
       +
           (lib.getExe bash)

     

       19
       83
        
         ];

     

       20
       84
        
       

     

       21
       21
       -
         mounts = {

     

       22
       22
       -
           "/data" = {

     

       23
       23
       -
             type = "none";

     

       24
       24
       -
             source = "/var/lib/mydata";

     

       25
       25
       -
             options = [ "bind" ];

     

       26
       26
       -
           };

     

       27
       27
       -
         };

     

       28
       28
       -
       

     

       29
       85
        
         readonly = false;

     

       30
       86
        
       }

     

       31
       87
        
       ```

     

       32
       88
        
       

     

       33
       33
       -
       - `args` specifies a set of arguments to run inside the container. This is the only required argument for `buildContainer`. All referenced packages inside the derivation will be made available inside the container.

     

       89
       89
       +
       As an example of how to run the container generated by this package, we'll use `runc` to start the container.

     

       90
       90
       +
       Any other tool that supports OCI containers could be used instead.

     

       34
       91
        
       

     

       35
       35
       -
       - `mounts` specifies additional mount points chosen by the user. By default only a minimal set of necessary filesystems are mounted into the container (e.g procfs, cgroupfs)

     

       92
       92
       +
       ```shell

     

       93
       93
       +
       $ nix-build

     

       94
       94
       +
       (some output removed for clarity)

     

       95
       95
       +
       /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join

     

       36
       96
        
       

     

       37
       37
       -
       - `readonly` makes the container's rootfs read-only if it is set to true. The default value is false `false`.

     

       97
       97
       +
       $ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join

     

       98
       98
       +
       $ nix-shell -p runc

     

       99
       99
       +
       [nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example

     

       100
       100
       +
       help

     

       101
       101
       +
       GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu)

     

       102
       102
       +
       (some output removed for clarity)

     

       103
       103
       +
       ```

     

       104
       104
       +
       :::

doc/manpage-urls.json

···

       318
       318
        
         "passwd(5)": "https://man.archlinux.org/man/passwd.5",

     

       319
       319
        
         "group(5)": "https://man.archlinux.org/man/group.5",

     

       320
       320
        
         "login.defs(5)": "https://man.archlinux.org/man/login.defs.5",

     

       321
       321
       +
         "unshare(1)": "https://man.archlinux.org/man/unshare.1.en",

     

       321
       322
        
         "nix-shell(1)": "https://nixos.org/manual/nix/stable/command-ref/nix-shell.html"

     

       322
       323
        
       }