Orka 2.0 has arrived, and with it, several new features have been introduced including the ability to tag nodes and deploy VMs to nodes with that tag!

What is Node Tagging?

Node tagging gives you the option to put as many tags on an Orka node as you want and then use those tags to tell VMs where to deploy. These tags can be almost any set of words you want them to be. For example, you might choose “ci” for your CI runners, or you might choose “devteam” if you want to give your dev team specific nodes to target without completely locking them down with groups, etc.

The Problem

Imagine your Orka cluster has 3 worker nodes with 12 vCPU each.

On a regular day, you have 6 VMs with 3 vCPUs each spread over those 3 worker nodes, and you don’t really need to know which nodes are which. However, the day before a code freeze, suddenly your developers are running dozens of CI processes and you run out of space on your nodes for other work!

You could create a group and dedicate some nodes to CI and only deploy CI runners there, but then you can’t use those nodes for anything else.

How Does Node Tagging Help?

Instead of dedicating some nodes to CI, you can tag a few nodes with “ci-pool”, for example, and then use that tag when deploying CI VMs. Additionally, you can choose if the VM must deploy to that tag, or if it just prefers to deploy to that tag.

When the CI VM attempts to deploy to “ci-pool”, one of 3 things will happen:

  1. There is space on a node tagged “ci-pool” → The VM deploys
  2. There is no space on a node tagged “ci-pool” and the VM requires that tag → The VM fails to deploy and returns an error. This will help in the situation where minor CI processes kicked off by devs were filling up the nodes. The devs can just run their CI process later when there is less utilization.
  3. There is no space on a node tagged “ci-pool” and the VM does not require the tag → The VM successfully deploys to a node without the tag. This option can be chosen for processes you want to always be able to deploy (as long as there’s space somewhere in the cluster) even if there isn’t room on a tagged node. For instance, an important integration test or nightly build.

Tagging A Node

For our above example, we’ll need to tag one or more nodes with the tag “ci-pool.”

CLI Example

// Note: CLI tagging requires an administrative user license
// add the tag to the node
orka node tag -n mini-1 --tag ci-pool -y

// verify the tag
orka nodes

// Ex Output:
 orka nodes
   │  Node  │      IP       │   CPU   │     Memory      │ State │ Group │  Tags   │
   │ mini- / 1247.33G / 62.63G │ READY │       │ ci-pool │
   │ mini- / 1247.33G / 62.63G │ READY │       │         │
   │ mini-310.221.188.1312 / 1262.43G / 62.63G │ READY │       │         │
   │ mini-410.221.188.1411 / 1262.30G / 62.63G │ READY │       │         │

API Example

curl --location --request POST '<orka api url>/resources/node/tag/ci-pool' \
--header 'Content-Type: application/json' \
--header 'orka-licensekey: <license-key>' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
	"orka_node_name": "macpro-1"

Deploying a VM to the Tag

CLI Example

// Deploy an existing VM
// Don't require the tag
orka vm deploy -v <vm name> --tag ci-pool -y

// Require the tag
orka vm deploy -v <vm name> --tag ci-pool -y --tagRequired=true

// Create a new VM and save the tag to the configuration
orka vm create -v <vm name> --tag ci-pool -y

API Example

curl --location --request POST '<orka api url>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
	"orka_vm_name": "myorkavm",
	"tag": "ci-pool",
	"tag_required": true


Node tagging is one of the many exciting feature additions to Orka 2.0. It allows teams granular control over which processes are deployed to particular nodes or groups of nodes, which will allow your team much more flexibility in the way that they utilize the compute resources provided by an Orka cluster.

There two fundamental options teams can choose from when employing node tagging in Orka. They can require that a specific process be deployed to a node with a matching tag, or they can give preference to a node that with a matching tag, but still execute the process on any available node should a preferred node not be available.

Share this article


Orka, Orka Workspace and Orka Pulse are trademarks of MacStadium, Inc. Apple, Mac, Mac mini, Mac Pro, Mac Studio, and macOS are trademarks of Apple Inc. The names and logos of third-party products and companies shown on the website are the property of their respective owners and may also be trademarked.

©2023 MacStadium, Inc. is a U.S. corporation headquartered at 3525 Piedmont Road, NE, Building 7, Suite 700, Atlanta, GA 30305. MacStadium, Ltd. is registered in Ireland, company no. 562354.