plugins/cdi/nbdkit-cdi-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-cdi-plugin - export a layer from a container image
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit cdi [name=]NAME[:TAG|@DIGEST] [layer=N]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-cdi-plugin> (Containerized Data Importer plugin) is a plugin
  12 for L<nbdkit(1)> which downloads a container image using
  13 L<podman-pull(1)> and makes a single layer available over NBD.  The
  14 plugin is essentially a convenient wrapper around L<podman(1)> and
  15 L<jq(1)> and requires both tools to be installed.
  16
  17 =head1 EXAMPLES
  18
  19 Given a Containerized Data Importer (CDI) registry image containing a
  20 VM disk, you can export the whole layer using:
  21
  22  $ nbdkit cdi docker://kubevirt/fedora-cloud-container-disk-demo
  23
  24 The layer exported over NBD is a tar file:
  25
  26  $ nbdcopy nbd://localhost - | file -
  27  -: POSIX tar archive
  28
  29 To export only the VM disk image in this layer, combine this plugin
  30 with L<nbdkit-tar-filter(1)>.  In this example when you run L<file(1)>
  31 on the tar entry within the layer it shows that it is a QCOW2 file:
  32
  33  $ nbdkit cdi docker://kubevirt/fedora-cloud-container-disk-demo \
  34          --filter=tar tar-entry=./disk/downloaded \
  35          --run 'nbdcopy "$uri" - | file -'
  36  -: QEMU QCOW2 Image (v2), 4294967296 bytes
  37
  38 =head1 PARAMETERS
  39
  40 =over 4
  41
  42 =item [B<name=>]NAME[:TAG|@DIGEST]
  43
  44 The name or URI of the container image.  This is passed to
  45 L<podman-pull(1)>.
  46
  47 C<name=> is a magic config key and may be omitted in most cases.
  48 See L<nbdkit(1)/Magic parameters>.
  49
  50 =item B<layer=>N
  51
  52 Export the N'th layer (instead of layer 0).
  53
  54 =back
  55
  56 =head1 ENVIRONMENT VARIABLES
  57
  58 =over 4
  59
  60 =item C<TMPDIR>
  61
  62 A temporary copy of the layer is created in C<TMPDIR>.  If this
  63 environment variable is not set then F</var/tmp> is used instead.
  64
  65 =back
  66
  67 =head1 FILES
  68
  69 =over 4
  70
  71 =item F<$plugindir/nbdkit-cdi-plugin.so>
  72
  73 The plugin.
  74
  75 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
  76
  77 =back
  78
  79 =head1 VERSION
  80
  81 C<nbdkit-cdi-plugin> first appeared in nbdkit 1.22.
  82
  83 =head1 SEE ALSO
  84
  85 L<nbdkit(1)>,
  86 L<nbdkit-plugin(3)>,
  87 L<nbdkit-tar-filter(1)>,
  88 L<podman(1)>,
  89 L<podman-pull(1)>,
  90 L<jq(1)>,
  91 L<https://github.com/kubevirt/containerized-data-importer/blob/master/doc/image-from-registry.md>.
  92
  93 =head1 AUTHORS
  94
  95 Richard W.M. Jones
  96
  97 =head1 COPYRIGHT
  98
  99 Copyright Red Hat