CRD reference

All kinds are in the API group infrared.darkshift.io, version v1alpha1. Cluster-scoped kinds describe the control plane. Namespaced kinds belong to one org and live in ir-org-<org>. Every kind has status.observedGeneration and status.conditions (Ready, Progressing, Degraded), which are left out of the tables below.

Resources Infrared creates carry the label app.kubernetes.io/managed-by: infrared. Org resources carry infrared.darkshift.io/org, and catalog-seeded resources carry infrared.darkshift.io/catalog.

Kind	Short name	Scope
Installation	irinst	Cluster
Organization	irorg	Cluster
Cluster	ircluster	Cluster
GitProvider	irgit	ir-org-<org>
GitopsRepo	irgitops	ir-org-<org>
Product	irproduct	ir-org-<org>
AgentRole	ar	ir-org-<org>
AgentWorkflow	aw	ir-org-<org>
AgentWorkflowRun	awr	ir-org-<org>

Installation

The singleton that tracks the setup wizard. It must be named infrared. The API fills in the spec as the wizard advances; the controller derives the phase.

Field	Meaning
spec.tokenVerified	Set once the one-time setup token has been presented.
spec.admin.email, spec.admin.passwordSecretRef	The first platform admin and the Secret key holding the bcrypt hash of their password.
spec.platformOrg	The Organization that administers the control plane.
spec.managementCluster	The Cluster Infrared runs on.
spec.gitProviderRef, spec.gitopsRepoRef	The platform org's GitProvider and GitopsRepo.
status.phase	AwaitingToken, AwaitingAdmin, AwaitingOrg, AwaitingCluster, AwaitingGitProvider, AwaitingGitopsRepo, Syncing or Ready.
status.version	The Infrared control plane version.

Organization

An org: the tenancy and RBAC boundary. Names are at most 56 characters so ir-org-<name> fits a namespace.

Field	Meaning
spec.displayName	Name shown in the UI.
spec.platform	True for the org that administers the control plane.
spec.clusterAllowlist	Clusters this org may deliver zones to. Managed by the platform org.
status.namespace	The org's namespace, ir-org-<name>.

Cluster

A management or workload cluster.

Field	Meaning
spec.type	management or workload.
spec.flavor	k3s or eks. Selects distribution-specific components.
spec.provider, spec.region	aws, gcp, linode or local, and the provider region.
spec.template.module, spec.template.version	The cluster template (a module in infrared-iac-modules, such as aws/k3s-node) and its tag.
spec.server	API server URL Argo CD uses. Empty means in-cluster.
status.kubernetesVersion, status.nodes	Observed version and node count.
status.detected	True for the cluster Infrared found itself running on.

GitProvider

Connects an org to GitHub through a GitHub App. GitLab and Gitea come later.

Field	Meaning
spec.type	github-app.
spec.owner	The GitHub organization login Infrared manages.
spec.github.appID, spec.github.slug	The GitHub App.
spec.github.installationID	Set once the App is installed on the owner.
spec.github.privateKeySecretRef	Secret key holding the App's PEM private key.
spec.github.webhookSecretRef	Secret key holding the webhook secret.
spec.github.apiURL	Overrides https://api.github.com for GitHub Enterprise Server.
status.installationVerified, status.lastVerifiedTime	Whether and when the App last minted an installation token.

GitopsRepo

An org's gitops repo, created, hydrated and bootstrapped by Infrared.

Field	Meaning
spec.providerRef	The GitProvider that owns the repo.
spec.name, spec.visibility, spec.defaultBranch	Defaults gitops, private, main.
spec.template.repo, spec.template.version	The gitops template and the tag it is hydrated from.
spec.cluster, spec.clusterFlavor	The management cluster the registry bootstraps, and its flavor.
spec.bootstrap	Apply Argo CD and the root Application after hydration. Default true.
status.phase	Pending, Created, Hydrated, Bootstrapped or Synced.
status.url, status.commit, status.hydratedVersion	The repo URL, the last hydration commit and the template version used.
status.waves[]	Per sync wave, each Application's sync (Synced, OutOfSync, Unknown) and health (Healthy, Progressing, Degraded, Suspended, Missing, Unknown).

