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 in‐
31 formation needed to execute a specified pipeline. Furthermore, a mani‐
32 fest 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 ex‐
35 pected 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 in‐
41 clude sections that describe the steps of the pipeline to execute, but
42 also external resources to make available to the pipeline execution.
43 The following manual describe the different sections available in the
44 manifest, as well as short examples how these sections can look like.
45
47 The pipeline section describes the pipeline to execute. This includes a
48 description of the build system to use for the execution, the stages to
49 execute, and the final assemblers which produce the desired output for‐
50 mat.
51 "pipeline": {
53 "build": { ... },
54 "stages": [ ... ],
55 "assembler": { ... }
56 }
57 PIPELINE: build
61 The build section specifies the system to use when executing stages of
62 a pipeline. The definition of this section is recursive, in that it re‐
63 quires a pipeline definition as its value. The build system is created
64 by recursively executing its pipeline definition first. It is then used
65 as the build system to execute the pipeline that defined this build
66 system.
67 Additionally to the pipeline description, a build definition must also
69 define the runner to use when executing applications in this system.
70 These runners are shipped with osbuild(1) and perform environment setup
71 before executing a stage.
72 "build": {
74 "pipeline": {
75 "build": { ... },
76 "stages": [ ... ],
77 "assembler": { ... }
78 },
79 "runner": "org.osbuild.linux"
80 }
81 PIPELINE: stages
85 The stages section is an array of stages to execute as part of the
86 pipeline. Together they produce a file system tree that forms the out‐
87 put of the pipeline. Each stage can modify the tree, alter its con‐
88 tent, or add new data to it. All stages are executed in sequence, each
89 taking the output of the previous stage as their input.
90 "stages": [
92 {
93 "name": "<stage-A>",
94 "options": {
95 ...
96 }
97 },
98 {
99 "name": "<stage-B>",
100 "options": {
101 ...
102 }
103 }
104 ]
105 Stages are shipped together with osbuild(1). The manifest can option‐
109 ally contain options that are passed to the respective stage.
110 PIPELINE: assembler
112 The assembler is the final stage of a pipeline. It is similar to a
113 stage but always executed last. Furthermore, it is not allowed to mod‐
114 ify the file system tree. Instead, it is expected to take the file sys‐
115 tem tree and produce a desired output format for consumption by the
116 user.
117 "assembler": {
119 "name": "<assembler-A>",
120 "options": {
121 ...
122 }
123 }
124 Assemblers are shipped together with osbuild(1). The manifest can op‐
128 tionally contain options that are passed to the respective assembler.
129
131 The sources section describes external resources that are needed to ex‐
132 ecute a pipeline. Specified sources do not have to be used by a pipe‐
133 line execution. Hence, it is not an error to specify more resources
134 than actually required.
135 Note: The pipeline executor might prefetch resources before executing
137 a pipeline. Therefore, you should only specify resources that
138 are actually required to execute a pipeline.
139 The sources section thus allows to hide from the pipeline execution
141 where an external resource comes from and how it is fetched. Instead,
142 it provides an internal API to the pipeline to access these external
143 resources in a common way. Depending on which pipeline stages are de‐
144 fined, they required different source types to provide configured re‐
145 sources.
146 The following sub-sections describe the different available source
148 types. To configure a specific source type, you would use something
149 like the following:
150 "sources": {
152 "<source-type-A>": {
153 ...
154 },
155 "<source-type-B>": {
156 ...
157 }
158 }
159 SOURCE: org.osbuild.files
163 The org.osbuild.files source type allows to provide external files to
164 the pipeline execution. The argument to this type is a dictionary of
165 file names and their corresponding resource URIs. The file name must be
166 the hash of the expected file, prefixed with the hash-type.
167 The following example shows how you could provide two files to a pipe‐
169 line execution via the org.osbuild.files source type:
170 "sources": {
172 "org.osbuild.files": {
173 "sha256:<hash-A>": "https://example.com/some-file-A",
174 "sha256:<hash-B>": "https://example.com/some-file-B"
175 }
176 }
177
181 osbuild(1), osbuild-composer(1)
182
184 [1] OSBuild JSON Schema: https://osbuild.org/schemas/osbuild1.json
185 OSBUILD-MANIFEST(5)