Architecture
Infrared is a Kubernetes operator with an API in front of it, and a web app, a command-line client and an MCP server that all talk to that API. It keeps its records as Kubernetes custom resources, so there is no separate database to run. Everything it installs, itself included, is described in a gitops repo that Argo CD keeps in step with your clusters.
You rarely need this page to use Infrared: you work in the app or with ir, and the rest happens for you. Read on when you want to know what runs where, what Infrared writes to git, and what an agent can and cannot reach.
The parts
| Part | What it does |
|---|---|
| infrared-operator | The controllers and the custom resource definitions. It sets the install up, keeps orgs, clusters, gitops repos, Products and their zones in the state their resources describe, runs deployments and release cuts, runs each AgentWorkflowRun step by step, and keeps each access group's GitHub team in step with its people. |
| infrared-api | The REST API under /v1, described by an OpenAPI document. The app, ir and the MCP server all go through it. It serves the setup wizard before any org exists, signs people in, and reads the Google Workspace groups that access groups map to. |
| infrared-ui | The web app: the setup wizard, then Products, Changes, Deployments, Releases, Workforce, Clusters, Usage, Access and Settings, your own page (You), and each Product's status page. |
infrared-cli (ir) | The command-line client. It calls the same API as the app, and installs, backs up and restores Infrared. See the ir command reference. |
| infrared-mcp | An MCP server that gives agents read-only access to Infrared through the API, with the permissions of the token they use. On an install with the code index turned on, it also serves the code tools. See MCP. |
| infrared-runner | Runs one AgentRole step inside a Kubernetes Job the operator starts. It downloads the Product's repo, runs the agent, and writes the result back to the forge: a commit and pull request, a comment, an issue, or a draft for Slack. It never merges. |
| Summary video Job | When an org has summary videos on, the operator starts one Job per video: a Change's summary, or the org's weekly video on Products. The Job writes and voices a script, renders the scenes, and uploads the video to the API. It holds no API token, only a ticket the operator signs for that one video. See Summary videos. |
| Code index | Optional. A search index of your own repositories and the open-source ones your install runs on, each at named commits. The API reads it, and agents reach it through the MCP server's code tools. See Code index. |
| Argo CD | Installed by Infrared on the management cluster. It syncs the gitops repo to the management cluster and to every workload cluster, Infrared itself included. |
| gitops repo | Each org's git repo of desired state: the components each cluster runs, each Product's build and zones, and Infrared's own settings. Infrared creates it, fills it from the gitops template, and changes it only through pull requests. |
| Forge | Where your repos and gitops repo live: a GitHub organization, connected through a GitHub App the setup wizard creates, or Gitea, which the chart can run on the management cluster. |
Infrared ships as one Helm chart, infrared, that pins the image of every part above. It also uses two template repos, pinned by tag: infrared-gitops-template, which every gitops repo is filled from, and infrared-iac-modules, the cluster templates gcp/gke-cluster (GKE) and aws/eks-cluster (EKS) that the operator applies with an OpenTofu Job when you build a workload cluster.
The resources
Every kind is in the API group infrared.darkshift.io/v1alpha1. Cluster-scoped kinds describe the install as a whole. Namespaced kinds belong to one org and live in its namespace, ir-org-<org>. The CRD reference lists every field.
| Kind | Scope | What it holds |
|---|---|---|
| Installation | Cluster | The one install, named infrared: the setup wizard's progress, addresses, models, backups and sign-in. |
| Organization | Cluster | An org: its name, whether it is the platform org, its access groups, the clusters it may use, scheduling, models and Slack. |
| Cluster | Cluster | The management cluster or a workload cluster: its provider, region, cluster template and how Infrared reaches it. |
| BreakGlass | Cluster | The root user, named root: its sign-in address, a one-way hash of its password, where the password is kept, and every use. |
| User | Cluster | A person who signs in with Google, and the git accounts they linked. |
| GitConnector | Cluster | A forge people link their git accounts on: GitHub, GitLab or Gitea, at an address. |
| GitProvider | ir-org-<org> | The org's connection to its forge: a GitHub App, or the install's Gitea. |
| GitopsRepo | ir-org-<org> | The org's gitops repo: the template version, the last hydration, and each sync wave's status. |
| Product | ir-org-<org> | A Product: its repos, its zones in promotion order with their addresses and settings, its SLOs and its status page. |
| Release | ir-org-<org> | A deployment: one version of a Product on its way through its zones. The kind keeps the name Release. |
| ReleaseCut | ir-org-<org> | A release: the deployments that reached production since the last one, under one version, with its notes and post. |
| Team | ir-org-<org> | A Team on Workforce: its people, its AgentRoles and the Products it owns or contributes to. |
| Human | ir-org-<org> | A person on Workforce → People: their profile, job role, manager and handles. |
| 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 a scheduled job moves through. |
| AgentWorkflowRun | ir-org-<org> | One run of an AgentWorkflow: each step's phase, verdict, usage, cost and evidence. |
| Domain | ir-org-<org> | A DNS name the org can put zone addresses under, with the records to add and what Infrared last found. |
| Incident | ir-org-<org> | Something wrong in a Product's zone that people are handling. |
| CloudAccount | ir-org-<org> | A Google Cloud project or AWS account the org gives Infrared, reached through a role, never a key. |
| Registry | ir-org-<org> | A container registry in one of the org's cloud accounts. |
How a fresh install sets itself up
A fresh install goes from one helm install to a control plane that Argo CD manages. The Installation's status.phase follows each step, and the setup wizard walks you through the ones that need you. See Setup wizard.
Once Argo CD has adopted Infrared, Helm is no longer how Infrared changes. An upgrade is a pull request to the gitops repo that Argo CD applies, watched by a guard that rolls a bad upgrade back. See Upgrades.
Sync waves
The gitops template gives each component a sync wave. Argo CD syncs one wave at a time, and a wave starts only when every Application before it is Synced and Healthy.
| Wave | Applications | When |
|---|---|---|
| 0 | AppProjects | Always. The boundaries every later Application belongs to. |
| 10 | cert-manager, external-secrets, aws-load-balancer-controller | aws-load-balancer-controller on EKS only. |
| 11 to 13 | envoy-gateway, origin-ca-issuer, platform-tokens, external-dns, edge | Only on the shared Gateway edge. See Expose Infrared. |
| 15 | infisical | Installed for later use. Infrared's own secrets are still Kubernetes Secrets. |
| 25 | kpack | Always. |
| 26 | builds | When the install has a build registry: the builder, its service account, and the jobs that keep registry and forge credentials fresh. |
| 30 | victoria-metrics-k8s-stack | Metrics, alerts and dashboards. |
| 40 | infrared | Infrared itself, adopted from the Helm install. Its values hold the install's settings. |
| 41 | code-index | Only when the code index is turned on. |
| 50 | Product builds, workload clusters | Added by Infrared: each Product's kpack Image and each workload cluster's app-of-apps (cluster-<name>). |
| 60 | Product zones | Added by Infrared: one Application per zone (product-<zone>). |
| 100 | argocd | Argo CD manages itself, last. |
The template holds a few more components that a standard install leaves out.
What Infrared writes to the gitops repo
The repo holds one folder per cluster under registry/clusters/. The management cluster's root Application, registry-<cluster>, points at that cluster's components/ folder and owns every Application in it. Infrared adds files as you add Products, zones, workload clusters and Teams, each through a pull request.
gitops/
components/ # the gitops catalog, filled from the template
registry/
clusters/
<cluster>/
registry.yaml # the root Application (app-of-apps)
components/ # one Application per component, with its sync wave
infrared.yaml # Infrared itself, with the install's settings
product-<zone>.yaml # one per Product zone
cluster-<workload>.yaml # the app-of-apps of a workload cluster
products/
<product>/
build/image.yaml # the Product's kpack Image
chart/ # a generic web chart, when Infrared scaffolds the Product
zones/<zone>/values.yaml # the zone's values, holding its image pin
teams/
<team>/ # a Team's charter, context and daily status
How an agent step runs
When an AgentWorkflowRun reaches an AgentRole step, the operator starts a Kubernetes Job in the org's namespace that runs infrared-runner. The Job gets the step's spec, a forge token limited to what the AgentRole may do, and the org's model key.
The runner downloads the Product's repo at the right commit, runs the agent on it, and writes back through the forge's API. It leaves its verdict, usage and evidence as its result, and the operator records them on the AgentWorkflowRun. Human gates, promotions and automatic steps are the operator's own work and start no Job.
A NetworkPolicy fences every runner pod. It may reach the internet over DNS and HTTP(S), for the model provider and the forge, and nothing inside the cluster or its network, the Kubernetes API and cloud metadata included. The agent's container asks for 2 GiB of memory and may use up to 6 GiB; if it runs out, the step says so and an incident opens on the Product.
Where secrets live
| Secret | Where |
|---|---|
| The GitHub App's private key and webhook secret | Kubernetes Secrets in the org's namespace, named by the GitProvider. |
| The org's model key | The Secret model-provider-anthropic in the org's namespace. |
| Git connectors' OAuth client secrets | The Secret infrared-git-connectors in Infrared's namespace. |
| API tokens | Only their SHA-256 hashes, in the Secret infrared-api-tokens. |
| The root user's password | In no Secret. It lives in a vault outside Infrared, and the BreakGlass record keeps only its bcrypt hash. See Break glass. |
The gitops template installs Infisical and external-secrets, but Infrared's own secrets don't use them yet. See the roadmap.