Copy page

Features

Branching

Branching lets you create a clone (a branch) of an existing instance, including its memory and volume state. The branch is an identical but independent copy of the source. It starts from the same memory state instead of going through a cold boot, and from then on runs on its own without affecting the source.

This resembles creating an instance from an instance template, but the source must be an ordinary instance, not a template.

How it works

Branching builds on copy-on-write (CoW) asynchronous snapshotting. When you create a branch, Unikraft Cloud snapshots the source instance's memory and volume state. The snapshot becomes the starting point for the new instance. Because the snapshot is copy-on-write and taken asynchronously, the source instance only pauses for a few milliseconds before it resumes running.

The source instance's state determines how Unikraft Cloud populates the branch:

Source state	Behavior
Running	Unikraft Cloud takes an asynchronous CoW snapshot of the source. The branch waits for that snapshot to complete and then starts from it.
Stopped or Standby	Unikraft Cloud creates the branch right away from the source's existing snapshot, or from its image if the source has none.

Creating a branch

To create a branch, pass the source instance to --branch:

Code
unikraft instance create --metro fra \
  --name my-branch \
  --branch my-instance

You can also reference the source by its UUID instead of its name. Use unikraft run --branch instead of unikraft instance create --branch to create the branch and follow its logs in one step.

Apart from the branch source, a branch accepts the same options as a regular instance creation. You can attach ROMs and volumes, configure a service, and set other options as when you create an instance from a template.

What the branch inherits

A branch derives the following from its source, so you can't set these fields in the create request:

• The image (--image)
• The number of vCPUs (--vcpus)
• The memory size (--memory)
• The app arguments (--args)
• The environment variables (--env)
• The memory and volume state at the time of the snapshot

Setting any of these alongside a branch source makes the request fail (see Error handling).

You can still give the branch its own configuration, as when instantiating a template, including a name, ROMs, volumes, and a service.

Error handling

The CLI rejects --branch alongside --image, --template, or --checkpoint before it sends anything, with only one of --image, --template, --branch, or --checkpoint may be specified. It also rejects a source in a different metro from the new instance, with cannot create instance: metro mismatch between branch ("fra") and instance ("dal2"). Otherwise, a branch request can fail for the following reasons:

Error message	Cause
Cannot specify 'image' when 'branch_from' is set	The request sets both image and branch_from. A branch derives its image from the source.
Cannot specify 'branch_from' when creating an instance from a template	The request sets both template and branch_from. Choose one creation source, not both.
Cannot specify '<field>' when branching from an existing instance	The request sets a field the branch inherits from its source (args, env, memory_mb, or vcpus).
Cannot branch from VM with pending snapshot	The source already has a snapshot in progress. Retry once it completes.
Cannot branch from VM in state '<state>'	The source is in a state that branching doesn't support.
Insufficient license. Please make sure your license is valid and includes branching	Your account's license doesn't include the branching feature.

Limitations

• A branch must stay in the metro of its source. The CLI catches a cross-metro source before it sends the request.
• Branching needs the default micro instance type. QEMU-backed full VMs (type: full), which GPU instances require, don't support branching, and a create request can't combine type with a branch source.
• Branching only works with block-based volumes (for example, ext4). The branch clones the source's volume state consistently with its memory snapshot, which isn't supported for other volume types.
• On BYOC and on-prem installations, branching requires a license that includes the feature.

Learn more

• Instance templates: create instances from a stopped, snapshotted template.
• Instance forking: create a copy of an instance from within the instance itself.
• Serverless databases: a use case that branches a running PostgreSQL instance to clone its state.
• Unikraft Cloud's REST API reference, in particular the create instance endpoint.