controllers/

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

Links

Open Source Insights

README ¶

`pkg/controllers` — reconcilers, webhooks, status helpers

Every controller-runtime reconciler the operator registers, the admission webhooks it serves, and the shared helpers they all use for status and conditions.

`+kubebuilder:rbac` markers here generate the ClusterRole

The markers in these packages' controller.go files are the source of config/manager/role.yaml. The chain is:

+kubebuilder:rbac markers here  ──mage gen:api──▶  config/manager/role.yaml
                                ──mage manifests─▶  pkg/platform/manifests/install.yaml

Adding a watched resource without regenerating produces an operator that crash-loops on failed to wait for caches to sync — controller-runtime starts an informer for the resource, the list/watch is Forbidden, the cache never syncs, and mgr.Start returns. The failure is silent at build time and fatal at deploy time. Run mage gen:api then mage manifests after touching a marker; TestInstallYAMLMatchesKustomize catches the drift in CI.

Note that a Get through the operator's client reads through the cache and therefore starts an informer — so get alone is not enough, you need list;watch too. See spiceboxsession/controller.go for a worked example of exactly this trap.

Reconcilers

Package	Primary CRD
`agentclass/`	`AgentClass`
`agentidentity/`	`AgentIdentity` (a validity reconciler + a refresh reconciler)
`agentsession/`	`AgentSession`
`agentui/`	`AgentUI`
`artifactrender/`	`ArtifactRender`
`channel/`	`Channel` (the `Connected` condition is channelsd's, not the operator's)
`clusteridentityprovider/`	`ClusterIdentityProvider` (singleton)
`clusterskill/`	`ClusterSkill`
`clusterskillsource/`	`ClusterSkillSource`
`credentialupdaterequest/`	`CredentialUpdateRequest`
`guardian/`	`AgentSessionGrants` → the SpiceDB `agentsession` definition
`mcpserver/`	`MCPServer`
`monitoring/`	Many — a declarative table of (CR type, condition) rows
`settings/`	`ClusterAgentSettings` and `AgentSettings`
`sidecartoolbox/`	`SidecarToolbox`
`skill/`	`Skill`
`skillsource/`	`SkillSource`
`spiceboxclass/`	`SpiceboxClass`
`spiceboxsession/`	`SpiceboxSession`
`spiceboxtoolchain/`	`SpiceboxToolchain`
`spiceboxtoolkit/`	`SpiceboxToolkit`
`spiceboxtoolspec/`	`SpiceboxToolspec`
`toolcall/`	`ToolCall`
`useridentity/`	`UserIdentity` (a validity reconciler + a refresh reconciler)
`workspacesource/`	`WorkspaceSource`

The cluster-scoped skill pair mirrors the namespaced pair; the shared halves live in internal/skillspec/ and internal/skillpin/ rather than being copied.

Shared machinery

Package	What it holds
`agentstatus/`	Multi-writer AgentSession status writes — each writer touches only the fields it changed
`conditions/`	Condition helpers that always stamp `ObservedGeneration`. Do not call `meta.SetStatusCondition` directly outside this package
`internal/`	The phase-based reconciler skeleton, backoff, and the helper bodies mirror controllers share
`webhooks/`	Admission webhooks — the author checks the API server cannot express
`testenv/`	Shared envtest harness + the SSA-idempotency CI gates
`testfixtures/`	`mustCreate` / `eventually` / `hasTrueCondition` helpers shared across controller tests

Status writes

Two rules the reconcilers here follow, both from AGENTS.md:

