osbuild-manifest - Man Page

OSBuild Manifest Format

Synopsis

{
"pipeline": {
"build": { ... },
"stages": [ ... ],
"assembler": { ... }
},

"sources": {
"org.osbuild.files": {
"urls": {
...
}
}
}
}

The osbuild manifest format describes to osbuild(1) which build pipeline to execute and which resources to make available to it. A manifest is always formatted as a single JSON document and must contain all information needed to execute a specified pipeline. Furthermore, a manifest must be authoritative in that data passed to osbuild(1) via other means than the manifest must not affect the outcome of the pipeline. Therefore, the content of a manifest deterministicly describes the expected output.

The exact schema of the manifest is available online as the OSBuild JSON Schema [1].

A manifest consists of a fixed amount of top-level sections. These include sections that describe the steps of the pipeline to execute, but also external resources to make available to the pipeline execution. The following manual describe the different sections available in the manifest, as well as short examples how these sections can look like.

Pipelines

The pipeline section describes the pipeline to execute. This includes a description of the build system to use for the execution, the stages to execute, and the final assemblers which produce the desired output format.

"pipeline": {
"build": { ... },
"stages": [ ... ],
"assembler": { ... }
}

PIPELINE: build

The build section specifies the system to use when executing stages of a pipeline. The definition of this section is recursive, in that it requires a pipeline definition as its value. The build system is created by recursively executing its pipeline definition first. It is then used as the build system to execute the pipeline that defined this build system.

Additionally to the pipeline description, a build definition must also define the runner to use when executing applications in this system. These runners are shipped with osbuild(1) and perform environment setup before executing a stage.

"build": {
"pipeline": {
"build": { ... },
"stages": [ ... ],
"assembler": { ... }
},
"runner": "org.osbuild.linux"
}

PIPELINE: stages

The stages section is an array of stages to execute as part of the pipeline. Together they produce a file system tree that forms the output of the pipeline. Each stage can modify the tree, alter its content, or add new data to it. All stages are executed in sequence, each taking the output of the previous stage as their input.

"stages": [
{
"name": "<stage-A>",
"options": {
...
}
},
{
"name": "<stage-B>",
"options": {
...
}
}
]

Stages are shipped together with osbuild(1). The manifest can optionally contain options that are passed to the respective stage.

PIPELINE: assembler

The assembler is the final stage of a pipeline. It is similar to a stage but always executed last. Furthermore, it is not allowed to modify the file system tree. Instead, it is expected to take the file system tree and produce a desired output format for consumption by the user.

"assembler": {
"name": "<assembler-A>",
"options": {
...
}
}

Assemblers are shipped together with osbuild(1). The manifest can optionally contain options that are passed to the respective assembler.

Sources

The sources section describes external resources that are needed to execute a pipeline. Specified sources do not have to be used by a pipeline execution. Hence, it is not an error to specify more resources than actually required.

Note:: The pipeline executor might prefetch resources before executing a pipeline. Therefore, you should only specify resources that are actually required to execute a pipeline.

The sources section thus allows to hide from the pipeline execution where an external resource comes from and how it is fetched. Instead, it provides an internal API to the pipeline to access these external resources in a common way. Depending on which pipeline stages are defined, they required different source types to provide configured resources.

The following sub-sections describe the different available source types. To configure a specific source type, you would use something like the following:

"sources": {
"<source-type-A>": {
...
},
"<source-type-B>": {
...
}
}

SOURCE: org.osbuild.files

The org.osbuild.files source type allows to provide external files to the pipeline execution. The argument to this type is a dictionary of file names and their corresponding resource URIs. The file name must be the hash of the expected file, prefixed with the hash-type.

The following example shows how you could provide two files to a pipeline execution via the org.osbuild.files source type:

"sources": {
"org.osbuild.files": {
"sha256:<hash-A>": " <https://example.com/some-file-A> ",
"sha256:<hash-B>": " <https://example.com/some-file-B> "
}
}