github.com/opencontainers/umoci@v0.4.8-0.20240508124516-656e4836fb0d/doc/site/quick-start/workflow.md (about)

     1  +++
     2  title = "Workflow"
     3  weight = 20
     4  +++
     5  
     6  umoci's workflow is based around an unpack-repack cycle, with some separate
     7  configuration steps. Most users are going to be primarily using the unpack and
     8  repack subcommands for most uses of umoci.
     9  
    10  ### Unpack ###
    11  
    12  Each image consists of a set of layers and a configuration that describes how
    13  the image should be used. `umoci unpack` allows you to take an image and
    14  extract its root filesystem and configuration into an [runtime
    15  bundle][oci-runtime]. This bundle can be used by an OCI compliant container
    16  runtime to spawn a container, but also can be used directly by non-containers
    17  (as it is just a directory).
    18  
    19  [oci-runtime]: https://github.com/opencontainers/runtime-spec
    20  
    21  ```text
    22  % sudo umoci unpack --image opensuse:42.2 bundle
    23  % ls -l bundle
    24  total 720
    25  -rw-r--r-- 1 root root   3247 Jul  3 17:58 config.json
    26  drwxr-xr-x 1 root root    128 Jan  1  1970 rootfs
    27  -rw-r--r-- 1 root root 725320 Jul  3 17:58 sha256_8eac95fae2d9d0144607ffde0248b2eb46556318dcce7a9e4cc92edcd2100b67.mtree
    28  -rw-r--r-- 1 root root    270 Jul  3 17:58 umoci.json
    29  % cat bundle/rootfs/etc/os-release
    30  NAME="openSUSE Leap"
    31  VERSION="42.2"
    32  ID=opensuse
    33  ID_LIKE="suse"
    34  VERSION_ID="42.2"
    35  PRETTY_NAME="openSUSE Leap 42.2"
    36  ANSI_COLOR="0;32"
    37  CPE_NAME="cpe:/o:opensuse:leap:42.2"
    38  BUG_REPORT_URL="https://bugs.opensuse.org"
    39  HOME_URL="https://www.opensuse.org/"
    40  ```
    41  
    42  You can spawn new containers with [runc][runc]. If you make any changes to
    43  the root filesystem, you can create a new delta layer and add it to the image
    44  by [repacking it](#repack).
    45  
    46  [runc]: https://github.com/opencontainers/runc
    47  
    48  ```text
    49  % sudo runc run -b bundle ctr-name
    50  sh-4.3# grep NAME /etc/os-release
    51  NAME="openSUSE Leap"
    52  sh-4.3# uname -n
    53  mrsdalloway
    54  ```
    55  
    56  ### Repack ###
    57  
    58  After making some changes to the root filesystem of your extracted image, you
    59  may want to create a new delta layer from the changes. Note that the way you
    60  modified the image does not matter, you can create a container using the
    61  extracted root filesystem or just modify it directly.
    62  
    63  `umoci repack` will create a derived image based on the image originally
    64  extracted to create the runtime bundle. Even if the original image
    65  has been "modified", `umoci repack` will still use the original. Note that in
    66  this invocation, `--image` refers to the new tag that will be used to reference
    67  the modified image (which may be the same tag used to extract the original
    68  image). `umoci repack` does not work across different images -- both the source
    69  and destination must be in the same image (and the original blobs must not have
    70  been garbage collected).
    71  
    72  ```text
    73  % echo "some change" > bundle/rootfs/my_change
    74  % sudo umoci repack --image opensuse:new bundle
    75  % sudo umoci unpack --image opensuse:new bundle2
    76  % cat bundle2/rootfs/my_change
    77  some change
    78  ```
    79  
    80  Note that any changes to `bundle/config.json` **will not** change the image's
    81  configuration. You can change an image's configuration using [the dedicated
    82  subcommand](#configuration).
    83  
    84  ### Configuration ###
    85  
    86  In order to change the configuration of an image, `umoci config` can be used. A
    87  full description of what each configuration option means is beyond the scope of
    88  this document, but you can [read the spec for more
    89  information][image-spec-config].
    90  
    91  By default, `umoci config` will override the tag given with `--image` but you
    92  can force the change to create a new tag (leaving the original unchanged) with
    93  `--tag`.
    94  
    95  ```text
    96  % umoci config --author="Aleksa Sarai <asarai@suse.de>" --image opensuse
    97  ```
    98  
    99  Note that both `umoci config` and `umoci repack` include entries in the history
   100  of the image. You can change what the history entry contains for a particular
   101  operation by using the `--history.` set of flags (for both `umoci repack` and
   102  `umoci config`).
   103  
   104  [image-spec-config]: https://github.com/opencontainers/image-spec/blob/v1.0.0-rc4/config.md