AGPL

Armored

Levenshtein

OpenPGP

Starlark

Subcommands

ZSTD

armor

armored

basename

esm

fips

http

https

jsonwall

optimize

subcommand

subcommands

symlink

ubuntu

yaml

"discourse": "https://discourse.ubuntu.com/tags/c/rocks/117/chisel",

This section of the documentation covers the core concepts of Chisel.

(chisel_mo_explanation)=

The purpose of Chisel is to create a minimal Ubuntu root file system comprising

only the application and its runtime dependencies. Chisel is especially useful

for developers who are looking to create minimal and distroless-like container

images.

Chisel uses the {{cut_cmd}} to _slice_ Ubuntu packages, as depicted in the workflow below:

<table style="width: 100%;">

<colgroup>

<col style="width: 45%;">

<col style="width: 55%;">

</colgroup>

<tr>

<td>

:align: center

:alt: Read and parse chisel-releases

</td>

<td>

Chisel fetches, reads and validates the {ref}`chisel-release<chisel-releases_ref>`.

This includes parsing the {ref}`chisel_yaml_ref` and {ref}`slice

definitions<slice_definitions_ref>` while validating the release and checking for conflicting paths across packages.

</td>

</tr>

<tr>

<td>

:align: center

:alt: Talk to archives and fetch packages

</td>

<td>

Chisel talks to the {ref}`chisel_yaml_format_spec_archives` directly.

It fetches, validates and parses their `InRelease` files.

It then resolves which archive holds the **requested** packages and fetches

the corresponding package tarballs.

</td>

</tr>

<tr>

<td>

:align: center

:alt: Install package slices

</td>

<td>

Chisel groups and merges all slice definitions per package. Then,

for every package, it extracts the **specified slices' paths** into

the provided root file system.

</td>

</tr>

<tr>

<td>

:align: center

:alt: Run mutation scripts

</td>

<td>

Chisel then runs the {{mutation_scripts}}. Only the

{ref}`mutable<slice_definitions_format_slices_contents_mutable>` files may be

modified at this stage. Finally, the files specified with

{ref}`until:mutate<slice_definitions_format_slices_contents_until>` are

removed from the provided root file system.

</td>

</tr>

</table>

(slices_explanation)=

Since Debian packages are simply archives that can be inspected, navigated and

deconstructed, it is possible to define slices of packages that contain

minimal, complementary, loosely-coupled sets of files based on package metadata

and content. Such **package slices** are subsets of Debian packages, with their

own content and set of dependencies to other internal and external slices.

The use of package slices provides the ability to build minimal root file

system from the wider set of Ubuntu packages.

:align: center

:width: 75%

:alt: Debian package slices with dependencies

This image illustrates the simple case where, at a package level, package _B_

depends on package _A_. However, there might be files in _A_ that _B_ doesn't

actually need, but which are provided for convenience or completeness. By

identifying the files in _A_ that are actually needed by _B_, we can divide _A_

into slices that serve this purpose. In this example, the files in the package

slice, _A_slice3_, are not needed for _B_ to function. To make package _B_

usable in the same way, it can also be divided into slices.

With these slice definitions in place, Chisel is able to extract a

highly-customised and specialised slice of the Ubuntu distribution, which one

could see as a block of stone from which we can carve and extract only the

small and relevant parts that we need to run our applications, thus keeping the

file system small and less exposed to vulnerabilities.

A package's slices can be defined via a YAML slice definitions file. Check

{ref}`slice_definitions_ref` for more information about this file's format.

In Chisel, slices are recognized by the following pattern:

`<package_name>_<slice_name>`.

For example, the slice `libc6_libs` refers to the slice definition `libs` of the

package `libc6`.

The use of an underscore in this pattern is what distinguishes package names from

slice names, as this character is not allowed in Debian package names.