Node Capacity Modes

The agent on each Anka Node decides if the Node can accept a start VM task. The capacity mode sets the rule that the agent uses for this decision.

If the agent cannot accept a task, it releases the task back to the Controller queue. Another Node can then take the task. If no Node can take the task, the instance stays in the Scheduling state. Refer to VM is stuck at scheduling.

Number Mode

Number mode is the default. The agent counts the managed VMs on the Node that are in the running or failed state. If this number is less than the VM limit, the agent accepts the task.

A failed VM uses a slot until you terminate the instance.

Number mode does not examine the CPU or RAM of the VM Template. If large VMs start on a small host, the VMs can use more CPU and RAM than the host has. This can make the host and the VMs slow.

To set the VM limit, use one of these procedures:

• Join the Node with --max-vm-count (default 2).
• In the Controller UI, open the Nodes page and use Change Node Configuration.
• Send max_vm_count to the Update Node API.

On Apple silicon, you cannot set a VM limit of more than 2. The agent and the Controller reject the value. The --ignore-arm-vm-limit join flag removes this limit.

Resource Mode

In resource mode, the agent does these steps for each start VM task:

1. It gets the CPU core count and the RAM size of the VM Template and Tag from the Registry.
2. It calculates the free vCPUs and the free RAM on the Node.
3. It accepts the task only if the free vCPUs and the free RAM are both equal to or more than the VM Template needs.

Use resource mode when your VM Templates have different sizes, or when you do not want the VMs to use more RAM than the host has.

How the agent calculates free resources

An override value replaces the calculation. The agent does not multiply --vcpu-override by 2, and it does not subtract 2 GB from --ram-override.

On Apple silicon, the limit of 2 running VMs also applies in resource mode. Resource mode prevents too many resources from being used. It does not increase the number of VMs that a Node can run. The --ignore-arm-vm-limit join flag removes this limit.

Example

The host is an Apple silicon Mac with 8 performance cores and 32 GB of RAM. In resource mode, the total is 16 vCPUs and 30 GB of RAM. The VM Template has 8 vCPUs and 16 GB of RAM.

In resource mode, the second task goes back to the queue. A Node with enough free resources can start it.

CPU and RAM overrides in the start VM request

The Start VM instances API accepts vcpu and vram (in MB) to change the size of the VM. By default, the resource check uses the VM Template values and ignores these overrides. Because of this, a request for more RAM than the VM Template has can start on a Node that does not have that RAM free.

In version 1.50.0 and later, join the Node with --force-overrides-in-resource-mode. Then the resource check uses the vcpu and vram values from the request when they are more than 0.

Set the Capacity Mode

When you join the Node

sudo ankacluster join http://anka.controller \
  --capacity-mode resource

To set your own limits and to use the start VM request overrides in the check:

sudo ankacluster join http://anka.controller \
  --capacity-mode resource \
  --vcpu-override 12 \
  --ram-override 24 \
  --force-overrides-in-resource-mode

To see the mode that the agent uses, run sudo ankacluster status and find capacity_mode in the output. Refer to Preparing and joining your nodes for all of the ankacluster join flags.

With the Controller API

Send capacity_mode, vcpu_override, and ram_override to the Update Node API. You do not have to join the Node again.

curl -X POST "http://anka.controller/api/v1/node/config" -H "Content-Type: application/json" \
  -d '{"node_id": "f8707005-4630-4c9c-8403-c9c5964097f6", "capacity_mode": "resource", "vcpu_override": 12, "ram_override": 24}'

The Change Node Configuration dialog in the Controller UI does not set the capacity mode. Use the API or join the Node again. You can set --force-overrides-in-resource-mode only when you join the Node.

Capacity in the Controller

The List Nodes API shows capacity_mode, vcpu_override, and ram_override for each Node.

The meaning of the capacity value changes with the mode:

• In number mode, capacity is the VM limit.
• In resource mode, capacity is the number of free vCPUs on the Node. If the Node has no free RAM, capacity is 0.

The Controller UI shows the same value on the Nodes page.

Troubleshooting

The agent writes the result of each capacity check to /var/log/veertu/anka_agent.INFO:

❯ grep -E "Resources check|capacity available" /var/log/veertu/anka_agent.INFO
... preRunCheck: capacity available: false
... Resources check to evaluate if VM can run: CPUs: required 8, available: 8; RAM: required 16 GB, available: 14 GB

• capacity available: false tells you that the Node rejected the task because of the capacity mode.
• The Resources check line shows the required and the available vCPUs and RAM in resource mode.

In resource mode, the Node must get the VM Template information from the Registry. If it cannot, the agent writes failed getting vm info from registry to the log and rejects the task.