Product

The unit Infrared builds, releases and manages change for.

Field	Meaning
spec.displayName, spec.description	Shown in the UI.
spec.repos[]	The repos in the Product: owner, name and role (app, chart, umbrella, library or docs).
spec.currentRelease	The Release in progress, such as 2.4.
spec.logo	repo (default: the first repo) and path (default: found by convention). See Products.
status.logo	repo, path, sha, contentType, bytes, source (detected or uploaded), syncedAt, pending, message.

AgentRole

A job an agent performs. See AgentRoles, AgentWorkflows and AgentWorkflowRuns.

Field	Meaning
spec.displayName, spec.summary	Name and one-sentence summary (at most 280 characters).
spec.category	architect, change-review, scheduled or builder.
spec.mission	The outcome the role is accountable for.
spec.responsibilities[]	Ordered steps.
spec.triggers[]	type (adhoc, onChange, cron, event), schedule, event, description, and optional filters labels[], paths[] (globs) and branches[].
spec.inputs[]	source and description.
spec.outputs[]	What the role leaves behind.
spec.evidence[]	kind (screenshot, video, report, log, comment, diff, sarif, metric, document, trace, sbom), description, required.
spec.successCriteria[]	Verifiable statements that must all hold.
spec.guardrails[]	What the role must never do.
spec.permissions	allowedTools, deniedTools, git, cluster, network (none, allowlist, open), egressAllowlist, mayMerge. Deny wins over allow. egressAllowlist may contain $(ZONE_HOSTS), which the runner expands to the Product's zone hostnames.
spec.escalation	when[], to (a team or user handle), after (a duration such as 30m).
spec.opinions[]	name, title, guidance, origin (catalog, org, tailored), enabled (omitted means on; false keeps the opinion but the agent doesn't receive it).
spec.verdicts[]	The verdicts a run may end with, such as VERIFIED, MERGE WITH FOLLOW-UPS, BLOCK. Every run ends with exactly one.
spec.instructions	Markdown appended to the role's prompt for the org.
spec.skills[], spec.mcpServers[]	Names of skills and MCP servers the org configured for the role.
spec.model	providerRef, model, maxBudgetUSD (decimal string), maxTurns.
spec.enabled	Whether the role runs.
spec.origin	catalog version, tailored, tailoredFrom[].
status.stats	runs7d, succeeded7d, medianTokens, lastRunTime.
status.differsFromCatalog	True when the org edited the role after seeding.

AgentWorkflow

Orders AgentRoles and gates into a repeatable workflow.

Field	Meaning
spec.displayName, spec.description	Shown in the UI.
spec.triggers[]	Same shape as AgentRole triggers.
spec.steps[]	name, type (agentRole, human, auto, ci, promote), agentRole, zone, required, onFailure (deadLetter, fail, continue), maxAttempts, needs[], independent, when, approvers[], minApprovals, timeout, description. Empty needs means the previous step; independent: true starts the step with the workflow. when is a condition such as change.author in [human], agentRole.enabled or label:security, combined with && and negated with !. approvers, minApprovals (default 1) and timeout configure human gates; timeout applies to any step. A step whose AgentRole is switched off is Skipped.
spec.deadLetter	to (default human reviewer) and notify[] channels such as slack:#checkout-changes.
spec.maxConcurrency	Runs at once. Default 3.
spec.enabled, spec.origin	As for AgentRole.

AgentWorkflowRun

One run of an AgentWorkflow. Execution arrives in phase 5.

Field	Meaning
spec.workflowRef, spec.productRef	The AgentWorkflow and the Product.
spec.change	repo, issue (such as checkout-web#212) and pullRequest.
spec.trigger	What started the run, such as onChange, cron or adhoc:<user>.
status.phase	Queued, Running, DeadLettered, AwaitingApproval, Succeeded, Failed, Cancelled or Skipped.
status.steps[]	Per step: phase, verdict, attempts, startedAt, finishedAt, usage, evidence[] (with per-criterion results) and message.
status.usage	Input, output and cache-read tokens, costUSD and turns for the whole run.