Parallels Desktop for Mac

This provisioner allows Stretchy to run jobs on virtual machines managed by Parallels Desktop for Mac. Virtual machines are created on demand by cloning another virtual machine that acts as an image.

Identifier

PARALLELS

Status

Preview

Since

0.1.0

Maintained by

Stretchy developers

Supported Platforms

Host:

  • macOS

Guest:

  • Linux

  • macOS

  • Windows

Nested virtualization is possible if supported by the host’s hardware.

Hardware Requirements

The Parallels provisioner does not require additional resources beyond the minimum requirements of Stretchy Node Agent.

Images are cloned using copy-on-write. That means you need enough free space to store the virtual machine images to be cloned, plus whatever additional data is written to disk by the jobs.

Software Requirements

Host

You need at least the Pro Edition of Parallels Desktop for Mac. The Standard Edition is not sufficient and will not work.

Guests

  • Parallels Tools

  • OpenSSH

  • sudo, systemd (Linux)

  • sudo (macOS)

Host Configuration

prlctl must be on the search path. To validate whether prlctl is working correctly, run the following command as the user Stretchy Node Agent is running as:

prlctl list --all

The output should list the virtual machines that you want to use with Stretchy.

Agent Configuration

Apart from setting the provisioner identifier (PARALLELS) and the provisioner parallelism (use 3), no further configuration is necessary.

Never consider increasing the parallelism beyond 3. Despite its name, Parallels Desktop for Mac does not particularly like being used in parallel.

Image Configuration

Install the guest operating system as you normally would, for example, manually with Parallels Desktop for Mac or with packer. All job sources expect a local user named stretchy to be present with a home directory according to Table 1.

Table 1. Expected home directories by system
System family Home directory

Linux

/home/stretchy

macOS

/Users/stretchy

Windows

C:\Users\stretchy
Some Linux distributions, notably Ubuntu, use /etc/machine-id to request an IP address using DHCP. Ensure that each guest has a unique /etc/machine-id and, therefore, IP address.
We highly recommend employing cloud-init to set the virtual machine’s hostname, to replace its SSH host key, and to change any passwords when the guest boots for the first time.
Automatic updates can slow down or even interrupt the execution of jobs. Therefore, we recommend disabling automatic updates on all guest systems.

Then, install all required software, including your job source’s agent.

If jobs should be able to access a graphical user interface, for example, to perform GUI testing, automatic login must be enabled on macOS and Windows for the user stretchy. On macOS, the job runner will be started in such a way that it has access to an Aqua session.

The provisioner communicates with the guests over SSH. It tries to log in as user stretchy using public-key authentication. This means that the public SSH key of the user Stretchy Node Agent is running as must be in the authorized_keys file of the user stretchy on the guest.

On Windows, configuring public-key authentication works differently than on other systems, especially for administrators. Please see Microsoft’s article on Key-based authentication in OpenSSH for Windows for details.

Forgejo Runner

Download and extract Forgejo Runner. Put it in the expected place as outlined by Table 2. No further installation or configuration is necessary. Stretchy will take care of it for you.

It is recommended to use the latest version of Forgejo Runner. The oldest supported version is Forgejo Runner 12.8.
Table 2. Programs invoked to start Forgejo Runner
System family Directory

BSD

/usr/local/bin/forgejo-runner

Linux

/usr/local/bin/forgejo-runner

macOS

/usr/local/bin/forgejo-runner

Windows

C:\Users\stretchy\forgejo-runner.exe

GitHub Actions Runner

After installing all dependencies, download and extract the GitHub Actions Runner as explained in its README. Any further configuration or a registration on GitHub is not necessary. Stretchy will do that automatically for you.

The provisioner will start GitHub Actions Runner by invoking the programs listed in Table 3.

Table 3. Programs invoked to start GitHub Actions Runner
System family Directory

Linux

/home/stretchy/actions-runner/run.sh

macOS

/Users/stretchy/actions-runner/run.sh

Windows

C:\actions-runner\run.cmd

Jenkins

After installing a suitable version of Java, download Jenkins' agent.jar from your Jenkins instance (for example, https://jenkins.example.com/jnlpJars/agent.jar) and place it in the home directory of the local user stretchy. The provisioner expects it at the paths listed in Table 4.

Table 4. Programs invoked to start Jenkins Agent
System family Directory

Linux

/home/stretchy/agent.jar

macOS

/Users/stretchy/agent.jar

Windows

C:\Users\stretchy\agent.jar

Image Registration

To register an image in Stretchy Orchestrator, enter the name of the corresponding virtual machine as listed by prlctl list --all into the field Name and PARALLELS into the field Provisioner.

Do not prefix the name of your virtual machines with stretchy-. The Parallels provisioner treats virtual machines prefixed with stretchy- like stretchy-ubuntu as managed machines (virtual machines dynamically created by the provisioner). It might either complain about them or even delete them without asking.

Limitations

  • Apple limits the number of simultaneously running virtual machines with any version of macOS to two.

  • Parallels Desktop for Mac has fewer capabilities on computers with Apple’s ARM chips than on those with Intel processors. See Known limitations of macOS virtual machines on Mac computers with Apple Silicon in Parallels' knowledge base for details.

  • Parallels Desktop for Mac can suffer from severe performance degradation if a single virtual machine is cloned hundreds of times over its lifetime. The problem manifests itself with very high CPU usage. The remedy is to manually remove all snapshots and restart Parallels Desktop for Mac. We have reported the issue to Parallels in 2024.