From 0eb4a49b244b3f923b455885f80a210fd1741368 Mon Sep 17 00:00:00 2001 From: Justin Cormack Date: Thu, 8 Jun 2017 14:58:29 +0100 Subject: [PATCH] Import yaml documentation from LinuxKit Signed-off-by: Justin Cormack --- docs/yaml.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 docs/yaml.md diff --git a/docs/yaml.md b/docs/yaml.md new file mode 100644 index 000000000..3291a4927 --- /dev/null +++ b/docs/yaml.md @@ -0,0 +1,123 @@ +# Configuration Reference + +The yaml configuration specifies the components and the build time artifacts. All components +are downloaded at build time to create an image. The image is self-contained and immutable, +so it can be tested reliably for continuous delivery. + +The configuration file is processed in the order `kernel`, `init`, `onboot`, `services`, `files`. +Each section adds file to the root file system + +## `kernel` + +The `kernel` section defines the kernel configuration. The `image` field specifies the Docker image, +which should contain a `bzImage` (for `amd64` architecture, others may vary) and a file +called `kernel.tar` which is a tarball that is unpacked into the root, which should usually +contain a kernel modules directory. See [`kernel/`](../kernel/) for source code. `cmdline` +specifies the kernel command line options if required. + +## `init` + +The `init` section is a list of images that are used for the `init` system and are unpacked directly +into the root filesystem. This should bring up `containerd`, start the system and daemon containers, +and set up basic filesystem mounts. See [`pkg/init/`](../pkg/init/) for source code. For ease of +modification `runc` and `containerd` images, which just contain these programs are added here +rather than bundled into the `init` container. + +## `onboot` + +The `onboot` section is a list of images. These images are run before any other +images. They are run sequentially and each must exit before the next one is run. +These images can be used to configure one shot settings. See [Image +specification](#image-specification) for a list of supported fields. + +## `services` + +The `services` section is a list of images for long running services which are +run with `containerd`. Startup order is undefined, so containers should wait +on any resources, such as networking, that they need. See [Image +specification](#image-specification) for a list of supported fields. + +## `trust` + +The `trust` section specifies which build components are to be cryptographically verified with +[Docker Content Trust](https://docs.docker.com/engine/security/trust/content_trust/) prior to pulling. +Trust is a central concern in any build system, and LinuxKit's is no exception: Docker Content Trust provides authenticity, +integrity, and freshness guarantees for the components it verifies. The LinuxKit maintainers are responsible for signing +`mobylinux` components, though collaborators can sign their own images with Docker Content Trust or [Notary](https://github.com/docker/notary). + +- `image` lists which individual images to enforce pulling with Docker Content Trust. +The image name may include tag or digest, but the matching also succeeds if the base image name is the same. +- `org` lists which organizations for which Docker Content Trust is to be enforced across all images (ex: `mobylinux` is the org for `mobylinux/kernel`) + +## Image specification + +Entries in the `onboot` and `services` sections specify an OCI image and +options. Default values may be specified using the `org.mobyproject.config` image label. +For more details see the [OCI specification](https://github.com/opencontainers/runtime-spec/blob/master/spec.md). + +- `name` a unique name for the program being executed, used as the `containerd` id. +- `image` the Docker image to use for the root filesystem. The default command, path and environment are + extracted from this so they need not be filled in. +- `capabilities` the Linux capabilities required, for example `CAP_SYS_ADMIN`. If there is a single + capability `all` then all capabilities are added. +- `mounts` is the full form for specifying a mount, which requires `type`, `source`, `destination` + and a list of `options`. If any fields are omitted, sensible defaults are used if possible, for example + if the `type` is `dev` it is assumed you want to mount at `/dev`. The default mounts and their options + can be replaced by specifying a mount with new options here at the same mount point. +- `binds` is a simpler interface to specify bind mounts, accepting a string like `/src:/dest:opt1,opt2` + similar to the `-v` option for bind mounts in Docker. +- `tmpfs` is a simpler interface to mount a `tmpfs`, like `--tmpfs` in Docker, taking `/dest:opt1,opt2`. +- `command` will override the command and entrypoint in the image with a new list of commands. +- `env` will override the environment in the image with a new environment list +- `cwd` will set the working directory, defaults to `/`. +- `net` sets the network namespace, either to a path, or if `host` is specified it will use the host namespace. +- `pid` sets the pid namespace, either to a path, or if `host` is specified it will use the host namespace. +- `ipc` sets the ipc namespace, either to a path, or if `host` is specified it will use the host namespace. +- `uts` sets the uts namespace, either to a path, or if `host` is specified it will use the host namespace. +- `readonly` sets the root filesystem to read only, and changes the other default filesystems to read only. +- `maskedPaths` sets paths which should be hidden. +- `readonlyPaths` sets paths to read only. +- `uid` sets the user id of the process. Only numbers are accepted. +- `gid` sets the group id of the process. Only numbers are accepted. +- `additionalGids` sets additional groups for the process. A list of numbers is accepted. +- `noNewPrivileges` is `true` means no additional capabilities can be acquired and `suid` binaries do not work. +- `hostname` sets the hostname inside the image. +- `oomScoreAdj` changes the OOM score. +- `disableOOMKiller` disables the OOM killer for the service. +- `rootfsPropagation` sets the rootfs propagation, eg `shared`, `slave` or (default) `private`. +- `cgroupsPath` sets the path for cgroups. +- `sysctl` sets a list of `sysctl` key value pairs that are set inside the container namespace. + +Further OCI values will be added, as the list is not yet complete. + +### Mount Options +When mounting filesystem paths into a container - whether as part of `onboot` or `services` - there are several options of which you need to be aware. Using them properly is necessary for your containers to function properly. + +For most containers - e.g. nginx or even docker - these options are not needed. Simply doing the following will work fine: + +```yml +binds: + - /var:/some/var/path +``` + +However, in some circumstances you will need additional options. These options are used primarily if you intend to make changes to mount points _from within your container_ that should be visible from outside the container, e.g., if you intend to mount an external disk from inside the container but have it be visible outside. + +In order for new mounts from within a container to be propagated, you must set the following on the container: + +1. `rootfsPropagation: shared` +2. The mount point into the container below which new mounts are to occur must be `rshared,rbind`. In practice, this is `/var` (or some subdir of `/var`), since that is the only true read-write area of the filesystem where you will mount things. + +Thus, if you have a regular container that is only reading and writing, go ahead and do: + +```yml +binds: + - /var:/some/var/path +``` + +On the other hand, if you have a container that will make new mounts that you wish to be visible outside the container, do: + +```yml +binds: + - /var:/var:rshared,rbind +rootfsPropagation: shared +```