kurchu.toml - Man Page
input configuration for compose generation
Description
The Kurchu configuration file provides a declarative format to describe how Kurchu should create a collection of artifacts (henceforth referred to as a "compose").
Format
The configuration file follows the TOML specification. For more information on TOML, visit https://toml.io.
The following subsections describe the content of the file format.
compose table
This is the top level table for the configuration where global settings for the compose is defined.
The following settings are present at this level:
- release_name defines the base name of the compose.
- release_version defines the base version of the compose, and is used similarly to "releasever" in dnf(8) and dnf.conf(5).
- date_format is an optional value that defines the date string used in date(1) format. If unset, the default is "%Y%m%d".
- compose_id defines the full ID of the generated compose. The values of "release_version" and "compose_date" can be substituted in by using those names wrapped with curly braces.
- destdir defines the local directory path to store the compose. If unset, the default is "./artifacts".
compose.gather table
This table in the configuration defines what content should be sourced as input for the compose. There is a single key: sources, which contains an array of inline tables. An example looks like this:
Within this section, "release_version" can be substituted in as part of a string value for any key as shown above.
Each source inline table entry has the following settings:
- name for an identity of the source
- url for the location to fetch the source
- target for the location to store the source relative to the destination directory
- type for the source type being fetched. The following values are acceptable: "kojidist", "pungi", "bodhi", "odcs", and "yumrepo".
- sync for indicating whether the source needs to be fully downloaded. Setting this to "false" indicates that only a reference to the source ID needs to be fetched, rather than a complete download. This can be useful if you already have mirrors elsewhere to use instead.
compose.compile table
This table in the configuration defines images to be created to incorporate into the compose.
Image creation configuration is split into common settings and subsections. For the common settings:
- base_name for the name prefix used for all produced images
- image_release for the version suffix used for all produced images. "compose_date" can be substituted in by that label wrapped with curly braces.
- target for the location to store the images relative to the destination directory
For the images being produced, this is defined in a key named images, which contains an array of inline tables. An example looks like this:
Each image inline table entry has the following settings:
- variant for the image variant to produce. This is often suffixed to base_name to fully name an image and defined as "image_name".
- image_type for identifying what type of image is being made. Valid values depend on selected image build tool.
- volid_prefix for overriding the name portion of a volume ID. It only applies to ISO images.
- appid_prefix for overriding the name portion of an application ID. It only applies to ISO images.
- image_tool for identifying the image build tool. Currently the only valid option is "kiwi".
- arch for optionally restricting an image to a set of architectures. If not set, the build system's defaults are used. This is an array of architectures, with the architecture names dependent on the build system.
- buildsys for selecting the build system target to run the image build. This is defined in the configuration.
Within this section, "base_name", "variant", "release_version", and "compose_date" can be substituted in as part of a string value for any key.
compose.compile.type.kiwi table
This table defines kiwi(8) base settings to be used for any image build using this tool.
There is a single setting key:
- kiwi_result_bundle_name_format for optionally defining the name format for files created as part of the image build. The format is described in kiwi::result::bundle(8). If not set, a default format may be used based on the build system backend.
Additionally, there is a key kiwi_description, which contains an inline table.
The inline table has the following settings:
- url for the location that the descriptions are to be fetched from
- path for the location relative to the base directory for the descriptions file
- vcs for type of version control system (if any). For now, only "git" is supported.
- ref for symbolic reference (branch or tag, for example) from which to pull the descriptions from, if from a version control system
Within this section, "base_name" and "release_version" can be substituted in as part of a string value for any key as shown above.
compose.compile.buildsys.<name> table
This table is where the configuration for the build system is declared. The name of this table is formulated by the value set for "buildsys" in the image entries defined in the images array in the "compose.compile" table. For example, if a "dev" build system was referenced, then the table name will be "compose.compile.buildsys.dev".
This table has the following settings:
- type for the build system type. The only supported value is "koji".
- koji_profile for the profile to pass to the koji CLI client.
- koji_build_tag for the build environment reference to build the image.
- koji_success_tags for the array of tags to put the built images into.
- gather_url for the location the build system publishes the images.
Within this section, "image_name", "release_version", and "image_release" can be substituted in as part of a string value for any key as shown above.
compose.furnish table
This table defines the settings for publishing completed composes.
This table has the following settings:
- write_compose_info is a flag for writing out a json file that provides static metadata of what the compose includes. By default, it will be "true".
For external upload targets, this is defined in a key named upload_targets, which contains an array of inline tables. An example looks like this:
Each inline table entry contains the following settings:
- name for the named reference (e.g. bucket name for s3)
- target for the directory path in the upload target to write to
- generate_indexhtml for optionally generating directory listing pages
- public for optionally declaring world readable access
- type for type of storage upload target (currently only "s3" is supported)
The usage of upload targets is optional, and if this is run from the system serving the content, it is uneeded provided the destination directory is set correctly to store the content in a published location.
See Also
kurchu(1)
Authors
Developed and maintained by Neal Gompa <ngompa@velocitylimitless.com>.