Anka Cloud Gitlab Executor

Veertu’s Anka and the new Anka Cloud Gitlab Executor

Veertu’s Anka is a suite of software tools built on the macOS virtualization platform. It enables the execution of single or multi-use macOS virtual machines (VMs) in a manner similar to Docker. Anka is specifically designed for DevOps and CI/CD teams, large or small, that need to build and test macOS or iOS applications. Leveraging the official Apple hypervisor/virtualization technology, Anka offers enhanced performance and security.

The Anka Build Cloud serves as a unified management interface for Anka Build Nodes (hosts), VM instances, VM Templates/Tags, and logs. It features intelligent queueing and load balancing for handling numerous concurrent CI/CD job macOS VM requests. Additionally, it integrates with widely-used CI/CD servers and tools such as Jenkins, Github Actions, Buildkite, TeamCity, GitLab, and provides an API for custom integrations.

For many years, Veertu has provided a forked version of the official Gitlab Runner code with the Anka executor built into it. Users would typically use the binaries we built and deploy/run them alongside the official Gitlab Runners they may already be using for non-macOS jobs. This seemed to work just fine for most customers, but often the versions of the core Gitlab Runner code would drift and fall behind. We attempted to merge the Anka executor into the official GitLab Runner repo so it would be included in every release, but it was rejected by the official runner team.

The GitLab maintainers realized that maintaining merge requests for the built-in executors was a massive maintenance burden and in version 12.1 released Gitlab Runner Custom Executors that vendors could use to load their executors into the runner without needing any changes to the base Gitlab code. Once the Gitlab Runner Custom Executor matured enough, we decided to shift our focus to building our own Custom Executor: The Anka Cloud GitLab Executor.

Getting started using the Anka Cloud Gitlab Executor

1. Prerequisites

1. Install and Register a self-managed Gitlab Runner (more info).
2. An active Anka Build Cloud.
3. An Anka VM Template in the Anka Build Cloud Registry with git installed, Remote Login enabled, and SSH port forwarding configured (more info).

2. Installation

Download the Binary:

LATEST_VERSION="$(curl -IkLs -o NUL -w %{url_effective} https://github.com/veertuinc/anka-cloud-gitlab-executor/releases/latest | rev | cut -d/ -f1 | rev)"
curl -LO https://github.com/veertuinc/anka-cloud-gitlab-executor/releases/download/${LATEST_VERSION}/anka-cloud-gitlab-executor_Linux_x86_64
chmod +x anka-cloud-gitlab-executor_Linux_x86_64

Create the `executor-template.toml`:

GITLAB_RUNNER_CUSTOM_EXECUTOR_FILE_NAME="anka-cloud-gitlab-executor_Linux_x86_64"
cat > custom-executor.template.toml <<BLOCK
[[runners]]
  [runners.custom]
    config_exec = "/mnt/${GITLAB_RUNNER_CUSTOM_EXECUTOR_FILE_NAME}"
    config_args = ["config"]
    prepare_exec = "/mnt/${GITLAB_RUNNER_CUSTOM_EXECUTOR_FILE_NAME}"
    prepare_args = ["prepare"]
    run_exec = "/mnt/${GITLAB_RUNNER_CUSTOM_EXECUTOR_FILE_NAME}"
    run_args = ["run"]
    cleanup_exec = "/mnt/${GITLAB_RUNNER_CUSTOM_EXECUTOR_FILE_NAME}"
    cleanup_args = ["cleanup"]
BLOCK

Set the Runner’s config.toml environment to point to the Anka Build Cloud Controller:

environment = [ "ANKA_CLOUD_CONTROLLER_URL=http://{controller address and port here}" ]

3. Mount the location of the executor binary into the runner’s container at /mnt.

Usage

Once the GitLab Runner and Anka Executor are running, you can now target it in your job’s .gitlab-ci.yml. We’ll use this as our example:

build:
  tags:
    - localhost-shared
  stage: build
  variables:
    ANKA_CLOUD_TEMPLATE_ID: "5d1b40b9-7e68-4807-a290-c59c66e926b4"
    ANKA_CLOUD_TEMPLATE_TAG: "v1"
  script:
    - hostname
    - echo "Echo from inside of the VM!"
    - sleep 20

In the above example, we define the Runner Tag, Anka VM Template ID, VM Tag, and commands that will run inside of the Anka macOS VM.

Once the job is executed, the runner will request a VM start on one of the Anka Build Cloud Nodes, and once the VM is ready, SSH into it and execute the commands in the script section.

That’s all you need to get started! Take a look over the Anka Cloud GitLab Executor documentation and feel free to reach out to [email protected] for any questions you may have.