Rockcraft

Rockcraft project. Documentation: https://documentation.ubuntu.com/rockcraft/stable/

Type object
File match rockcraft.yaml
Schema URL https://catalog.lintel.tools/schemas/schemastore/rockcraft/latest.json
Source https://raw.githubusercontent.com/canonical/rockcraft/main/schema/rockcraft.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Rockcraft project definition.

Properties

name string required

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: "ubuntu", "jupyterlab-desktop", "lxd", "digikam", "kafka", "mysql-router-k8s"
minLength=1maxLength=40
summary string required

A short, single line description of the rock.

description string required

A full description of the rock, potentially including multiple paragraphs.

base string required

The base system image for the rock.

Values: "bare" "[email protected]" "[email protected]" "[email protected]" "[email protected]" "[email protected]"
platforms Record<string, null | Platform> required

Determines which architectures the project builds and runs on.

Examples: "{amd64: {build-on: [amd64], build-for: [amd64]}, arm64: {build-on: [amd64, arm64], build-for: [arm64]}}"
parts Record<string, object> required

The self-contained software pieces needed to create the final artifact.

Examples: "{cloud-init: {plugin: python, source-type: git, source: https://git.launchpad.net/cloud-init}}"
title string | null
Default: null
version string | null
Default: null
build-base string | null

The system used to build the rock.

Default: null
contact string | string[] | null

The author's contact links and email addresses.

Default: null
Examples: "[[email protected], https://example.com/contact]"
issues string | string[] | null

The links and email addresses for submitting issues, bugs, and feature requests.

Default: null
Examples: "[[email protected], https://example.com/issues]"
source-code string | null

The links to the source code of the project.

Default: null
Examples: "[https://github.com/canonical/craft-application]"
license string | null

The project's license as an SPDX expression

Default: null
Examples: "GPL-3.0+", "Apache-2.0"
adopt-info string | null

Selects a part to inherit metadata from.

Default: null
Examples: "foo-part"
package-repositories object[] | null

The package repositories to use for build and stage packages.

Default: null
Examples: "[{type: apt, components: [main], suites: [xenial], key-id: 78E1918602959B9C59103100F1831DDAFC42E99D, url: http://ppa.launchpad.net/snappy-dev/snapcraft-daily/ubuntu}]"
environment object | null

Additional environment variables for the base image's OCI environment.

Default: null
run-user string | null

The default OCI user. If unset, runs as root.

Default: null
services object | null

Services to run in the rock, using Pebble's layer specification syntax.

Default: null
checks object | null

Health checks for this rock.

Default: null
entrypoint-service string | null

The optional name of the Pebble service to serve as the entrypoint.

Default: null
Examples: "my-service"
entrypoint-command string | null

Overrides the rock's default Pebble OCI entrypoint and CMD properties.

Default: null
Examples: "echo [ Hello ]"

Definitions

ExecCheck object

Model for a check that executes a command.

override string required

How this check is combined with another same-named check.

Values: "merge" "replace"
exec object required

Lightweight schema validation for a Pebble exec check.

8 nested properties
command string required

The command to execute for this health check.

Examples: "/usr/bin/health-check"
service-context string | null

Run the check as the given service's user and group, with that service's working directory and environment variables set.

Default: null
environment object | null

A mapping of environment variables with which to run the check.

Default: null
user string | null

The user that will run the check.

Default: null
user-id integer | null

The UID of the user that will run the check.

Default: null
group string | null

The group name for the check process to run as.

Default: null
group-id integer | null

The GID of the group that will run the check.

Default: null
working-dir string | null

The working directory in which the command will run.

Default: null
level string | null

Check level, used for filtering checks when calling the health endpoint.

Default: null
period string | null

How frequently to run this check.

Default: null
Examples: "10s", "30m"
timeout string | null

The time before the check fails if not completed. Must be less than period.

Default: null
Examples: "5s", "2m"
threshold integer | null

Number of consecutive errors before the check is considered failed.

Default: null
ExecCheckOptions object

Lightweight schema validation for a Pebble exec check.

command string required

The command to execute for this health check.

Examples: "/usr/bin/health-check"
service-context string | null

Run the check as the given service's user and group, with that service's working directory and environment variables set.

Default: null
environment object | null

A mapping of environment variables with which to run the check.

Default: null
user string | null

The user that will run the check.

Default: null
user-id integer | null

The UID of the user that will run the check.

Default: null
group string | null

The group name for the check process to run as.

Default: null
group-id integer | null

The GID of the group that will run the check.

Default: null
working-dir string | null

The working directory in which the command will run.

Default: null
FailureExitState string

What to do on a failure exit.

HttpCheck object

Model for a check that uses HTTP.

override string required

How this check is combined with another same-named check.

Values: "merge" "replace"
http object required

Lightweight schema validation for a Pebble HTTP check.

