Components

Ambient runs actions in a virtual machine (VM) to build and test software. To be safe and secure any code from the software under test (SUT) is only run in the VM, which has no network access and set limits on the resources it can use. For actions that require network access, Ambient will run vetted code to download dependencies or publish artifacts.

For performance, Ambient keeps the downloaded dependencies in a directory. This avoids wasting time and bandwidth on downloading the same files every run. Likewise for performance, Ambient maintains a cache of temporary build outputs, such as compiled object files, to allow builds to be incremental.

In the diagram below, the cyan circle is the Ambient program itself. Green ellipses are external hosts and services. Yellow cylinders are persistent storage between Ambient runs. Pink file is the temporary tar archives used to pass data in and out of the VM safely and securely. Solid arrows are network transfers, dashed arrows are local storage transfers.

Tar archives are used to transfer data into and out of the VM. Tar is a relatively simple format that is implemented fully in user space without any involvement by the kernel. In contrast, file system images are tricky and prone to be exploits that causes the host (not VM) kernel to panic. The tar archives are constructed and unpacked by Ambient as needed.

A CI run

When Ambient runs CI for a project, the process is as follows:

  • inspect source tree, download any dependencies it needs that aren't already downloaded
  • create an execute tar with the ambient-execute-plan binary and the "runnable plan"
  • package source tree, dependencies, and cache into tar archives
  • create an empty tar for artifacts
  • run QEMU with the tars as virtual block devices
    • the VM unpacks the execute tar and invokes the program it contains
  • unpack artifacts tar
  • run any post-plan actions to publish artifacts

The execute tar contains both a "runnable plan", which is a sequence of actions to do inside the VM, and a program to execute the actions. VM is either specially constructed for use with Ambient, or supports cloud-init. In either case, it unpacks the execute tar into a temporary directory, and execute the program contained therein. This design allows Ambient to make changes its component that actually executes within the VM, and removes the need for the VM to be updated whenever the program is changed.

The cache and artifacts tar archives are created as sparse files with the size configured for them. This prevents the VM from storing more data in them than is allowed.

The run log

When Ambient runs QEMU, it creates a virtual serial port and connects the standard output and error to that when running the executor program. This means the run log is whatever is written to the serial port. Dependintg on the VM image this can start with BIOS/UEFI output from the VM.

The run log is captured by Ambient, and may require post-processing to be usable by developers of the software under test.