github.com/canonical/ubuntu-image@v0.0.0-20240430122802-2202fe98b290/internal/imagedefinition/README.rst (about) 1 ================ 2 Image Definition 3 ================ 4 5 The image definition is a YAML file that is consumed by ``ubuntu-image`` 6 that specifies how to build a classic image. 7 8 The following specification defines what is supported in the YAML: 9 10 .. code:: yaml 11 12 # The name of the image. 13 name: <string> 14 # The human readable name to use in the image. 15 display-name: <string> 16 # An integer used to track changes to the image definition file. 17 revision: <int> (optional) 18 # The architecture of the image to create. 19 architecture: amd64 | armhf | arm64 | s390x | ppc64el | riscv64 20 # The Ubuntu codename to use as apt sources. Example: jammy 21 series: <string> 22 # The classification for this image. 23 class: cloud | installer | preinstalled 24 # An alternative kernel to install in the image. Normally this 25 # is just one kernel and defaults to "linux", but we support 26 # installing more than one, since installer images can provide 27 # multiple kernels to choose from. 28 kernel: <string> (optional) 29 # gadget defines the boot assets of an image. When building a 30 # classic image, the gadget is optionally compiled as part of 31 # the state machine run. 32 gadget: (optional) 33 # An URI pointing to the location of the gadget tree. For 34 # gadgets that need to be built this can be a local path 35 # to a directory or a URL to be git cloned. These gadget 36 # tree builds will automatically have the environment 37 # variables ARCH=<architecture> and SERIES=<series>. 38 # The values for these environment variables are sourced 39 # from this image definition file. For pre-built 40 # gadget trees this must be a local path. 41 # The URI must begin with either http://, https://, or file:// 42 url: <string> 43 # The type of gadget tree source. Currently supported values 44 # are git, directory, and prebuilt. When git is used the url 45 # will be cloned and `make` will be run. When directory is 46 # used, ubuntu-image will change directories into the specified 47 # URL and run `make`. When prebuilt is used, the contents of the 48 # URL are simply copied to the gadget directory. 49 type: git | directory | prebuilt 50 # A git reference to use if building a gadget tree from git. 51 ref: <string> (optional) 52 # The branch to use if building a gadget tree from git. 53 # Defaults to "main" 54 branch: <string> (optional) 55 # The target to build when running "make". If none is specified 56 # make will be called with no target. This key/value pair has 57 # no effect when the gadget.type is "prebuilt" 58 target: <string> (optional) 59 # A path to a model assertion to use when pre-seeding snaps 60 # in the image. Must be a local file URI beginning with file:// 61 # The given path will be interpreted as relative to the path of 62 # the image definition file if is not absolute. 63 model-assertion: <string> (optional) 64 # Defines parameters needed to build the rootfs for a classic 65 # image. Currently only building from a seed is supported. 66 # Exactly one of the following must be included: seed, 67 # archive-tasks, or tarball. 68 rootfs: 69 # Components are a list of apt sources, such as main, 70 # universe, and restricted. Defaults to "main,restricted". 71 components: (optional) 72 - <string> 73 - <string> 74 # The archive to use as an apt source. Defaults to "ubuntu". 75 archive: <string> (optional) 76 # The flavor of Ubuntu to build. Examples: kubuntu, xubuntu. 77 # Defaults to "ubuntu". 78 flavor: <string> (optional) 79 # The mirror for apt sources. 80 # Defaults to "http://archive.ubuntu.com/ubuntu/". 81 mirror: <string> (optional) 82 # Ubuntu offers several pockets, which often imply the 83 # inclusion of other pockets. The release pocket only 84 # includes itself. The security pocket includes itself 85 # and the release pocket. Updates includes updates, 86 # security, and release. Proposed includes all pockets. 87 # Defaults to "release". 88 pocket: release | security | updates | proposed (optional) 89 # Used for building an image from a set of archive tasks 90 # rather than seeds. Not yet supported. 91 archive-tasks: (exactly 1 of archive-tasks, seed or tarball must be specified) 92 - <string> 93 - <string> 94 # The seed to germinate from to create a list of packages 95 # to be installed in the image. 96 seed: (exactly 1 of archive-tasks, seed or tarball must be specified) 97 # A list of git, bzr, or http locations from which to 98 # retrieve the seeds. Must be a web address, local file paths 99 # are not supported 100 urls: (required if seed dict is specified) 101 - <string> 102 - <string> 103 # The names of seeds to use from the germinate output. 104 # Examples: server, minimal, cloud-image. 105 names: (required if seed dict is specified) 106 - <string> 107 - <string> 108 # Whether to use the --vcs flag when running germinate. 109 # Defaults to "true". 110 vcs: <boolean> (optional) 111 # An alternative branch to use while retrieving seeds 112 # from a git or bzr source. 113 branch: <string> (optional) 114 # Whether to write the sources list as Deb822 formatted entries in 115 # /etc/apt/sources.list.d/ubuntu.sources or not (and thus use the legacy format 116 # in /etc/apt/sources.list) 117 # Default to "false" for now to not break existing builds but a warning will be 118 # displayed and this default will switch at some point in the future. 119 # A warning is also displayed if no value was explicitely set for this field. 120 sources-list-deb822: <boolean> (optional) 121 # Used for pre-built root filesystems rather than germinating 122 # from a seed or using a list of archive-tasks. Must be an 123 # an uncompressed tar archive or a tar archive with one of the 124 # following compression types: bzip2, gzip, xz, zstd. 125 tarball: (exactly 1 of archive-tasks, seed or tarball must be specified) 126 # The path to the tarball. Currently only local paths beginning with 127 # file:// are supported. The given path will be interpreted as relative 128 # to the path of the image definition file if is not absolute. 129 url: <string> (required if tarball dict is specified) 130 # URL to the gpg signature to verify the tarball against. 131 gpg: <string> (optional) 132 # SHA256 sum of the tarball used to verify it has not 133 # been altered. 134 sha256sum: <string> (optional) 135 # ubuntu-image supports building automatically with some 136 # customizations to the image. Note that if customization 137 # is specified, at least one of the subkeys should be used 138 # This is only supported for classic image building 139 customization: (optional) 140 # Components are a list of apt sources, such as main, 141 # universe, and restricted. Defaults to "main, restricted, universe". 142 # These are used in the resulting img, not to build it. 143 components: (optional) 144 - <string> 145 - <string> 146 # Ubuntu offers several pockets, which often imply the 147 # inclusion of other pockets. The release pocket only 148 # includes itself. The security pocket includes itself 149 # and the release pocket. Updates includes updates, 150 # security, and release. Proposed includes all pockets. 151 # Defaults to "release". 152 # This value is in the resulting img, not to build it. 153 pocket: release | security | updates | proposed (optional) 154 # Used only for installer images 155 installer: (optional) 156 preseeds: (optional) 157 - <string> 158 - <string> 159 # Only applicable to subiquity based layered images. 160 layers: (optional) 161 - <string> 162 - <string> 163 # Used to create a custom cloud-init configuration. 164 # Given configuration should be fully valid cloud-init configuration 165 # (including file header) 166 cloud-init: (optional) 167 # cloud-init yaml metadata 168 meta-data: <yaml as a string> (optional) 169 # cloud-init yaml metadata 170 user-data: <yaml as a string> (optional) 171 # cloud-init yaml metadata 172 network-config: <yaml as a string> (optional) 173 # Extra PPAs to install in the image. Both public and 174 # private PPAs are supported. If specifying a private 175 # PPA, the auth and fingerprint fields are required. 176 # For public PPAs, auth has no effect and fingerprint 177 # is optional. These PPAs will be used as a source 178 # while creating the rootfs for the classic image. 179 extra-ppas: (optional) 180 - 181 # The name of the PPA in the format "user/ppa-name". 182 name: <string> 183 # The fingerprint of the GPG signing key for this 184 # PPA. Public PPAs have this information available 185 # from the Launchpad API, so it can be retrieved 186 # automatically. For Private PPAs this must be 187 # specified. 188 fingerprint: <string> (optional for public PPAs) 189 # Authentication for private PPAs in the format 190 # "user:password". 191 auth: <string> (optional for public PPAs) 192 # Whether to leave the PPA source file in the resulting 193 # image. Defaults to "true". If set to "false" this 194 # PPA will only be used as a source for installing 195 # packages during the rootfs build process, and the 196 # resulting image will not have this PPA configured. 197 keep-enabled: <boolean> 198 # A list of extra packages to install in the rootfs beyond 199 # what is included in the germinate output. 200 extra-packages: (optional) 201 - 202 name: <string> 203 # Extra snaps to preseed in the rootfs of the image. 204 extra-snaps: (optional) 205 - 206 # The name of the snap. 207 name: <string> 208 # The channel from which to seed the snap. 209 # If both the revision and channel are provided 210 # the snap revision specified will be installed 211 # and updates will come from the channel specified 212 channel: <string> (optional) 213 # The store to retrieve the snap from. Not yet supported. 214 # Defaults to "canonical". 215 store: <string> (optional) 216 # The revision of the snap to preseed in the rootfs. 217 # If both the revision and channel are provided 218 # the snap revision specified will be installed 219 # and updates will come from the channel specified 220 revision: <int> (optional) 221 # After the rootfs has been created and before the image 222 # artifacts are generated, ubuntu-image can automatically 223 # perform some manual customization to the rootfs. 224 manual: (optional) 225 # Create directories in the rootfs of the image 226 make-dirs: (optional) 227 - 228 # The path to the directory to create 229 # Every intermediate directories missing on the path 230 # will be created. 231 path: <string> 232 # Permissions to give to the directory and any missing 233 # intermediate directories. 234 permissions: <uint32> 235 # Copies files from the host system to the rootfs of 236 # the image. 237 copy-file: (optional) 238 - 239 # The path to the file to copy. 240 # The given path will be interpreted as relative to the 241 # path of the image definition file if is not absolute. 242 source: <string> 243 # The path to use as a destination for the copied 244 # file. The location of the rootfs will be prepended 245 # to this path automatically. 246 destination: <string> 247 # Creates empty files in the rootfs of the image. 248 touch-file: (optional) 249 - 250 # The location of the rootfs will be prepended to this 251 # path automatically. 252 path: <string> 253 # Chroots into the rootfs and executes an executable file. 254 # This customization state is run after the copy-files state, 255 # so files that have been copied into the rootfs are valid 256 # targets to be executed. 257 execute: (optional) 258 - 259 # Path inside the rootfs. 260 path: <string> 261 # Any additional users to add in the rootfs 262 # We recommend using cloud-init when possible and fallback 263 # on this method if not possible (e.g performance issues) 264 add-user: (optional) 265 - 266 # The name for the user 267 name: <string> 268 # The UID to assing to this new user 269 id: <string> (optional) 270 # Password. This can be a plain text or a hashed value. 271 # This password will immediately expire and force the user to 272 # renew it at first login. 273 password: <string> (optional) 274 # Type of password submitted above. Defaults to "hash" 275 password-type: text | hash (optional) 276 add-group: (optional) 277 - 278 # The name of the group to create. 279 name: <string> 280 # The GID to assign to this group. 281 gid: <string> (optional) 282 # Set a custom fstab. The existing one (if any) will be truncated. 283 fstab: (optional) 284 - 285 # the value of LABEL= for the fstab entry 286 label: <string> 287 # where to mount the partition 288 mountpoint: <string> 289 # the filesystem type 290 filesystem-type: <string> 291 # options for mounting the filesystem 292 mount-options: <string> (optional) 293 # whether or not to dump the filesystem 294 dump: <bool> (optional) 295 # the order to fsck the filesystem 296 fsck-order: <int> 297 # Define the types of artifacts to create, including the actual images, 298 # manifest files, changelogs, and a list of files in the rootfs. 299 # If this is not set, only the rootfs will be created. 300 artifacts: (optional) 301 # Used to specify that ubuntu-image should create a .img file. 302 img: (optional) 303 - 304 # Name to output the .img file. 305 name: <string> 306 # Volume from the gadget from which to create the image 307 volume: <string> (optional for single volume gadgets, 308 required for multi-volume gadgets) 309 # Used to specify that ubuntu-image should create a .iso file. 310 # Not yet supported. 311 iso: (optional) 312 - 313 # Name to output the .iso file. 314 name: <string> 315 # Volume from the gadget from which to create the image 316 volume: <string> (optional for single volume gadgets, 317 required for multi-volume gadgets) 318 # Specify parameters to use when calling `xorriso`. When not 319 # provided, ubuntu-image will attempt to create it's own 320 # `xorriso` command. 321 xorriso-command: <string> (optional) 322 # Used to specify that ubuntu-image should create a .qcow2 file. 323 # If a .img file is specified for the corresponding volume, the 324 # existing .img will be re-used and converted into a qcow2 image. 325 # Otherwise, a new raw image will be created and then converted 326 # to qcow2. 327 qcow2: (optional) 328 - 329 # Name to output the .qcow2 file. 330 name: <string> 331 # Volume from the gadget from which to create the image 332 volume: <string> (optional for single volume gadgets, 333 required for multi-volume gadgets) 334 # A manifest file is a list of all packages and their version 335 # numbers that are included in the rootfs of the image. 336 manifest: 337 # Name to output the manifest file. 338 name: <string> 339 # A filelist is a list of all files in the rootfs of the image. 340 filelist: 341 # Name to output the filelist file. 342 name: <string> 343 # Not yet supported. 344 changelog: 345 name: <string> 346 # A tarball of the rootfs that has been built by ubuntu-image. 347 rootfs-tarball: 348 # Name to output the tar archive. 349 name: <string> 350 # Type of compression to use on the tar archive. Defaults 351 # to "uncompressed" 352 compression: uncompressed (default) | bzip2 | gzip | xz | zstd (optional) 353 354 The following sections detail the top-level keys within this definition, 355 followed by several examples. 356 357 358 name 359 ==== 360 361 This mandatory meta-data field is not yet used, but must not be blank. 362 Any characters are permitted, of any (non-zero) length. For example: 363 364 .. code:: yaml 365 366 name: ubuntu-server-raspi 367 368 369 display-name 370 ============ 371 372 This mandatory meta-data field is not yet used, but must not be blank. 373 Any characters are permitted, of any (non-zero) length. For example: 374 375 .. code:: yaml 376 377 display-name: Ubuntu Server for Raspberry Pi 378 379 380 revision 381 ======== 382 383 This optional meta-data field is not yet used. If specified, it must 384 be an integer number. 385 386 387 architecture 388 ============ 389 390 This mandatory field specifies the architecture of the image to be created. It 391 must be one of the following valid strings: 392 393 * amd64 394 * armhf 395 * arm64 396 * s390x 397 * ppc64el 398 * riscv64 399 400 For example: 401 402 .. code:: yaml 403 404 architecture: arm64 405 406 407 series 408 ====== 409 410 This mandatory field specifies the Ubuntu release name as it should appear in 411 apt sources. For example, to produce an image for the 20.04 release, this 412 should be "focal". Example values include: 413 414 * bionic 415 * focal 416 * jammy 417 * kinetic 418 419 Please consult the `Releases <https://wiki.ubuntu.com/Releases>`_ page for 420 currently valid release names, but bear in mind that release names must be 421 specified as they would appear in apt sources, i.e. lower-cased with no numeric 422 part and no "LTS" suffix. 423 424 For example: 425 426 .. code:: yaml 427 428 series: jammy 429 430 431 class 432 ===== 433 434 This mandatory field specifies the image classification. It is currently 435 unused, and must be set to the string "preinstalled". In future, the set of 436 valid strings is intended to be: 437 438 * preinstalled 439 * installer 440 * cloud 441 442 For example: 443 444 .. code:: yaml 445 446 class: preinstalled 447 448 449 kernel 450 ====== 451 452 This optional key specifies an additional kernel to include in the image. If 453 specified, the value should be a string that represents the name of the 454 kernel package to be installed. 455 456 .. code:: yaml 457 458 kernel: linux-image-generic 459 460 461 gadget 462 ====== 463 464 This optional field specifies from where the gadget tree will be sourced. 465 Support is included for prebuilt gadgets, building gadgets from a local 466 directory, or building gadgets from a git repository. If gadget is not 467 included in the image definition, but some disk output (img, qcow2, iso) 468 is included, an error will occur. Gadget should only be excluded if the 469 only artifact that you will be creating is a rootfs tarball. 470 471 Examples 472 ======== 473 474 Note that not all of these fields are required. An example used to build 475 Raspberry Pi images is: 476 477 .. code:: yaml 478 479 name: ubuntu-server-raspi-arm64 480 display-name: Ubuntu Server Raspberry Pi arm64 481 revision: 2 482 architecture: arm64 483 series: noble 484 class: preinstalled 485 kernel: linux-image-raspi 486 gadget: 487 url: "https://git.launchpad.net/snap-pi" 488 branch: "classic" 489 type: "git" 490 rootfs: 491 archive: ubuntu 492 sources-list-deb822: true 493 components: 494 - main 495 - restricted 496 - universe 497 - multiverse 498 mirror: "http://ports.ubuntu.com/ubuntu-ports/" 499 pocket: updates 500 seed: 501 urls: 502 - "git://git.launchpad.net/~ubuntu-core-dev/ubuntu-seeds/+git/" 503 branch: noble 504 names: 505 - server 506 - server-raspi 507 - raspi-common 508 - minimal 509 - standard 510 - cloud-image 511 - supported-raspi-common 512 customization: 513 cloud-init: 514 user-data: | 515 #cloud-config 516 name: ubuntu 517 password: ubuntu 518 extra-snaps: 519 - name: snapd 520 fstab: 521 - label: "writable" 522 mountpoint: "/" 523 filesystem-type: "ext4" 524 dump: false 525 fsck-order: 1 526 - label: "system-boot" 527 mountpoint: "/boot/firmware" 528 filesystem-type: "vfat" 529 mount-options: "defaults" 530 dump: false 531 fsck-order: 1 532 artifacts: 533 img: 534 - name: ubuntu-24.04-preinstalled-server-arm64+raspi.img 535 manifest: 536 name: ubuntu-24.04-preinstalled-server-arm64+raspi.manifest