From c73de6fac35a264d7a95d0875c7d7075bcbfae0e Mon Sep 17 00:00:00 2001 From: DS Date: Fri, 23 Feb 2024 04:56:08 -0800 Subject: doc: update docs in ociTools, follow doc conventions --- doc/build-helpers/images/ocitools.section.md | 107 ++++++++++++++++++++++----- doc/manpage-urls.json | 1 + 2 files changed, 88 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/build-helpers/images/ocitools.section.md b/doc/build-helpers/images/ocitools.section.md index c35f65bce007..96627615ffb5 100644 --- a/doc/build-helpers/images/ocitools.section.md +++ b/doc/build-helpers/images/ocitools.section.md @@ -1,37 +1,104 @@ # pkgs.ociTools {#sec-pkgs-ociTools} -`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. +`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). +It makes no assumptions about the container runner you choose to use to run the created container. + +The set of functions in `pkgs.ociTools` currently does not handle the [OCI image specification](https://github.com/opencontainers/image-spec). + +At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle. +At this point the OCI Runtime Bundle would be run by an OCI Runtime. +`pkgs.ociTools` provides utilities to create OCI Runtime bundles. ## buildContainer {#ssec-pkgs-ociTools-buildContainer} -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. +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. +The nix store of the container will contain all referenced dependencies of the given command. + +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. +Because of this, a container built with `buildContainer` will not work on Windows or other non-POSIX platforms without modifications to the container configuration. +These modifications aren't supported by `buildContainer`. + +For `linux` platforms, `buildContainer` also configures the following namespaces (see {manpage}`unshare(1)`) to isolate the OCI container from the global namespace: +PID, network, mount, IPC, and UTS. + +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. + +### Inputs {#ssec-pkgs-ociTools-buildContainer-inputs} + +`buildContainer` expects an argument with the following attributes: + +`args` (List of String) + +: Specifies a set of arguments to run inside the container. + Any packages referenced by `args` will be made available inside the container. + +`mounts` (Attribute Set; _optional_) + +: Would specify additional mounts that the runtime must make available to the container. + + :::{.warning} + As explained in [issue #290879](https://github.com/NixOS/nixpkgs/issues/290879), this attribute is currently ignored. + ::: + + :::{.note} + `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. + ::: + + _Default value:_ `{}`. -The parameters of `buildContainer` with an example value are described below: +`readonly` (Boolean; _optional_) + +: If `true`, sets the container's root filesystem as read-only. + + _Default value:_ `false`. + +`os` **DEPRECATED** + +: Specifies the operating system on which the container filesystem is based on. + If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties). + 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`. + + _Default value:_ `"linux"`. + +`arch` **DEPRECATED** + +: Used to specify the architecture for which the binaries in the container filesystem have been compiled. + If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties). + 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`. + + _Default value:_ `x86_64`. + +### Examples {#ssec-pkgs-ociTools-buildContainer-examples} + +::: {.example #ex-ociTools-buildContainer-bash} +# Creating an OCI runtime container that runs `bash` + +This example uses `ociTools.buildContainer` to create a simple container that runs `bash`. ```nix -buildContainer { +{ ociTools, lib, bash }: +ociTools.buildContainer { args = [ - (with pkgs; - writeScript "run.sh" '' - #!${bash}/bin/bash - exec ${bash}/bin/bash - '').outPath + (lib.getExe bash) ]; - mounts = { - "/data" = { - type = "none"; - source = "/var/lib/mydata"; - options = [ "bind" ]; - }; - }; - readonly = false; } ``` -- `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. +As an example of how to run the container generated by this package, we'll use `runc` to start the container. +Any other tool that supports OCI containers could be used instead. -- `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) +```shell +$ nix-build +(some output removed for clarity) +/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join -- `readonly` makes the container's rootfs read-only if it is set to true. The default value is false `false`. +$ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join +$ nix-shell -p runc +[nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example +help +GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu) +(some output removed for clarity) +``` +::: diff --git a/doc/manpage-urls.json b/doc/manpage-urls.json index 5739a59d9420..5111103244ba 100644 --- a/doc/manpage-urls.json +++ b/doc/manpage-urls.json @@ -318,5 +318,6 @@ "passwd(5)": "https://man.archlinux.org/man/passwd.5", "group(5)": "https://man.archlinux.org/man/group.5", "login.defs(5)": "https://man.archlinux.org/man/login.defs.5", + "unshare(1)": "https://man.archlinux.org/man/unshare.1.en", "nix-shell(1)": "https://nixos.org/manual/nix/stable/command-ref/nix-shell.html" } -- cgit v1.2.3