Building Container-Optimized OS from source

Container-Optimized OS is based on, and built using, tools from the open-source Chromium OS project. If you like, you can build a Container-Optimized OS image yourself directly from the Container-Optimized OS source code.

Prerequisites

To build a Container-Optimized OS image, you'll need to install the following tools on your development machine:

  • git and curl
  • A package of Chromium scripts called depot_tools that includes tools like repo and cros_sdk.

Obtaining the Container-Optimized OS source code

You can download the source code for Container-Optimized OS by using the repo tool that is included in depot_tools.

First, create a directory to store the source code. For example, cos-src in your home directory:

mkdir $HOME/cos-src
cd $HOME/cos-src

Now download source code using the following commands:

repo init https://cos.googlesource.com/cos/manifest.git
repo sync

Building a Container-Optimized OS image

To build Container-Optimized OS, you must create a suitable chroot environment. You can use the cros_sdk tool included in depot_tools to create and enter a chroot that's ready for Container-Optimized OS compilation by running the following command in the source directory that you created in the previous step:

cd $HOME/cos-src
cros_sdk --enter

Once inside chroot, you can build the disk image. To build Container-Optimized OS, specify lakitu (x86 image) or lakitu-arm64 (Arm image) for the board name as follows:

x86 image

   build_packages --board=lakitu
   build_image --board=lakitu test

Arm image

   build_packages --board=lakitu-arm64
   build_image --board=lakitu-arm64 test

In addition to test, you can build either a base, or dev image by passing the appropriate parameter to the ./build image script command. If you don't specify a parameter, the dev image is built by default.

The dev image contains some additional debug tools installed on top of the base image. The test image includes the debug tools from the dev image as well as tools necessary for running automatic Container-Optimized OS tests.

Attribution Requirements

When you produce a Container-Optimized OS image, you need to fulfill various attribution requirements of third party licenses. The image generated by a build contains all relevant attribution information in /opt/google/chrome/resources/about_os_credits.html. As a separate build artifact it is also available as license_credits.html file in the build output directory.

Running Your Image

Once you've built your Container-Optimized OS image, you can run the image using KVM, or import the image to a Compute Engine instance.

Running in hypervisor

To boot your image in hypervisor, run the following command:

x86 image

   kvm -m 1024 -nographic -net nic,model=virtio -net user,hostfwd=tcp:127.0.0.1:9222-:22 -hda src/build/images/lakitu/latest/chromiumos_test_image.bin

Arm image

   sudo apt-get install qemu-system-arm qemu-efi

   dd if=/dev/zero of=/tmp/flash0.img bs=1M count=64
   dd if=/usr/share/qemu-efi/QEMU_EFI.fd of=/tmp/flash0.img conv=notrunc

   sudo qemu-system-aarch64 -m 1024 -cpu cortex-a57 -M virt -nographic \
         -pflash /tmp/flash0.img \
         -device virtio-scsi-pci,id=scsi \
         -drive if=none,file=src/build/images/lakitu-arm64/latest/chromiumos_test_image.bin,id=hd0 \
         -device scsi-hd,drive=hd0,bootindex=0 \
         -net nic \
         -net user,hostfwd=tcp::9222-:22

Booting in this manner leaves the VM's serial port connected to your console, letting you log in without using SSH. If you're running a test image, you can log in with the username/password pair "root/test0000".

Once the VM is started, you can access your dev or test image using SSH. To SSH into the image, use the key generated for that image, as follows:

x86 image

   ssh root@localhost -p 9222 -i src/build/images/lakitu/latest/id_rsa

Arm image

   ssh root@localhost -p 9222 -i src/build/images/lakitu-arm64/latest/id_rsa

Running on Compute Engine

To import your image to a Compute Engine instance, you must compress the image into a .tar file. To compress the image, run the following command:

x86 image

   tar -Sczf compressed-image.tar.gz images/lakitu/latest/chromiumos_image.bin --transform 's|images/lakitu/latest/chromiumos_image.bin|disk.raw|'

Arm image

   tar -Sczf compressed-image.tar.gz images/lakitu-arm64/latest/chromiumos_image.bin --transform 's|images/lakitu-arm64/latest/chromiumos_image.bin|disk.raw|'

After you've created your .tar file, you can follow the instructions to import an existing image in the Compute Engine documentation.