2 nested properties
url string required

The URL to fetch

Examples: "https://example.com/foo", "http://localhost/health-check"
format=uriminLength=1
headers object | null

Headers to send with the HTTP request.

Default: null
Examples: {"X-Health-Check":"true"}
level string | null

Check level, used for filtering checks when calling the health endpoint.

Default: null
period string | null

How frequently to run this check.

Default: null
Examples: "10s", "30m"
timeout string | null

The time before the check fails if not completed. Must be less than period.

Default: null
Examples: "5s", "2m"
threshold integer | null

Number of consecutive errors before the check is considered failed.

Default: null
HttpCheckOptions object

Lightweight schema validation for a Pebble HTTP check.

url string required

The URL to fetch

Examples: "https://example.com/foo", "http://localhost/health-check"
format=uriminLength=1
headers object | null

Headers to send with the HTTP request.

Default: null
Examples: {"X-Health-Check":"true"}
Platform object

A single platform entry in the platforms dictionary.

This model defines how a single value under the platforms key works for a project.

build-on string[] | string required
Examples: "amd64", ["arm64","riscv64"]
minLength=1
build-for string[] | string required
Service object

Lightweight schema validation for a Pebble service.

Based on https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/layer-specification/

override string required

Whether to replace pre-existing service definitions or merge them.

Values: "merge" "replace"
command string required

The command used to run the service.

Examples: "/usr/bin/ls", "/usr/bin/somedaemon --db=/db/path [ --port 8080 ]"
summary string | null

A short summary of the service.

Default: null
description string | null

A detailed, potentially multi-line, description of the service.

Default: null
startup string | null

Whether the service is enabled automatically when the rock starts.

Default: null
after string[] | null

The names of other services that this service should start after.

Default: null
before string[] | null

The names of other services that this service should start before.

Default: null
requires string[] | null

The names of other services that this service requires in order to start.

Default: null
environment object | null

Environment variables to set for this process.

Default: null
user string | null

Run the service as this user.

Default: null
user-id integer | null

Run the service with this user ID.

Default: null
group string | null

Run the service as this group.

Default: null
group-id integer | null

Run the service with this group ID.

Default: null
working-dir string | null

Working directory for the service command.

Default: null
on-success SuccessExitState | null

What to do when the service exits with success.

Default: null
on-failure FailureExitState | null

What to do when the service exits with an error.

Default: null
on-check-failure object | null

What to do when a health check fails.

Default: null
backoff-delay string | null

Initial backoff delay for the 'restart' exit action.

Default: null
Examples: "500ms", "10s"
backoff-factor number | null

Multiplication factor for backoff delay.

Default: null
Examples: "2.0", "1.000001"
backoff-limit string | null

Maximum backoff delay.

Default: null
Examples: "30s", "1m"
kill-delay string | null

How long to wait after a SIGTERM and exit pebble uses SIGKILL.

Default: null
Examples: "10s", "1m"
SuccessExitState string

What to do on exit success.

TcpCheck object

Model for a check that uses TCP.

override string required

How this check is combined with another same-named check.

Values: "merge" "replace"
tcp object required

Lightweight schema validation for a Pebble TCP check.

2 nested properties
port integer required

The TCP port to check is open.

min=1max=65535
host string | null

The hostname or IP address to check. Defaults to 'localhost'.

Default: null
Examples: "localhost", "::1", "127.0.0.1"
level string | null

Check level, used for filtering checks when calling the health endpoint.

Default: null
period string | null

How frequently to run this check.

Default: null
Examples: "10s", "30m"
timeout string | null

The time before the check fails if not completed. Must be less than period.

Default: null
Examples: "5s", "2m"
threshold integer | null

Number of consecutive errors before the check is considered failed.

Default: null
TcpCheckOptions object

Lightweight schema validation for a Pebble TCP check.

port integer required

The TCP port to check is open.

min=1max=65535
host string | null

The hostname or IP address to check. Defaults to 'localhost'.

Default: null
Examples: "localhost", "::1", "127.0.0.1"
Part object

The part specification data.

plugin string | null

The plugin to build the part with.

Default: null
Values: "dump" "nil" "ant" "autotools" "cargo-use" "cmake" "dotnet" "go" "go-use" "gradle" "jlink" "make" "maven" "maven-use" "meson" "npm" "npm-use" "poetry" "python" "qmake" "ruby" "rust" "scons" "uv"
Examples: "python", "dump"
source string | null

The location of the source files for the part.

Default: null
Examples: ".", "https://github.com/canonical/dqlite"
source-checksum string

The checksum of the downloaded source, to ensure integrity.

Default: ""
Examples: "sha256/1451d01ee3a21100340aed867d0b799f46f0b1749680028d38c3f5d0128fb8a7"
source-channel string | null
Default: null
source-branch string

The target branch for Git sources.

