imagecraft.yaml¶
This reference describes the purpose, usage, and examples of all available keys in
an image’s project file, imagecraft.yaml.
Top-level keys¶
An Imagecraft project’s top-level keys declare the image’s descriptors and the essential details of how it builds.
Top-level descriptors include the image’s name, version, description, and license, alongside operational values such as its supported architectures and build environment.
name¶
Type
str
Description
The name of the project. This is used when uploading, publishing, or installing.
The project name must consist only of lower-case ASCII letters (a-z), numerals
(0-9), and hyphens (-). It must contain at least one letter, not start or end
with a hyphen, and not contain two consecutive hyphens. The maximum length is 40
characters.
Examples
name: ubuntu
name: jupyterlab-desktop
name: lxd
name: digikam
name: kafka
name: mysql-router-k8s
title¶
Type
str
Description
A human-readable title.
Examples
title: Ubuntu Linux
title: Jupyter Lab Desktop
title: LXD
title: DigiKam
title: Apache Kafka
title: MySQL Router K8s charm
version¶
Type
str
Description
The version of the project, enclosed in quotation marks.
Examples
version: '0.1'
version: 1.0.0
version: v1.0.0
version: '24.04'
license¶
Type
str
summary¶
Type
str
Description
A short description of the project.
Examples
summary: Linux for Human Beings
summary: The cross-platform desktop application for JupyterLab
summary: Container and VM manager
summary: Photo Management Program
summary: Charm for routing MySQL databases in Kubernetes
summary: An open-source event streaming platform for high-performance data pipelines
description¶
Type
str
base¶
Type
One of: ['bare']
Description
The base layer the image is built on.
The value bare denotes that the project will start with an empty directory and,
if overlays are used, an empty base layer.
Examples
base: bare
build-base¶
Type
One of: ['ubuntu@20.04', 'ubuntu@22.04', 'ubuntu@24.04']
Description
The build base determines the image’s build environment. This system and version will be used when assembling the image’s contents, but will not be included in the final image.
Values
Value |
Description |
|---|---|
|
The Ubuntu 20.04 build environment. |
|
The Ubuntu 22.04 build environment. |
|
The Ubuntu 24.04 build environment. |
Examples
build-base: [email protected]
build-base: [email protected]
platforms¶
Type
dict[str, Platform]
parts¶
Type
dict[str, Part]
volumes¶
Type
dict[str, Volume]
Description
The structure and properties of the image.
This key expects a single entry defining the image’s schema and partitions.
Examples
volumes:
pc:
schema: gpt
structure:
- name: efi
type: C12A7328-F81F-11D2-BA4B-00A0C93EC93B
filesystem: vfat
role: system-boot
filesystem-label: UEFI
size: 256M
- name: rootfs
type: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
filesystem: ext4
filesystem-label: writable
role: system-data
size: 5G
filesystems¶
Type
dict[str, FilesystemMount]
Description
The mapping of the image’s partitions to mount points.
This mapping can only contain a single filesystem, named default. The first
entry of default must map a partition to the / mount point.
Examples
filesystems:
default:
- mount: /
device: (volume/pc/rootfs)
- mount: /boot/efi
device: (volume/pc/efi)
Part keys¶
The parts key and its values declare the image’s parts
and detail how they’re built.
parts.<part-name>.plugin¶
Type
str
Description
The plugin to build the part with.
During the build step, the plugin prepares the part’s files with the build system of its language or framework.
Examples
plugin: python
plugin: dump
parts.<part-name>.after¶
Type
list[str]
Description
The parts to process before starting this part’s build.
During the build step, this part waits for all of the listed parts to reach the stage step before it begins building.
The purpose of this key is to stagger the part processing order so that interrelated parts can provide data to each other.
When this key is set, the part queue follows modified rules during the lifecycle:
Parts are processed alphabetically by name.
When the build reaches a part that another depends on, the dependent part will only start its build and stage steps after the initial part finishes its stage step.
After the string of dependent parts completes their lifecycles, the queue continues to the next part in alphabetical order.
Examples
after:
- build-deps
- daemon
parts.<part-name>.disable-parallel¶
Type
bool
Description
Whether to disable CPU multithreading during the build step.
If unset, the build defaults to multithreading.
Examples
disable-parallel: true
parts.<part-name>.source¶
Type
str
Description
The location of the source files for the part.
During the pull step, these files are placed in the part’s build environment.
Enter either an HTTP/HTTPS URL or the path to the local project directory.
Examples
source: .
source: https://github.com/canonical/dqlite
parts.<part-name>.source-type¶
Type
str
Description
The format of the part’s source.
During the pull step, the part expects the source to behave like the specified format.
If unset, the part attempts to auto-detect the format.
Supported formats include container types like .tar files and Debian packages,
version-controlled directories like Git repositories, and local files.
Values
Value |
Description |
|---|---|
|
Debian package |
|
Git repository |
|
Red Hat package |
|
Snap container format |
|
Tarball archive |
|
ZIP file |
|
Local directory or file in the project directory |
|
A “plain” file retrieved from the internet |
Examples
source-type: git
source-type: local
parts.<part-name>.source-checksum¶
Type
str
Description
The checksum of the downloaded source, to ensure integrity.
During the pull step, the part compares the checksum against that of the downloaded files.
Checksums can be generated with any of the hashing algorithms supported by Python’s hashlib.
Examples
source-checksum: sha256/1451d01ee3a21100340aed867d0b799f46f0b1749680028d38c3f5d0128fb8a7
parts.<part-name>.source-branch¶
Type
str
Description
If the source is a Git repository, this key specifies the target branch.
During the pull step, the part fetches the repository from the earliest available commit up to the tip of this branch.
The commit history can be truncated by specifying a source-depth.
This key is mutually incompatible with source-commit and source-tag.
Examples
source-branch: main
source-branch: hotfix/2.10
parts.<part-name>.source-tag¶
Type
str
Description
If the source is a Git repository, this key specifies the target tag.
During the pull step, the part fetches the repository from the earliest available commit up to the commit with this tag.
The commit history can be truncated by specifying a source-depth.
This key is mutually incompatible with source-branch and source-commit.
Examples
source-tag: 1.0.1
parts.<part-name>.source-commit¶
Type
str
Description
If the source is a Git repository, this key specifies the target commit. Both short and long SHA hashes are supported.
During the pull step, the part fetches the repository from the earliest available commit up to this commit.
The commit history can be truncated by specifying a source-depth.
This key is mutually incompatible with source-branch and source-tag.
Examples
source-commit: 36086af03fc4941a8ac219648ce77401743f3ae0
parts.<part-name>.source-depth¶
Type
int
Description
If the source is a Git repository, this key specifies how far back in the commit history to fetch.
During the pull step, the part fetches the repository from the specified commit up to the target commit, the target tag, or the tip of the target branch.
Equivalent to the
--depth
parameter of git fetch.
If unset, the part fetches the full repository history up to the target commit, the target tag, or the tip of the target branch.
Examples
source-depth: 1
parts.<part-name>.source-submodules¶
Type
list[str]
Description
If the source is a Git repository, this key specifies the registered Git submodules that the project also needs.
During the pull step, the part fetches these submodules.
Equivalent to the
--recurse-submodules
parameter of git clone.
If unset, the part will fetch all of the repository’s submodules.
Examples
source-submodules:
- third_party/googletest
- third_party/jsoncpp
source-submodules:
- libbpf
parts.<part-name>.source-subdir¶
Type
str
Description
The subdirectory of the unpacked source where the build will occur.
During the pull step, the build will be restricted to the specified path.
If unset, the build can access the entire file tree of the source.
Examples
source-subdir: src
source-subdir: demo_nodes_cpp
parts.<part-name>.override-pull¶
Type
str
Description
The commands to run instead of the default behavior of the pull step.
The standard pull step actions can be performed by calling craftctl default.
Examples
override-pull: |
craftctl default
rm $CRAFT_PART_SRC/pyproject.toml
parts.<part-name>.overlay¶
Type
list[str]
Description
The files to copy from the part’s overly filesystem to the stage directory.
Examples
overlay:
- bin
- usr/bin
overlay:
- -etc/cloud/cloud.cfg.d/90_dpkg.cfg
parts.<part-name>.overlay-packages¶
Type
list[str]
Description
The packages to install in the part’s overlay filesystem.
During the overlay step, these packages are installed into the part’s overlay filesystem using the base layer’s package manager.
Examples
overlay-packages:
- ed
parts.<part-name>.overlay-script¶
Type
str
Description
The commands to run after the part’s overlay packages are installed.
If unset, the part’s overlay filesystem will only contain the packages specified
in overlay-packages.
Examples
overlay-script: |
rm -f ${CRAFT_OVERLAY}/usr/bin/vi ${CRAFT_OVERLAY}/usr/bin/vim*
rm -f ${CRAFT_OVERLAY}/usr/bin/emacs*
rm -f ${CRAFT_OVERLAY}/bin/nano
parts.<part-name>.build-environment¶
Type
list[dict[str, str]]
Description
The environment variables to define for the build step, as key-value pairs.
Examples
build-environment:
- MESSAGE: Hello world!
- NAME: Craft Parts
parts.<part-name>.build-packages¶
Type
list[str]
Description
The packages to install during the build step, before the build starts. The part installs them into the build environment using the host’s native package manager.
Build packages must be listed by their name on the host system.
Examples
build-packages:
- git
- libffi-dev
- libssl-dev
parts.<part-name>.build-snaps¶
Type
list[str]
Description
The snaps to install during the build step, before the build starts. The part makes them available in the build environment.
Entries can be listed in one of three formats.
<snap-name><snap-name>/<channel-name><snap-name>/<channel-name>/<version-name>
If no version or channel is provided, latest/stable is used.
Examples
build-snaps:
- go/latest/stable
- node/stable
parts.<part-name>.organize¶
Type
dict[str, str]
Description
A map of files from the build directory to their destinations in the stage directory.
Each pair of source and destination paths is represented as a nested key of the form
<source-path>: <destination-path>.
At the end of the build step, the files at the source paths are copied to their destination paths in the stage directory.
Files from the build environment can be organized into specific partitions by prepending the destination path with the partition name, enclosed in parentheses. Source paths always reference the default partition.
Examples
organize:
hello.py: bin/hello
organize:
vmlinuz-6.2.0-39-generic: (boot)/vmlinuz
parts.<part-name>.override-build¶
Type
str
Description
The commands to run instead of the default behavior of the build step.
The standard build step actions can be performed by calling craftctl default.
Examples
override-build: |
cd cmd/webhook
mkdir $CRAFT_PART_INSTALL/ko-app
go build -o $CRAFT_PART_INSTALL/ko-app/webhook -a .
parts.<part-name>.stage¶
Type
list[str]
Description
During the stage step, any specified files are copied from the build directory to the stage directory.
Paths support wildcards (*) and must be relative to the working directory where
they will be used.
Examples
stage:
- usr/bin/*
- usr/share
stage:
- -usr
- zfsutils-linux
parts.<part-name>.stage-packages¶
Type
list[str]
Description
During the stage step, these packages are included in the stage environment alongside the build artifacts.
Chisel slices can be listed using the <package-name>_<slice-name> syntax.
Listing both packages and slices in the same stage-packages key is not
currently supported.
Examples
stage-packages:
- curl
- libxml2
parts.<part-name>.stage-snaps¶
Type
list[str]
Description
During the stage step, these snaps are included in the stage environment.
Entries can be in one of three formats:
<snap-name><snap-name>/<channel-name><snap-name>/<channel-name>/<version-name>
If an entry contains no version or channel, latest/stable is used.
Examples
stage-snaps:
- go/1.17
- chisel/latest/candidate
- mir-kiosk-x11
parts.<part-name>.override-stage¶
Type
str
Description
The commands to run instead of the default behavior of the stage step.
The standard stage step actions can be performed by calling craftctl default.
Examples
override-stage: |
craftctl default
chown -R 499 "${CRAFT_PART_INSTALL}/entrypoint.sh"
parts.<part-name>.prime¶
Type
list[str]
Description
During the prime step, any specified files are copied from the stage directory to the final payload.
Paths support wildcards (*) and must be relative to the working directory where
they will be used.
Examples
prime:
- usr/lib/*/qt6/plugins/tls/*
- -usr/share/thumbnailers
parts.<part-name>.override-prime¶
Type
str
Description
The commands to run instead of the default behavior of the prime step.
The standard prime step actions can be performed by calling craftctl default.
Examples
override-prime: |
craftctl default
mkdir -p $CRAFT_PRIME/var/lib/mysql
mkdir -p $CRAFT_PRIME/var/lib/mysqld
parts.<part-name>.permissions¶
Type
list[Permissions]
Description
The ownership and permission settings for a set of files in the part’s prime directory.
The files at path will be assigned an owner and a group, with the read,
write, and execute permissions of each being determined by the value of mode.
Examples
permissions:
- owner: 2000
group: 2000
- path: srv/indico/start-indico.sh
mode: '544'
- path: etc/
mode: '755'
parts.<part-name>.permissions.<permission>.path¶
Type
str
Description
The file path, relative to the prime directory, being assigned permissions.
Wildcards (*) are supported.
If unset, the permissions will be assigned to every file in the prime directory.
parts.<part-name>.permissions.<permission>.owner¶
Type
int
Description
The numeric user ID (UID) of the desired owner on the host system.
This entry is required if the permissions contain a group entry.
parts.<part-name>.permissions.<permission>.group¶
Type
int
Description
The numeric group ID (GID) of the desired owner group on the host system.
This entry is required if the permissions contain an owner entry.
parts.<part-name>.permissions.<permission>.mode¶
Type
str
Description
The numeric representation of the file’s read, write, and execute permissions.
This entry must be assigned an octal number, enclosed in double-quotation marks
("), for each defined path.
This value should align with the POSIX specification for file permissions, just like
one would use when calling chmod. For more detail on octal file permissions, see
the chmod command reference.
Volume keys¶
The volumes key and its values declare the schema and layout of the image’s
partitions.
volumes.<volume-name>.schema¶
Type
One of: ['gpt']
Description
The partitioning schema of the image.
Imagecraft currently supports GUID partition tables (GPT).
Examples
schema: gpt
volumes.<volume-name>.structure¶
Type
list[Partition]
Description
The partitions that comprise the image.
Each entry in the structures list represents a disk partition in the final
image.
Examples
structure:
- name: efi
type: C12A7328-F81F-11D2-BA4B-00A0C93EC93B
filesystem: vfat
role: system-boot
filesystem-label: EFI System
size: 256M
- name: rootfs
type: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
filesystem: ext4
filesystem-label: writable
role: system-data
size: 6G
Partition keys¶
The following keys can be declared for each partition listed in the structure key.
volumes.<volume-name>.structure.<partition>.name¶
Type
str
Description
The name of the partition.
The name must:
Be unique to the volume
Contain only lower case letters and hyphens
Contain at least one letter
Not start or end with a hyphen
Not exceed 36 characters
The name is interpreted as a UTF-16 encoded string.
Examples
name: efi
name: rootfs
volumes.<volume-name>.structure.<partition>.id¶
Type
UUID
Description
The partition’s unique identifier.
The identifier must be a unique 32-digit hexadecimal number in the GPT UUID format.
Examples
id: 6F8C47A6-1C2D-4B35-8B1E-9DE3C4E9E3FF
id: E3B0C442-98FC-1FC0-9B42-9AC7E5BD4B35
volumes.<volume-name>.structure.<partition>.role¶
Type
Role
Description
The partition’s purpose in the image.
Values
Value |
Description |
|---|---|
|
The partition stores the image’s primary operating system data. |
|
The partition stores the image’s boot assets. |
Examples
role: system-data
role: system-boot
volumes.<volume-name>.structure.<partition>.type¶
Type
GptType
Description
The type of the partition.
For GPT partitions, the value must be the standard 32-digit hexadecimal number associated with the type.
This is distinct from the structure.<partition>.id key, which is unique among
all partitions, regardless of type.
Values
Value |
Description |
|---|---|
|
Linux filesystem in a GPT schema. |
|
Microsoft basic data partition in a GPT schema. |
|
EFI system partition in a GPT schema. |
|
BIOS boot partition in a GPT schema. |
Examples
type: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
type: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
volumes.<volume-name>.structure.<partition>.size¶
Type
ByteSize
Description
The size of the partition, in bytes.
You can append an M or a G to the size to specify the unit in mebibytes or
gibibytes, respectively.
Examples
size: 256M
size: 6G
volumes.<volume-name>.structure.<partition>.filesystem¶
Type
FileSystem
Description
The filesystem of the partition.
Values
Value |
Description |
|---|---|
|
The ext4 filesystem. |
|
The ext3 filesystem. |
|
The FAT16 filesystem. |
|
The VFAT filesystem. |
Examples
filesystem: ext4
filesystem: fat16
volumes.<volume-name>.structure.<partition>.filesystem-label¶
Type
str
Description
A human-readable name to assign the partition.
If unset, the label will default to the value of structure.<partition>.name.
Labels must be unique to their volume.
Examples
filesystem-label: EFI System
filesystem-label: writable
Filesystem keys¶
The following keys can be declared for each filesystem mount listed.
filesystems.<filesystem-name>.<mount>.mount¶
Type
str
Description
The device’s mount point.
Examples
mount: "/"
mount: "/boot/efi"
filesystems.<filesystem-name>.<mount>.device¶
Type
str
Description
The device to be mounted. This must reference one of the partitions defined
in volumes.<volume-name>.structure.
Examples
device: "(default)"
device: "(volume/pc/rootfs)"