Observations go in controller-owned status, never in a client-applied field. A byte-identical server-side re-apply must be a no-op; testenv/idempotency/ is the CI gate for that.
Write only what changed. On AgentSession three actors write status concurrently, so use agentstatus.WriteOwned rather than a whole-object Status().Update.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
agentclass pkg/controllers/agentclass/builderclass.go	pkg/controllers/agentclass/builderclass.go
agentidentity Package agentidentity reconciles AgentIdentity CRs.	Package agentidentity reconciles AgentIdentity CRs.
agentsession pkg/controllers/agentsession/archive.go	pkg/controllers/agentsession/archive.go
cosidecar Package cosidecar builds the Kubernetes objects for a container that runs as a co-located sidecar in (or beside) the runner pod: the hardened container, its startup probe, and a NetworkPolicy with runner-only ingress and an egress policy chosen by the caller.	Package cosidecar builds the Kubernetes objects for a container that runs as a co-located sidecar in (or beside) the runner pod: the hardened container, its startup probe, and a NetworkPolicy with runner-only ingress and an egress policy chosen by the caller.
netpolrule Package netpolrule holds NetworkPolicy rule fragments shared by the per-session pod policies (pkg/controllers/agentsession) and the co-sidecar policies (pkg/controllers/agentsession/cosidecar).	Package netpolrule holds NetworkPolicy rule fragments shared by the per-session pod policies (pkg/controllers/agentsession) and the co-sidecar policies (pkg/controllers/agentsession/cosidecar).
agentstatus Package agentstatus writes AgentSession status the way a multi-writer CRD requires: each writer (the operator, channelsd) touches ONLY the fields it changed, so it never reverts a stale field or clears a field a concurrent writer owns.	Package agentstatus writes AgentSession status the way a multi-writer CRD requires: each writer (the operator, channelsd) touches ONLY the fields it changed, so it never reverts a stale field or clears a field a concurrent writer owns.
agentui Package agentui reconciles AgentUI CRs: it admits the page — spec.view, or spec.slots compiled into one by the legacy shim — validating it in one pass against the platform component vocabulary (pkg/web/uicomponents), including every oap:generative hook's own contract (a unique name, a registered allowlist, no nesting), and observes both the resulting hook table and an eligibility CEILING (pkg/web/uigrant) onto status — see AgentUIStatus.EligibleTools's doc comment for exactly what that ceiling does and does not mean; it is not the full three-way grant and must not be read as an authorization decision.	Package agentui reconciles AgentUI CRs: it admits the page — spec.view, or spec.slots compiled into one by the legacy shim — validating it in one pass against the platform component vocabulary (pkg/web/uicomponents), including every oap:generative hook's own contract (a unique name, a registered allowlist, no nesting), and observes both the resulting hook table and an eligibility CEILING (pkg/web/uigrant) onto status — see AgentUIStatus.EligibleTools's doc comment for exactly what that ceiling does and does not mean; it is not the full three-way grant and must not be read as an authorization decision.
artifactrender Package artifactrender hosts the ArtifactRender CRD reconciler.	Package artifactrender hosts the ArtifactRender CRD reconciler.
channel Package channel reconciles Channel CRDs.	Package channel reconciles Channel CRDs.
clusteridentityprovider pkg/controllers/clusteridentityprovider/controller.go	pkg/controllers/clusteridentityprovider/controller.go
clusterskill pkg/controllers/clusterskill/controller.go	pkg/controllers/clusterskill/controller.go
clusterskillsource pkg/controllers/clusterskillsource/controller.go	pkg/controllers/clusterskillsource/controller.go
conditions Package conditions wraps k8s.io/apimachinery/pkg/api/meta condition helpers with the project-wide convention of always stamping ObservedGeneration from the owning object's Generation.	Package conditions wraps k8s.io/apimachinery/pkg/api/meta condition helpers with the project-wide convention of always stamping ObservedGeneration from the owning object's Generation.
credentialupdaterequest Package credentialupdaterequest hosts the CredentialUpdateRequest reconciler: the operator-side decision of whether an agent's claim that a credential has died justifies putting a credential-entry card in front of a human.	Package credentialupdaterequest hosts the CredentialUpdateRequest reconciler: the operator-side decision of whether an agent's claim that a credential has died justifies putting a credential-entry card in front of a human.
guardian Package guardian holds the operator-side controllers that compose per-AgentClass authz requirements (AgentSessionGrants CRs) into the SpiceDB `agentsession` definition.	Package guardian holds the operator-side controllers that compose per-AgentClass authz requirements (AgentSessionGrants CRs) into the SpiceDB `agentsession` definition.
inboxwake Package inboxwake tells a session's OWN agent something by the only two means that work when the agent is not blocked in a tool call: append a fixed line to its transcript as an inbound "inbox" turn, then force it awake — the same two effects channelsd's applyWake produces for an ordinary human message (stamp the wake-requested-at annotation, publish the KindUserMessage nudge).	Package inboxwake tells a session's OWN agent something by the only two means that work when the agent is not blocked in a tool call: append a fixed line to its transcript as an inbound "inbox" turn, then force it awake — the same two effects channelsd's applyWake produces for an ordinary human message (stamp the wake-requested-at annotation, publish the KindUserMessage nudge).
internal
backoff Package backoff is the shared per-key exponential-backoff tracker used by controllers (agentidentity, useridentity), which run the identical JIT-refresh loop over different identity kinds.	Package backoff is the shared per-key exponential-backoff tracker used by controllers (agentidentity, useridentity), which run the identical JIT-refresh loop over different identity kinds.
identityrefresh Package identityrefresh holds the RFC 6749 refresh-token policy shared by the AgentIdentity and UserIdentity refresh reconcilers: classify each type=oauth credential against its Secret, redeem the ones inside the expiry threshold, write the Refresh condition, and schedule the next reconcile.	Package identityrefresh holds the RFC 6749 refresh-token policy shared by the AgentIdentity and UserIdentity refresh reconcilers: classify each type=oauth credential against its Secret, redeem the ones inside the expiry threshold, write the Refresh condition, and schedule the next reconcile.
reconcile Package reconcile provides a shared phase-based reconciler skeleton used by every controller in pkg/controllers/*.	Package reconcile provides a shared phase-based reconciler skeleton used by every controller in pkg/controllers/*.
skillpin Package skillpin provides pin-record construction helpers shared by controllers.	Package skillpin provides pin-record construction helpers shared by controllers.
skillspec Package skillspec holds type-agnostic leaf helpers shared by the SkillSource and ClusterSkillSource controllers, which materialize Skill / ClusterSkill CRs that embed the SAME SkillSpec / SkillStatus.	Package skillspec holds type-agnostic leaf helpers shared by the SkillSource and ClusterSkillSource controllers, which materialize Skill / ClusterSkill CRs that embed the SAME SkillSpec / SkillStatus.
mcpserver Package mcpserver reconciles MCPServer CRs.	Package mcpserver reconciles MCPServer CRs.
monitoring pkg/controllers/monitoring/monitoring.go	pkg/controllers/monitoring/monitoring.go
publicendpoint Package publicendpoint reconciles the PublicEndpoint CR: it opens the tunnel that makes this cluster reachable from the public Internet and publishes where it is reachable on status.url.	Package publicendpoint reconciles the PublicEndpoint CR: it opens the tunnel that makes this cluster reachable from the public Internet and publishes where it is reachable on status.url.
relationshipsource pkg/controllers/relationshipsource/controller.go	pkg/controllers/relationshipsource/controller.go
sessionhold Package sessionhold hosts the SessionHold reconciler: the operator-side component that publishes the session_release approval card once a hold has been observed Active, and applies the human's decision on it.	Package sessionhold hosts the SessionHold reconciler: the operator-side component that publishes the session_release approval card once a hold has been observed Active, and applies the human's decision on it.
settings RevokePublisher is the operator-side detective control pairing with the runner's in-process tool-origin invalidator cache: on every ClusterAgentSettings / AgentSettings reconcile it diffs spec.limits.allowedMCPServers and spec.limits.allowedToolkits against the previous per-CR observation and emits a "tool-origin" revocation on the unified ap.revocation bus for each explicit removal.	RevokePublisher is the operator-side detective control pairing with the runner's in-process tool-origin invalidator cache: on every ClusterAgentSettings / AgentSettings reconcile it diffs spec.limits.allowedMCPServers and spec.limits.allowedToolkits against the previous per-CR observation and emits a "tool-origin" revocation on the unified ap.revocation bus for each explicit removal.
sidecartoolbox Package sidecartoolbox reconciles SidecarToolbox CRs: validates the spec (sandbox class, provider ref, CEL constraints), then runs a one-shot probe Pod to confirm the sidecar image is reachable and its live tool list matches the declared allowlist.	Package sidecartoolbox reconciles SidecarToolbox CRs: validates the spec (sandbox class, provider ref, CEL constraints), then runs a one-shot probe Pod to confirm the sidecar image is reachable and its live tool list matches the declared allowlist.
skill pkg/controllers/skill/controller.go	pkg/controllers/skill/controller.go
skillsource pkg/controllers/skillsource/controller.go	pkg/controllers/skillsource/controller.go
spiceboxclass Package spiceboxclass implements the SpiceboxClass controller.	Package spiceboxclass implements the SpiceboxClass controller.
spiceboxsession Package spiceboxsession implements the SpiceboxSession controller.	Package spiceboxsession implements the SpiceboxSession controller.
spiceboxtoolchain Package spiceboxtoolchain reconciles SpiceboxToolchain CRs.	Package spiceboxtoolchain reconciles SpiceboxToolchain CRs.
spiceboxtoolkit Package spiceboxtoolkit reconciles SpiceboxToolkit CRs.	Package spiceboxtoolkit reconciles SpiceboxToolkit CRs.
spiceboxtoolspec Package spiceboxtoolspec reconciles SpiceboxToolspec CRs.	Package spiceboxtoolspec reconciles SpiceboxToolspec CRs.
subagentrequest Package subagentrequest hosts the SubagentRequest controller: the operator-side component that authorizes and performs delegation.	Package subagentrequest hosts the SubagentRequest controller: the operator-side component that authorizes and performs delegation.
testenv Package testenv provides a controller-runtime envtest harness shared across controller test packages.	Package testenv provides a controller-runtime envtest harness shared across controller test packages.
idempotency Package idempotency provides two CI-gate checks for the merge/apply convention in AGENTS.md's "Server-side apply: keep applied fields idempotent; put observations in status":	Package idempotency provides two CI-gate checks for the merge/apply convention in AGENTS.md's "Server-side apply: keep applied fields idempotent; put observations in status":
testfixtures Package testfixtures collects test helpers shared across controller test packages.	Package testfixtures collects test helpers shared across controller test packages.
toolcall Package toolcall implements the ToolCall controller.	Package toolcall implements the ToolCall controller.
useridentity Package useridentity reconciles UserIdentity CRs — the cluster-scoped per-user credential catalog used by identityMode=userPassthrough agents.	Package useridentity reconciles UserIdentity CRs — the cluster-scoped per-user credential catalog used by identityMode=userPassthrough agents.
webhooks
agentsession Package agentsession holds the AgentSession identity-pinning admission webhook.	Package agentsession holds the AgentSession identity-pinning admission webhook.
settings
skill pkg/controllers/webhooks/skill/clusterskill_webhook.go	pkg/controllers/webhooks/skill/clusterskill_webhook.go
subagentrequest Package subagentrequest holds the admission webhook that makes a SubagentRequest's parent claim provable.	Package subagentrequest holds the admission webhook that makes a SubagentRequest's parent claim provable.
toolcall Package toolcall holds the ToolCall admission webhook.	Package toolcall holds the ToolCall admission webhook.
workshop Package workshop holds the admission webhook that is the heart of the agent-builder lockdown (spec layer 1.4): it fires on every write the workshop sidecar's ServiceAccount makes to the workshop-authored kinds, attributes the SA to a session, walks that session's workshop and its SpiceDB `workshop#build` tuple, then enforces the per-kind content rules ordinary RBAC cannot express — no fragment schema, allowlisted sidecar images only, no nested builder, no cross-namespace reference, prefixed cluster-scoped tool CRs only, and per-kind object limits.	Package workshop holds the admission webhook that is the heart of the agent-builder lockdown (spec layer 1.4): it fires on every write the workshop sidecar's ServiceAccount makes to the workshop-authored kinds, attributes the SA to a session, walks that session's workshop and its SpiceDB `workshop#build` tuple, then enforces the per-kind content rules ordinary RBAC cannot express — no fragment schema, allowlisted sidecar images only, no nested builder, no cross-namespace reference, prefixed cluster-scoped tool CRs only, and per-kind object limits.
workspacejob Package workspacejob constrains Jobs created by a session runner to the workspace reconcile template derived from operator-owned session status.	Package workspacejob constrains Jobs created by a session runner to the workspace reconcile template derived from operator-owned session status.
workshop Package workshop hosts the Workshop reconciler: layer 1.2 (the closed RBAC kind set — the runner gets nothing, only <session>-workshop-sa gets the workshop namespace's build kinds) and layer 1.3 (the SpiceDB tuple that binds the workshop to the ONE session allowed to act as it).	Package workshop hosts the Workshop reconciler: layer 1.2 (the closed RBAC kind set — the runner gets nothing, only <session>-workshop-sa gets the workshop namespace's build kinds) and layer 1.3 (the SpiceDB tuple that binds the workshop to the ONE session allowed to act as it).
workshopprobe Package workshopprobe — controller.go: the reconciler that turns a WorkshopProbe CR into a run probe.	Package workshopprobe — controller.go: the reconciler that turns a WorkshopProbe CR into a run probe.
workspacesource
workspacevolume Package workspacevolume reclaims workspace PersistentVolume OBJECTS whose data can no longer exist: a Released, hostPath-backed volume of the workspace StorageClass, node-affined to a node the cluster no longer has.	Package workspacevolume reclaims workspace PersistentVolume OBJECTS whose data can no longer exist: a Released, hostPath-backed volume of the workspace StorageClass, node-affined to a node the cluster no longer has.