1OSBUILD-MANIFEST(5) File Formats Manual OSBUILD-MANIFEST(5)
2
6 osbuild-manifest - OSBuild Manifest Format
7
9 {
10 "pipeline": {
11 "build": { ... },
12 "stages": [ ... ],
13 "assembler": { ... }
14 },
15 "sources": {
17 "org.osbuild.files": {
18 "urls": {
19 ...
20 }
21 }
22 }
23 }
24
28 The osbuild manifest format describes to osbuild(1) which build pipe‐
29 line to execute and which resources to make available to it. A manifest
30 is always formatted as a single JSON document and must contain all
31 information needed to execute a specified pipeline. Furthermore, a man‐
32 ifest must be authoritative in that data passed to osbuild(1) via other
33 means than the manifest must not affect the outcome of the pipeline.
34 Therefore, the content of a manifest deterministicly describes the
35 expected output.
36 The exact schema of the manifest is available online as the OSBuild
38 JSON Schema [1].
39 A manifest consists of a fixed amount of top-level sections. These
41 include sections that describe the steps of the pipeline to execute,
42 but also external resources to make available to the pipeline execu‐
43 tion. The following manual describe the different sections available in
44 the manifest, as well as short examples how these sections can look
45 like.
46
48 The pipeline section describes the pipeline to execute. This includes a
49 description of the build system to use for the execution, the stages to
50 execute, and the final assemblers whichproduce the desired output for‐
51 mat.
52 "pipeline": {
54 "build": { ... },
55 "stages": [ ... ],
56 "assembler": { ... }
57 }
58 PIPELINE: build
62 The build section specifies the system to use when executing stages of
63 a pipeline. The definition of this section is recursive, in that it
64 requires a pipeline definition as its value. The build system is cre‐
65 ated by recursively executing its pipeline definition first. It is then
66 used as the build system to execute the pipeline that defined this
67 build system.
68 Additionally to the pipeline description, a build definition must also
70 define the runner to use when executing applications in this system.
71 These runners are shipped with osbuild(1) and perform environment setup
72 before executing a stage.
73 "build": {
75 "pipeline": {
76 "build": { ... },
77 "stages": [ ... ],
78 "assembler": { ... }
79 },
80 "runner": "org.osbuild.linux"
81 }
82 PIPELINE: stages
86 The stages section is an array of stages to execute as part of the
87 pipeline. Together they produce a file system tree that forms the out‐
88 put of the pipeline. Each stage can modify the tree, alter its con‐
89 tent, or add new data to it. All stages are executed in sequence, each
90 taking the output of the previous stage as their input.
91 "stages": [
93 {
94 "name": "<stage-A>",
95 "options": {
96 ...
97 }
98 },
99 {
100 "name": "<stage-B>",
101 "options": {
102 ...
103 }
104 }
105 ]
106 Stages are shipped together with osbuild(1). The manifest can option‐
110 ally contain options that are passed to the respective stage.
111 PIPELINE: assembler
113 The assembler is the final stage of a pipeline. It is similar to a
114 stage but always executed last. Furthermore, it is not allowed to mod‐
115 ify the file system tree. Instead, it is expected to take the file sys‐
116 tem tree and produce a desired output format for consumption by the
117 user.
118 "assembler": {
120 "name": "<assembler-A>",
121 "options": {
122 ...
123 }
124 }
125 Assemblers are shipped together with osbuild(1). The manifest can
129 optionally contain options that are passed to the respective assembler.
130
132 The sources section describes external resources that are needed to
133 execute a pipeline. Specified sources do not have to be used by a pipe‐
134 line execution. Hence, it is not an error to specify more resources
135 than actually required.
136 Note: The pipeline executor might prefetch resources before executing
138 a pipeline. Therefore, you should only specify resources that
139 are actually required to execute a pipeline.
140 The sources section thus allows to hide from the pipeline execution
142 where an external resource comes from and how it is fetched. Instead,
143 it provides an internal API to the pipeline to access these external
144 resources in a common way. Depending on which pipeline stages are
145 defined, they required different source types to provide configured
146 resources.
147 The following sub-sections describe the different available source
149 types. To configure a specific source type, you would use something
150 like the following:
151 "sources": {
153 "<source-type-A>": {
154 ...
155 },
156 "<source-type-B>": {
157 ...
158 }
159 }
160 SOURCE: org.osbuild.files
164 The org.osbuild.files source type allows to provide external files to
165 the pipeline execution. The argument to this type is a dictionary of
166 file names and their corresponding resource URIs. The file name must be
167 the hash of the expected file, prefixed with the hash-type.
168 The following example shows how you could provide two files to a pipe‐
170 line execution via the org.osbuild.files source type:
171 "sources": {
173 "org.osbuild.files": {
174 "sha256:<hash-A>": "https://example.com/some-file-A",
175 "sha256:<hash-B>": "https://example.com/some-file-B"
176 }
177 }
178
182 osbuild(1), osbuild-composer(1)
183
185 [1] OSBuild JSON Schema: https://osbuild.org/schemas/osbuild1.json
186 OSBUILD-MANIFEST(5)