Default: ""
Examples: "main", "hotfix/2.10"
source-commit string

The target commit for Git sources.

Default: ""
Examples: "36086af03fc4941a8ac219648ce77401743f3ae0"
source-depth integer

The commit depth to fetch for Git sources.

Default: 0
Examples: "1"
source-subdir string

The subdirectory of the unpacked source where the build will occur.

Default: ""
Examples: "src", "demo_nodes_cpp"
source-submodules string[] | null

The registered submodules to fetch from Git sources.

Default: null
Examples: "[third_party/googletest, third_party/jsoncpp]", "[libbpf]"
source-tag string

The target tag for Git sources.

Default: ""
Examples: "1.0.1"
source-type string

The format of the part's source.

Default: ""
Examples: "git", "local"
disable-parallel boolean

Whether to disable CPU multithreading during the build step.

Default: false
Examples: "true"
after string[]

The parts to process before starting this part's build.

Default:
[]
Examples: "[build-deps, daemon]"
overlay-packages string[]

The packages to install in the part's layer.

Default:
[]
Examples: "[ed]"
stage-snaps string[]

The snaps to include in the stage environment.

Default:
[]
Examples: "[go/1.17, chisel/latest/candidate, mir-kiosk-x11]"
stage-packages string[]

The packages or Chisel slices to include in the stage environment.

Default:
[]
Examples: "[curl, libxml2]"
build-snaps string[]

The snaps to install in the build environment.

Default:
[]
Examples: "[go/latest/stable, node/stable]"
build-packages string[]

The packages to install in the build environment.

Default:
[]
Examples: "[git, libffi-dev, libssl-dev]"
build-environment object[]

The environment variables to define for the build step, as key-value pairs.

Default:
[]
Examples: "[{MESSAGE: "Hello world!"}, {NAME: "Craft Parts"}]"
build-attributes string[]

Identifiers that control specific behaviors during the build.

Default:
[]
Examples: "[enable-usrmerge]", "[disable-usrmerge]"
organize Record<string, string>

A map of files from the build directory to their destinations in the stage directory.

Examples: "{hello.py: bin/hello}"
overlay string[]

The files to copy from the part's layer to the stage directory.

Examples: "[bin, usr/bin]", "[-etc/cloud/cloud.cfg.d/90_dpkg.cfg]"
stage string[]

The files to copy from the build directory to the stage directory.

Examples: "[usr/bin/*, usr/share]", "[-usr, zfsutils-linux]"
prime string[]
Examples: "[usr/lib/*/qt6/plugins/tls/*, -usr/share/thumbnailers]"
override-pull string | null

The commands to run instead of the default behavior of the pull step.

Default: null
Examples: "| craftctl default rm $CRAFT_PART_SRC/pyproject.toml"
overlay-script string | null

The commands to run after the part's overlay packages are installed.

Default: null
Examples: "| 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"
override-overlay string | null

Shell script to run inside the overlay chroot after mounting.

Default: null
Examples: "echo 'hello from chroot' > /root/test.txt"
override-build string | null

The commands to run instead of the default behavior of the build step.

Default: null
Examples: "| cd cmd/webhook mkdir $CRAFT_PART_INSTALL/ko-app go build -o $CRAFT_PART_INSTALL/ko-app/webhook -a ."
override-stage string | null

The commands to run instead of the default behavior of the stage step.

Default: null
Examples: "| craftctl default chown -R 499 "${CRAFT_PART_INSTALL}/entrypoint.sh""
override-prime string | null

The commands to run instead of the default behavior of the prime step.

Default: null
Examples: "| craftctl default mkdir -p $CRAFT_PRIME/var/lib/mysql mkdir -p $CRAFT_PRIME/var/lib/mysqld"
permissions Permissions[]

The ownership and permission settings for a set of files in the part's prime directory.

Default:
[]
Examples: "[{owner: 2000, group: 2000}, {path: srv/indico/start-indico.sh, mode: "544"}, {path: etc/, mode: "755"}]"
Permissions object

Description of the ownership and permission settings for a set of files.

A Permissions object specifies that a given pattern-like path should be owned by owner with a given group, and have the read/write/execute bits defined by mode.

Notes

  • path is optional and defaults to "everything";
  • owner and group are optional if both are omitted - that is, if one of the pair is specified then both must be;
  • mode is a string containing an integer in base 8. For example, "755", "0755" and "0o755" are all accepted and are the equivalent of calling chmod 755 ....
path string

The file path, relative to the prime directory, being assigned permissions.

Default: "*"
owner integer | null

The numeric user ID (UID) of the desired owner on the host system.

Default: null
group integer | null

The numeric group (GID) of the desired owner group on the host system.

Default: null
mode string | null

The numeric representation of the file's read, write, and execute permissions.

Default: null
RubyFlavor string

All Ruby implementations supported by ruby-install.