conductor is the platform intelligence layer for the Seam Platform. It produces two binaries from a single Go module at github.com/ontai-dev/conductor.
Status: Alpha. GitHub issues: https://github.com/ontai-dev/conductor/issues
| Binary | Entry point | Role |
|---|---|---|
| Compiler | cmd/compiler |
Compile-time intelligence. Short-lived CLI tool. Never deployed. |
| Conductor | cmd/conductor |
Runtime intelligence. Long-lived agent and short-lived executor. |
The Compiler produces manifests for human review and GitOps pipeline application. It never applies resources to any cluster. The Conductor binary runs in two distinct modes on clusters: as a long-lived Deployment (agent mode) and as short-lived Kueue Job pods (execute mode).
| Mode | Binary | Invocation | Duration | Image | Cluster scope |
|---|---|---|---|---|---|
| compile | Compiler | Direct CLI | Short-lived | Debian-slim | Never deployed |
| execute | Conductor | Kueue Job pod | Short-lived | Debian-slim | Management cluster only |
| agent | Conductor | Deployment in ont-system | Long-lived | Distroless | Management + all targets |
Compile mode attempted on the Conductor binary causes immediate InvariantViolation exit. The Conductor binary supports only execute and agent modes.
Execute-mode Jobs run exclusively on the management cluster. All cluster operations reach target clusters remotely via mounted kubeconfig and talosconfig Secrets. No capability Job runs on a target cluster.
The Compiler is a CR compiler: it reads human-authored spec files, validates them against platform schema rules, and produces Kubernetes CR YAML ready to apply. All subcommands are compile-only; the Compiler never applies, patches, or deletes any resource.
Subcommands:
| Subcommand | Purpose |
|---|---|
compiler bootstrap |
Compile a cluster declaration into Talos machine config Secrets and bootstrap CRs |
compiler launch |
Produce the CRD bundle for management cluster bootstrap |
compiler enable |
Produce the phased operator deployment manifest bundle |
compiler packbuild |
Compile a PackBuild spec into a ClusterPack CR |
compiler maintenance |
Compile a MaintenanceBundle CR with pre-resolved scheduling context |
compiler component |
Produce RBACProfile CR YAML from the embedded catalog or a descriptor |
compiler domain |
Reserved, not yet implemented |
Management cluster bootstrap is a three-step Compiler-driven sequence: bootstrap (cluster formation), launch (CRD installation), enable (operator deployment bundle). Platform operator has no involvement in management cluster bootstrap.
Helm rendering, Kustomize overlay resolution, and SOPS encryption live exclusively in the Compiler. These clients are excluded from the Conductor binary at build time via Go build tags.
Conductor in agent mode on the management cluster (stamped CONDUCTOR_ROLE=management by compiler enable) runs the full agent startup sequence plus:
- PackInstance signing loop: signs ClusterPack registrations with the platform signing key.
- PermissionSnapshot signing loop: signs PermissionSnapshot CRs produced by Guardian.
- Federation channel: exposes a persistent bidirectional gRPC stream for tenant Conductor connections on the federation port (default 9443).
- Step sequencer: as execute-mode Job, materialises one Kueue Job per RunnerConfig step in declared order, harvests ConfigMap results, and writes StepResults to RunnerConfig status.
Conductor in agent mode on each target cluster (stamped role=tenant by Platform operator at Deployment creation) runs:
- Capability manifest self-declaration: writes the supported capability list to RunnerConfig status on startup.
- PackReceipt reconciliation: verifies management signatures before acknowledging receipt.
- PermissionSnapshotReceipt reconciliation: verifies guardian signatures before acknowledging.
- Admission webhook: enforces RBAC ownership annotations (audit mode until bootstrap sweep completes, strict mode after).
- PermissionService gRPC server: serves authorization decisions cluster-locally.
- Drift detection loop: detects drift for TalosCluster and PackDelivery CRs.
- PermissionSnapshot pull loop: pulls snapshots from the management cluster.
- TenantBootstrapSweep: stamps governance annotations on existing RBAC resources and creates PermissionSet/RBACPolicy/RBACProfile for known third-party components.
Named capability constants and execution contracts are defined in the companion library at github.com/ontai-dev/conductor-sdk (package runnerlib). This is not a package in this repository. All operators import conductor-sdk. Conductor imports it at runtime to resolve capability names to handlers.
Conductor does not own any API group. CRDs it reads and writes are owned by:
seam.ontai.dev(seam): RunnerConfig, DriftSignal, LineageRecord, SeamMembership.seam.ontai.dev(dispatcher): PackDelivery, PackExecution, PackInstalled, PackReceipt.seam.ontai.dev(platform): TalosCluster and day-2 CRDs.guardian.ontai.dev(guardian): PermissionSet, RBACPolicy, RBACProfile, PermissionSnapshot.
Compiler binary:
go build -tags compiler ./cmd/compiler
Conductor binary:
go build -tags conductor ./cmd/conductor
Docker images:
# Compiler image (debian-slim, never deployed)
docker build -f Dockerfile.compiler -t 10.20.0.1:5000/ontai-dev/compiler:dev .
# Conductor agent image (distroless, agent mode - every cluster)
docker build -f Dockerfile.agent -t 10.20.0.1:5000/ontai-dev/conductor:dev .
# Conductor execute image (debian-slim, execute mode - Kueue Jobs on management cluster)
docker build -f Dockerfile.execute -t 10.20.0.1:5000/ontai-dev/conductor-exec:dev .
Lab builds are pushed only to 10.20.0.1:5000/ontai-dev/. Lab tags never enter the public registry.
The execute-mode image tag encodes Talos API compatibility: conductor-exec:<talos-version>. A cluster at Talos v1.9.3 requires a conductor-exec image tagged v1.9.3. Updating RunnerConfig agentImage to the new Conductor tag is a prerequisite to any Talos version upgrade.
go test ./...
Unit tests are required for all new functionality. End-to-end tests live under test/e2e/ and require MGMT_KUBECONFIG to be set. All e2e specs skip automatically when MGMT_KUBECONFIG is absent.
docs/conductor-schema.md: behavioral specification for modes, capabilities, job protocol, signing, and compiler subcommands.conductor-design.md: design rationale and architectural decisions.~/ontai/seam/docs/seam-schema.md: CRD schema authority for RunnerConfig, DriftSignal, and all cross-operator types underseam.ontai.dev.
conductor - Seam Platform Intelligence (Compiler and Conductor) / Apache License, Version 2.0