ArkService

ArkService routes tasks to available agent instances using round-robin, least-busy, or random load balancing strategies.

API: arkonis.dev/v1alpha1 Kind: ArkService Short name: aosvc Scope: Namespaced

ArkService routes incoming tasks to available agent instances, decoupling task producers from the agent pool. It selects a target ArkAgent and distributes tasks across ready pods using a configurable load balancing strategy.

Example

apiVersion: arkonis.dev/v1alpha1
kind: ArkService
metadata:
  name: research-service
  namespace: default
spec:
  selector:
    arkAgent: research-agent
  routing:
    strategy: least-busy
  ports:
    - protocol: HTTP
      port: 8081

Routing strategies

StrategyBehavior
round-robinDistributes tasks sequentially across all ready pods. Simple and predictable.
least-busyRoutes each task to the pod with the fewest active tasks. Best for tasks with variable duration.
randomSelects a ready pod at random. Useful for even distribution without tracking state.

Only pods with a passing /readyz check are eligible. Pods that fail the semantic readiness probe are excluded until they recover.

Spec reference

spec

FieldTypeRequiredDefaultDescription
selectorServiceSelectoryes—Identifies the target ArkAgent.
routingRoutingSpecno—Task routing configuration.
ports[]PortSpecno—Ports exposed by the service.

spec.selector

FieldTypeRequiredDescription
arkAgentstringyesName of the ArkAgent in the same namespace to route tasks to.

spec.routing

FieldTypeDefaultDescription
strategystringround-robinround-robin, least-busy, or random.

spec.ports[]

FieldTypeRequiredDescription
protocolstringyesHTTP — external task submission. A2A — agent-to-agent communication.
portintyesPort number.

status

FieldTypeDescription
readyReplicasint32Number of ready agent pods currently receiving tasks.
conditions[]ConditionStandard Kubernetes conditions.

See also

  • ArkAgent — the agent pool that ArkService routes to
  • ArkTeam — for multi-agent pipelines, ArkTeam wires routing automatically