conductor-sdk

Capability contract library for Conductor (Compiler, execute mode, agent mode)

What it is

conductor-sdk is a pure Go library. It has no deployable binary and is never installed to a cluster. The Conductor Compiler, Conductor execute mode, and Conductor agent mode all import it.

This library provides:

• Capability name constants: the permanent, immutable identifiers for every named capability the runner supports
• CapabilityManifest and CapabilityEntry types: the self-declared capability list the runner agent publishes to RunnerConfig status on startup
• JobSpecBuilder: the fluent builder operators use to construct Kueue-compatible Job specs
• JobSpec and SecretVolume value types: the shared contract between operator and runner for Job construction
• OperationResultSpec: the complete result document written to a ConfigMap by every runner executor Job before exit
• GenerateFromTalosCluster and GenerateFromPackBuild: RunnerConfigSpec generation functions called by operators at runtime

Module: github.com/ontai-dev/conductor-sdk

Packages

runnerlib

All library code lives in the single runnerlib package. The files and what each provides:

File	Description
constants.go	All capability name constants. Permanent and immutable. Every Capability* constant here is the authoritative identifier used as the CAPABILITY environment variable in runner Jobs.
capability.go	CapabilityManifest, CapabilityEntry, CapabilityMode, and ParameterDef types. Defines the manifest the runner agent publishes to RunnerConfig status on startup.
jobspec.go	JobSpecBuilder interface, JobSpec, SecretVolume value types, NewJobSpecBuilder() constructor, and ResolveNodeExclusionsFromRunnerConfig(). The builder enforces required fields at Build time and maintains value semantics across all With* calls.
generators.go	GenerateFromTalosCluster() and GenerateFromPackBuild(): operator-facing functions that produce a RunnerConfigSpec from a CRD spec. TalosClusterSpec, PackBuildSpec, HelmSource, KustomizeSource, and RawManifestSource input types live here.
operationresult.go	OperationResultSpec, ResultStatus, ArtifactRef, FailureReason, FailureCategory, DeployedResource, and StepResult. The complete result document contract between runner and operator.
packreceipt.go	Package stub. Reserved.
runnerconfig.go	Package stub. Reserved.

Capability constants

All capability names in constants.go are permanent and immutable. Renaming a capability is forbidden. Fundamental behavior changes require a new name.

Platform capabilities (cluster lifecycle and operations):

Constant	Value	Trigger
CapabilityBootstrap	bootstrap	TalosCluster creation
CapabilityTalosUpgrade	talos-upgrade	TalosUpgrade CR
CapabilityKubeUpgrade	kube-upgrade	TalosKubeUpgrade CR
CapabilityStackUpgrade	stack-upgrade	TalosStackUpgrade CR
CapabilityNodePatch	node-patch	TalosNodePatch CR
CapabilityNodeScaleUp	node-scale-up	TalosNodeScaleUp CR
CapabilityNodeDecommission	node-decommission	TalosNodeDecommission CR
CapabilityNodeReboot	node-reboot	TalosReboot CR
CapabilityEtcdBackup	etcd-backup	TalosBackup CR
CapabilityEtcdDefrag	etcd-defrag	EtcdMaintenance CR (operation=defrag)
CapabilityEtcdRestore	etcd-restore	TalosRecovery CR
CapabilityPKIRotate	pki-rotate	TalosPKIRotation CR
CapabilityCredentialRotate	credential-rotate	TalosCredentialRotation CR
CapabilityHardeningApply	hardening-apply	TalosHardeningApply CR
CapabilityClusterReset	cluster-reset	TalosClusterReset CR (requires ontai.dev/reset-approved=true)
CapabilityMachineConfigBackup	machineconfig-backup	TalosMachineConfigBackup CR
CapabilityMachineConfigRestore	machineconfig-restore	TalosMachineConfigRestore CR

Compile mode capabilities (run on workstation or CI, never submitted as a Kueue Job):

Constant	Value	Description
CapabilityPackCompile	pack-compile	Renders PackBuild inputs into a ClusterPack OCI artifact

Dispatcher capabilities (pack delivery):

Constant	Value	Trigger
CapabilityPackDeploy	pack-deploy	PackExecution CR

Guardian capabilities (RBAC plane):

Constant	Value	Description
CapabilityRBACProvision	rbac-provision	Provisions RBAC artifacts from the current PermissionSnapshot

RunnerConfig generation

Operators call GenerateFromTalosCluster or GenerateFromPackBuild to produce a RunnerConfigSpec at runtime. The operator must set RunnerImage on the returned spec before creating the RunnerConfig CR. INV-009: RunnerConfig is always operator-generated at runtime, never human-authored.

import "github.com/ontai-dev/conductor-sdk/runnerlib"

spec, err := runnerlib.GenerateFromTalosCluster(runnerlib.TalosClusterSpec{
    ClusterEndpoint:   "10.20.0.10",
    TalosVersion:      "v1.9.3",
    KubernetesVersion: "v1.32.1",
    InstallDisk:       "/dev/sda",
    ControlPlaneNodes: []string{"10.20.0.11", "10.20.0.12", "10.20.0.13"},
    WorkerNodes:       []string{"10.20.0.14", "10.20.0.15"},
    SeedNodes:         []string{"10.20.0.11"},
})
spec.RunnerImage = "registry.ontai.dev/ontai-dev/conductor:v1.9.3-r1"

Job spec builder

Operators use NewJobSpecBuilder() to construct Job specs before submission to Kueue:

import "github.com/ontai-dev/conductor-sdk/runnerlib"

spec, err := runnerlib.NewJobSpecBuilder().
    WithCapability(runnerlib.CapabilityBootstrap).
    WithClusterRef("my-cluster").
    WithRunnerImage("registry.ontai.dev/ontai-dev/conductor:v1.9.3-r1").
    WithQueueName("platform-system-queue").
    WithOperationResultConfigMap("bootstrap-result-my-cluster").
    Build()

Build() returns an error if RunnerImage or Capability is empty. Default namespace is ont-system. Default TTL is 600 seconds. SecretVolume mounts are always read-only; the builder enforces this regardless of caller intent.

Usage

Import path:

github.com/ontai-dev/conductor-sdk

Building

go build ./...

---

conductor-sdk - Conductor Capability Contract Library / Apache License, Version 2.0