API Node Affinity

📘

Orka 2.4.x content

This page has not been updated to reflect the changes introduced in Orka 3.0. Some of the information might be outdated or incorrect. Use 2.4.x to 3.0.0: API Mapping and 2.4.x to 3.0.0: CLI Mapping to figure out the correct endpoints and commands.

🚧

Quick navigation

Jump to: 1a. Tagging nodes | 1b. Untagging nodes | 2a. Configuring the VM tag settings | 2b. Overriding the VM tag settings

See also: How does node affinity work | Caveats

🚧

Quick request summary

curl POST /resources/node/tag/<tag>
curl DEL /resources/node/tag/<tag>
curl POST /resources/vm/create
curl POST /resources/vm/deploy

If you need to target a specific node or group of nodes during deployment, you can use node affinity (also: node tagging). Based on the tag required setting, Orka might or might not attempt to deploy on other nodes if the deployment to the tagged node(s) fails.

Node affinity consists of two parts (performed in the specified order any number of times within the current limitations of the feature):

1. Assign the tag to a node or a group of nodes
2. Create a VM config with the tag and specify if the tag is required OR apply the tag during deployment and specify if it's required

1a. Tagging nodes

This is an administrative operation and requires license authentication.

You can add one tag to one node at a time. One node can have multiple tags.

Send a POST request to the http://<Orka-API-URL>/resources/node/tag/<tag> endpoint. The body of the request must contain the "orka_node_name": "<node-name>" argument.

For example:

curl --location --request POST 'http://<orka-api-ip>/resources/node/tag/<tag>' \
--header 'Content-Type: application/json' \
--header 'orka-licensekey: <license-key>' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
	"orka_node_name": "<node-name>"
}'

Replace <orka-api-ip> with 10.221.188.20, 10.221.188.100, or your Orka domain, or your external custom domain. Note that for Orka and custom domains you need to switch to https.
Replace <tag> with the tag that you want to apply.
Replace <license-key> with your actual Orka license key.
Replace <token> with your Orka token.
Replace <node-name> with the name of the node that you want to tag.

1b. Untagging nodes

This is an administrative operation and requires license authentication.

You can remove one tag from one node at a time.

Send a DEL request to the http://<Orka-API-URL>/resources/node/tag/<tag> endpoint. The body of the request must contain the "orka_node_name": "<node-name>" argument.

For example:

curl --location --request DEL 'http://<orka-api-ip>/resources/node/tag/<tag>' \
--header 'Content-Type: application/json' \
--header 'orka-licensekey: <license-key>' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
	"orka_node_name": "<node-name>"
}'

Replace <orka-api-ip> with 10.221.188.20, 10.221.188.100, or your Orka domain, or your external custom domain. Note that for Orka and custom domains you need to switch to https.
Replace <tag> with the tag that you want to remove.
Replace <license-key> with your actual Orka license key.
Replace <token> with your Orka token.
Replace <node-name> with the name of the node that you want to untag.

2a. Configuring the VM tag settings

This is not an administrative operation and requires only token authentication.

You can configure your VM tag settings when you are creating the VM config. These settings will be applied on every deployment, unless explicitly overridden.

You can apply only one tag to a VM config.

Send a POST request to the http://<Orka-API-URL>/resources/vm/create endpoint. The body of the request must contain at least the arguments from the example below. You can set tag_required to true or false.

For example:

curl --location --request POST 'http://<orka-api-ip>/resources/vm/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
	"orka_vm_name": "<vm-name>",
	"orka_base_image": "<base-image>",
	"orka_image": "<vm-name>",
	"orka_cpu_core": <cpu>,
	"vcpu_count": <vcpu>,
  "tag": "<tag>",
  "tag_required": false
}'

Replace <orka-api-ip> with 10.221.188.20, 10.221.188.100, or your Orka domain, or your external custom domain. Note that for Orka and custom domains you need to switch to https.
Replace <token> with your Orka token.
Replace <vm-name> with the name you want to use for our VM config.
Replace <base-image> with the Intel- or Apple silicon-based image that you want to use. For example: 90GBVenturaSSH.orkasi.
Set valid values for <cpu> and <vcpu>.
Replace <tag> with the tag you want to apply.
Set "tag_required" to true or false. When true, Orka will never attempt to deploy on nodes that do not match the tag.

2b. Overriding the VM tag settings

This is not an administrative operation and requires only token authentication.

You can override the VM config settings for tag and tag_required during deployment. The VM config might or might not have any existing tag settings.

You can apply only one tag during deployment.

Send a POST request to the http://<Orka-API-URL>/resources/vm/deploy endpoint. The body of the request must contain "orka_vm_name" and "tag". If you skip "tag_required", Orka will default to the settings within the config or false, if the setting was not configured for the VM config.

For example:

curl --location --request POST 'http://<orka-api-ip>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
	"orka_vm_name": "<vm-name>",
	"tag": "<tag>",
  "tag_required": false
}'

Replace <orka-api-ip> with 10.221.188.20, 10.221.188.100, or your Orka domain, or your external custom domain. Note that for Orka and custom domains you need to switch to https.
Replace <token> with your Orka token.
Replace <vm-name> with the name of the VM config that you want to deploy.
Replace <tag> with the tag you want to apply.
Set "tag_required" to true or false. When true, Orka will never attempt to deploy on nodes that do not match the tag.

What's next

Create and deploy Orka virtual machines.