linuxkit/docs/external-disk.md

External Disk

linuxkit run has the ability to mount an external disk when booting. It involves two steps:

1. Make the disk available as a device
2. Mount the disk

Make Disk Available

In order to make the disk available, you need to tell linuxkit where the disk file or block device is.

All local linuxkit run methods (currently hyperkit, qemu, virtualization.framework and vmware) take a -disk argument:

• -disk path,size=100M,format=qcow2. For size the default is in GB but an M can be appended to specify sizes in MB. The format can be omitted for the platform default, and is only useful on qemu at present.

If a path is specified linuxkit will use the disk at location path. If you do not provide -disk path, linuxkit assumes a default path, which is prefix-state/disk.img.

If the disk at the specified or default path does not exist, linuxkit will create one of size size.

The -disk specification may be repeated for multiple disks, although a limited number may be supported, and some platforms currently only support a single disk.

TODO: GCP

Format the disk

pkg/format creates a partition table and format drives for use with LinuxKit

Example Usage

This packages supports two modes of use:

onboot:
  - name: format
    image: linuxkit/format:<hash>

In this mode of operation, the first disk found that does not have a valid partition table will have one linux partition created that fills the entire disk

Options

onboot:
  - name: format
    image: linuxkit/format:<hash>
    command: ["/usr/bin/format", "-type", "ext4", "-label", "DATA", "/dev/vda"]

onboot:
  - name: format
    image: linuxkit/format:<hash>
    command: ["/usr/bin/format", "-force", "-type", "xfs", "-label", "DATA", "-verbose", "/dev/vda"]

onboot:
  - name: format
    image: linuxkit/format:<hash>
    command: ["/usr/bin/format", "-type", "ext4", "-partition", "gpt", "/dev/vda"]

• -force can be used to force the partition to be cleared and recreated (if applicable), and the recreated partition formatted. This option would be used to re-init the partition on every boot, rather than persisting the partition between boots.
• -label can be used to give the disk a label
• -type can be used to specify the type. This is ext4 by default but btrfs and xfs are also supported
• -partition can be used to specify the partition table type. This is dos by default but gpt is also supported
• -verbose enables verbose logging, which can be used to troubleshoot device auto-detection and (re-)partitioning
• The final (optional) argument specifies the device name

Mount the disk

Once a disk has been prepared it will need to be mounted using pkg/mount

Usage

NOTE: Block devices may only be mounted in /var unless you have explicitly added an additional bind mount

If no additional arguments are provided the first unmounted linux partition on the first block device is mounted to the mountpoint provided.

onboot:
  - name: mount
    image: linuxkit/mount:<hash>
    command: ["/usr/bin/mountie", "/var/lib/docker"]

Options

You can provide either a partition label, device name or disk UUID to specify which disk should be used. For example:

onboot:
  - name: mount
    image: linuxkit/mount:<hash>
    command: ["/usr/bin/mountie", "-label", "DATA", "/var/lib/docker" ]

onboot:
  - name: mount
    image: linuxkit/mount:<hash>
    command: ["/usr/bin/mountie", "-uuid", "a-proper-uuid", "/var/lib/docker" ]

onboot:
  - name: mount
    image: linuxkit/mount:<hash>
    command: ["/usr/bin/mountie", "-device", "/dev/sda1", "/var/lib/docker" ]

For compatibility with the standard mount command we also support providing the device name as a positional argument. E.g

onboot:
  - name: mount
    image: linuxkit/mount:<hash>
    command: ["/usr/bin/mountie", "/dev/sda1", "/var/lib/docker" ]

Extending Partitions

pkg/extend can extends a single partition to fill the entire disk

Usage

In the default mode of operation, any disks that are found and have a single partition and free space will have that partition extended.

onboot:
  - name: extend
    image: linuxkit/extend:<hash>

Options

-type can be used to specify the type. The default is ext4 but btrfs and xfs are also supported. If you know the name of the disk that you wish to extend you may supply this as an argument

onboot:
  - name: extend
    image: linuxkit/extend:<hash>
    command: ["/usr/bin/extend", "-type", "btrfs", "/dev/vda"]