Skip to content

Tool reference

An agent is offered only the tools its key’s permissions allow. A key with read on clusters alone sees list_clusters and get_cluster, and nothing else.

Tool Needs Does
list_clusters Clusters: read Lists the account’s clusters with their status, region and version.
get_cluster Clusters: read One cluster, with its status, endpoint, region and Kubernetes version.
list_node_pools Node pools: read The node pools of a cluster, with their node size and count.
resize_node_pool Node pools: write Changes a pool’s number of nodes. Changes billing.
update_node_pool_labels_and_taints Node pools: write Replaces a pool’s Kubernetes labels and taints, on every node. Can move workloads.
list_nodes Nodes: read The nodes of a cluster, or of one pool, with their status and addresses.
restart_node Nodes: write Restarts one node. Interrupts its workloads.
list_activity Activity: read Recent activity in the account, newest first, optionally for one cluster.

IDs come from the list tools: an agent typically lists first, then acts on what it found.

Input Required
limit no How many to return, at most 100. Default 20.
offset no How many to skip, for paging.
Input Required
cluster_id yes The cluster’s ID.
Input Required
pool_id yes The node pool’s ID.
nodes yes The number of nodes the pool should have, 1 to 20.

Adding nodes is billed from when they start; removing nodes evicts the workloads on them. A cluster’s last worker nodes cannot be removed.

Input Required
pool_id yes The node pool’s ID.
labels no Every label the nodes should have, as an object of key to value. Left out, the labels stay as they are.
taints no Every taint the nodes should have, each with a key, an optional value and an effect (NoSchedule, PreferNoSchedule or NoExecute). Left out, the taints stay as they are.

What is given replaces the whole set; an empty one removes them all. Every node in the pool must be running. A NoExecute taint evicts the pods that do not tolerate it. See Node labels and taints.

Input Required
cluster_id yes The cluster’s ID.
pool_id no Only this node pool’s nodes.
Input Required
node_id yes The node’s ID.

The node reboots, which takes a few minutes; its workloads are interrupted meanwhile.

Input Required
cluster_id no Only this cluster’s activity.
limit no How many to return, at most 100. Default 20.
offset no How many to skip, for paging.

Tools answer with the same JSON the REST API returns, so the field reference applies to both. When Hyperkub refuses a call, the tool returns an error with the HTTP status and Hyperkub’s message — for example 404: cluster not found — which the agent can read and act on.