1OSBUILD-MANIFEST(5)           File Formats Manual          OSBUILD-MANIFEST(5)
2
3
4

NAME

6       osbuild-manifest - OSBuild Manifest Format
7

SYNOPSIS

9       {
10         "pipeline": {
11           "build": { ... },
12           "stages": [ ... ],
13           "assembler": { ... }
14         },
15
16         "sources": {
17           "org.osbuild.files": {
18             "urls": {
19               ...
20             }
21           }
22         }
23       }
24
25
26

DESCRIPTION

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
37       The exact schema of the manifest is available  online  as  the  OSBuild
38       JSON Schema [1].
39
40       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

PIPELINES

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 whichproduce the desired output for‐
50       mat.
51
52       "pipeline": {
53         "build": { ... },
54         "stages": [ ... ],
55         "assembler": { ... }
56       }
57
58
59
60   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
68       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
73       "build": {
74         "pipeline": {
75           "build": { ... },
76           "stages": [ ... ],
77           "assembler": { ... }
78         },
79         "runner": "org.osbuild.linux"
80       }
81
82
83
84   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
91       "stages": [
92         {
93           "name": "<stage-A>",
94           "options": {
95             ...
96           }
97         },
98         {
99           "name": "<stage-B>",
100           "options": {
101             ...
102           }
103         }
104       ]
105
106
107
108       Stages are shipped together with osbuild(1). The manifest  can  option‐
109       ally contain options that are passed to the respective stage.
110
111   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
118       "assembler": {
119         "name": "<assembler-A>",
120         "options": {
121           ...
122         }
123       }
124
125
126
127       Assemblers  are  shipped together with osbuild(1). The manifest can op‐
128       tionally contain options that are passed to the respective assembler.
129

SOURCES

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
136       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
140       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
147       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
151       "sources": {
152         "<source-type-A>": {
153           ...
154         },
155         "<source-type-B>": {
156           ...
157         }
158       }
159
160
161
162   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
168       The  following example shows how you could provide two files to a pipe‐
169       line execution via the org.osbuild.files source type:
170
171       "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
178
179

SEE ALSO

181       osbuild(1), osbuild-composer(1)
182

NOTES

184       [1]  OSBuild JSON Schema: https://osbuild.org/schemas/osbuild1.json
185
186
187
188
189                                                           OSBUILD-MANIFEST(5)
Impressum