Cuttlefish: Multi-tenancy

Cuttlefish multi-tenancy allows for your host machine to launch multiple virtual guest devices with a single launch invocation.

These multiple Cuttlefish virtual machines can share some of the host disk resources, allowing you to conserve disk space. Each virtual machine gets a distinct disk overlay covering the Android partitions (such as super, userdata, boot). Any modification to the guest disk is placed in a guest-specific disk overlay, giving each Cuttlefish virtual machine a copy-on-write view of its disk partitions. As each virtual device writes more data to its view of the disk, the overlay files on the host disk increase in size because they're capturing the delta between the original state and their current state.

The overlay files can be reset to return the Cuttlefish disk to its original state. This process is known as powerwashing.

Instance numbers

Cuttlefish devices create and consume resources on the host tied to their instance number. For example, an adb connection is exposed through a TCP server socket at port 6520 for the Cuttlefish device with instance number 1. When multiple instances are launched, it creates a TCP server socket at port 6520 for the first device, 6521 for the second device, and increments the port number for each additional device.

Modifying maximum number of supported instances

Host-side resources, such as TAP network devices, must be preallocated for Cuttlefish virtual machines. By default, the cuttlefish-base Debian package provisions resources for instance numbers 1 through 10.

This can be changed through modifying num_cvd_accounts in /etc/default/cuttlefish-host-resources and restarting the cuttlefish-host-resources service by running the following command:

sudo systemctl restart cuttlefish-host-resources

Controlling multi-tenant instances

This section describes how to start and stop devices. This applies to both single-tenant and multi-tenant launch_cvd invocations.

Starting

To launch multiple Cuttlefish devices at once, use the --num_instances=N flag, where N is the number of devices to launch. By default, devices starts from the instance number 1.

launch_cvd --num_instances=N

To change the starting instance number, do one of the following:

• Add the --base_instance_num=N flag with N as the first instance number.

  launch_cvd --base_instance_num=N
  

• Launch Cuttlefish with a user account matching vsoc-NN, where NN is the base instance number in two digit form. For example, to launch Cuttlefish with a user account vsoc-01, run:

  launch_cvd --base_instance_num=1
  

Stopping

Note: When used in a multidevice environment, the stop procedure is applied to all devices simultaneously.

To stop all the devices launched by the last launch_cvd invocation, run:

stop_cvd