#Layered Builds

A build can take its source from another build's output. This is how you compose a stack of modules, each layering on top of a previous one. In the visual editor, this is the Existing Image source option on a VM; in YAML, it is source.build_ref. See Sources for the field walkthrough.

vms:
    - name: builder
      source:
          build_ref:
              name: base-debian # name of the previous build
              vm_name: builder # required if base has multiple VMs
      resources:
          cpu: 1
          memory: '1Gi'
      provisioners:
          - type: shell
            shell:
                inline: |
                    sudo apt-get install -y postgresql

The referenced build must already be in Succeeded state, otherwise the layered build fails immediately. So your build order matters: run the base build first and wait for it to succeed, then run the layered build that references it.

#Bases you do not own

A base does not have to be your own module. The Base Image dropdown offers three kinds of module, all of which must have a stable build in your organization's deployment zone:

The third row is the interesting one: another organization can publish a foundation for you to build on without giving you any right to change it. You cannot edit or rebuild their module, but you can layer your own on top, and your module is entirely yours. See Sharing a base image.

Because the tag is what exposes a module to consumers this way, only the owning organization can set it. A maintainer can edit the manifest but cannot widen the audience.

Layering on someone else's module tracks their stable build rather than pinning to one image: when they promote a new stable, your next build picks it up. That is usually what you want from a maintained base, but it does mean a base you do not control can change under you. If you need a frozen foundation, copy the manifest into your own module instead.

#Data disks are inherited too

A layer inherits every disk the base VM has — boot disk and any secondary data disks — automatically, content included. You don't need to, and cannot, re-declare a data disk to carry it down the stack; it just comes along.

# Base build
disks:
    - name: rootdisk # boot disk
      size: 40Gi
    - name: secondary
      bus: usb
      size: 1Gi

# A layer on top of the above needs no disks field at all to keep both —
# rootdisk and secondary carry over, secondary's content included.
source:
    build_ref:
        name: base-build

Anything a layer lists in its own disks is purely additional, appended after the full set of inherited disks — it does not replace or resize an inherited one. Naming a layer's disk the same as any inherited disk — boot or secondary — is a hard error, not a way to override it:

additional disk "secondary" collides with an inherited parent disk name; rename it

There's currently no way to opt out of inheriting one specific data disk, or to change its size/bus, while keeping its name — pick a different name for your own disk if you want an extra one alongside the inherited set.

See What disks means depends on the source for the full rules.