add support for volumes

Signed-off-by: Avi Deitcher <avi@deitcher.net>

docs/yaml.md

@@ -3,7 +3,7 @@
 The `linuxkit build` command assembles a set of containerised components into in image. The simplest
 type of image is just a `tar` file of the contents (useful for debugging) but more useful
 outputs add a `Dockerfile` to build a container, or build a full disk image that can be
-booted as a linuxKit VM. The main use case is to build an assembly that includes
+booted as a linuxkit VM. The main use case is to build an assembly that includes
 `containerd` to run a set of containers, but the tooling is very generic.
 
 The yaml configuration specifies the components used to build up an image . All components
@@ -16,8 +16,10 @@ The Docker images are optionally verified with Docker Content Trust.
 For private registries or private repositories on a registry credentials provided via
 `docker login` are re-used.
 
+## Sections
+
 The configuration file is processed in the order `kernel`, `init`, `onboot`, `onshutdown`,
-`services`, `files`. Each section adds files to the root file system. Sections may be omitted.
+`services`, `files`, `volumes`. Each section adds files to the root file system. Sections may be omitted.
 
 Each container that is specified is allocated a unique `uid` and `gid` that it may use if it
 wishes to run as an isolated user (or user namespace). Anywhere you specify a `uid` or `gid`
@@ -40,7 +42,7 @@ files:
     mode: "0600"
 ```
 
-## `kernel`
+### `kernel`
 
 The `kernel` section is only required if booting a VM. The files will be put into the `boot/`
 directory, where they are used to build bootable images.
@@ -57,7 +59,7 @@ Kernel packages may also contain a cpio archive containing CPU microcode which n
 the initrd. To select this option, recommended when booting on bare metal, add `ucode: intel-ucode.cpio`
 to the kernel section.
 
-## `init`
+### `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,
@@ -65,14 +67,14 @@ and set up basic filesystem mounts. in the case of a LinuxKit system. For ease o
 modification `runc` and `containerd` images, which just contain these programs are added here
 rather than bundled into the `init` container.
 
-## `onboot`
+### `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.
 
-## `onshutdown`
+### `onshutdown`
 
 This is a list of images to run on a clean shutdown. Note that you must not rely on these
 being run at all, as machines may be be powered off or shut down without having time to run
@@ -81,18 +83,67 @@ run and when they are not. Most systems are likely to be "crash only" and not ha
 but you can attempt to deregister cleanly from a network service here, rather than relying
 on timeouts, for example.
 
-## `services`
+### `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.
 
-## `files`
+### `volumes`
+
+The volumes section is a list of named volumes that can be used by other containers,
+including those in `services`, `onboot` and `onshutdown`. The volumes are created in a directory
+chosen by linuxkit at build-time. The volumes then can be referenced by other containers and
+mounted into them.
+
+Volumes normally are blank directories. If an image is provided, the contents of that image
+will be used to populate the volume.
+
+The `volumes` section can declare a volume to be read-write or read-only. If the volume is read-write,
+a volume that is mounted into a container can be mounted read-only or read-write. If the volume is read-only,
+it can be mounted into a container read-only; attempting to do so read-write will generate a build-time error.
+By default, volumes are created read-write, and are mounted read-write.
+
+Volume names **must** be unique, and must contain only lower-case alphanumeric characters, hyphens, and
+underscores.
+
+Sample `volumes` section:
+
+```yml
+volumes:
+- name: vola
+  image: alpine:latest
+  readonly: true
+- name: volb
+  image: alpine:latest
+  readonly: false
+- name: volc
+  readonly: false
+```
+
+In the above example:
+
+* `vola` is populated by the contents of `alpine:latest` and is read-only.
+* `volb` is populated by the contents of `alpine:latest` and is read-write.
+* `volc` is an empty volume and is read-write.
+
+Sample usage of volumes in `services` section:
+
+```yml
+services:
+- name: myservice
+  image: alpine:latest
+  binds:
+  - volA:/mnt/volA:ro
+  - volB:/mnt/volB
+```
+
+### `files`
 
 The files section can be used to add files inline in the config, or from an external file.
 
-```
+```yml
 files:
   - path: dir
     directory: true
@@ -118,7 +169,8 @@ user's home directory.
 In addition there is a `metadata` option that will generate the file. Currently the only value
 supported here is `"yaml"` which will output the yaml used to generate the image into the specified
 file:
-```
+
+```yml
   - path: etc/linuxkit.yml
     metadata: yaml
 ```
@@ -130,7 +182,7 @@ Because a `tmpfs` is mounted onto `/var`, `/run`, and `/tmp` by default, the `tm
 
 ## Image specification
 
-Entries in the `onboot` and `services` sections specify an OCI image and
+Entries in the `onboot`, `onshutdown`, `volumes` 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).
 
@@ -205,7 +257,8 @@ which specifies some actions to take place when the container is being started.
 - `namespace` overrides the LinuxKit default containerd namespace to put the container in; only applicable to services.
 
 An example of using the `runtime` config to configure a network namespace with `wireguard` and then run `nginx` in that namespace is shown below:
-```
+
+```yml
 onboot:
   - name: dhcpcd
     image: linuxkit/dhcpcd:<hash>