Architecture
Infrared is a Kubernetes operator with an API, a UI, a CLI and an MCP server in front of it. Its data store is its own CRDs: there is no separate database. Everything it installs, including itself, is described in a gitops repo that Argo CD syncs.
Components
| Component | What it is |
|---|---|
| infrared-operator | The controllers and the CRDs. Reconciles the Installation, orgs, clusters, git providers, gitops repos, Products and the AgentRole catalog. The CRDs are the data store. |
| infrared-api | The REST API under /v1, described by an OpenAPI document. The UI, the CLI and the MCP server all go through it. It serves the setup wizard before any org exists. |
| infrared-mcp | An MCP server over infrared-api, so agents can read and act on Infrared with the same permissions a human would have. |
infrared-cli (ir) | The command-line client over infrared-api. |
| infrared-ui | The web UI: setup wizard, Products, Changes, AgentRoles, AgentWorkflows and AgentWorkflowRuns. |
| infrared-chart | The helm chart, published as oci://ghcr.io/darkshiftio/charts/infrared. It installs the operator, API, MCP server and UI. |
| infrared-gitops-template | The template every gitops repo is hydrated from: the gitops catalog of components, the registry layout and the app-of-apps root. Pinned by tag. |
| infrared-iac-modules | Tagged Terraform modules used as cluster templates, such as aws/k3s-node. Consumed by Crossplane provider-terraform Workspaces from phase 3. |
CRDs
All kinds are in the API group infrared.darkshift.io/v1alpha1. Cluster-scoped kinds describe the control plane; namespaced kinds belong to one org and live in its namespace, ir-org-<org>. The CRD reference lists the fields.
| Kind | Scope | What it holds |
|---|---|---|
| Installation | Cluster | The singleton, named infrared, that tracks the setup wizard. |
| Organization | Cluster | An org: display name, whether it is the platform org, and its cluster allowlist. |
| Cluster | Cluster | A management or workload cluster: flavor, provider, region, cluster template. |
| GitProvider | ir-org-<org> | The org's connection to GitHub through a GitHub App. |
| GitopsRepo | ir-org-<org> | The org's gitops repo: template version, hydration commit, sync waves and Application status. |
| Product | ir-org-<org> | A Product: its repos and current Release. |
| AgentRole | ir-org-<org> | One job an agent performs, seeded from the catalog and editable by the org. |
| AgentWorkflow | ir-org-<org> | The ordered steps a Change or scheduled job moves through. |
| AgentWorkflowRun | ir-org-<org> | One run of an AgentWorkflow. Execution arrives in phase 5; the schema is fixed now. |
Bootstrap sequence
A fresh install goes from helm install to a control plane that Argo CD manages. The Installation's status.phase tracks each step.
After adoption, the helm release is no longer how Infrared changes. Upgrades are pin PRs to the gitops repo, and Argo CD applies them.
Sync waves
The gitops template gives each component a sync wave. Argo CD syncs wave by wave, and a wave starts only when every Application in the waves before it is Synced and Healthy.
| Wave | Applications | Notes |
|---|---|---|
| 0 | AppProjects | The boundaries every later Application belongs to. |
| 10 | cert-manager, external-secrets, aws-load-balancer-controller | aws-load-balancer-controller on EKS only. |
| 15 | infisical | Secrets move into Infisical in phase 2. |
| 25 | kpack | The kpack controller. |
| 26 | builds | Only when builds.registry is set: the ClusterBuilder, the builder service account and the jobs that keep registry and GitHub credentials fresh. Products build here. See Deliver a single app. |
| 30 | victoria-metrics-k8s-stack | Metrics, alerting and dashboards. |
| 40 | infrared | Infrared itself, adopted by Argo CD from the helm install. |
| 100 | argocd | Argo CD manages itself, last. |
Gitops repo layout
The registry holds one folder per cluster. The root Application points at the management cluster's folder and creates every other Application from it.
gitops/
registry/
clusters/
<cluster>/
root.yaml # the app-of-apps root Application
appprojects/
components/ # one Application per component, annotated with its sync wave
catalog/ # the gitops catalog, hydrated from infrared-gitops-template
Where secrets live
In phase 1, the GitHub App's private key and webhook secret sit in Kubernetes Secrets in the org's namespace, referenced from the GitProvider. In phase 2 they move to Infisical and reach the cluster through external-secrets.