API Node Affinity
How to target a specific group of nodes for deployment using tags with the Orka API.
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):
- Assign the tag to a node or a group of nodes
- 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.
Updated over 1 year ago