Setup wizard
The setup wizard runs the first time you open the Infrared UI. It has seven steps, and each one moves the Installation infrared to its next phase. You can close the browser at any point and resume: the wizard reads its progress from the Installation.
kubectl get installation infrared -w
| Step | What you do | Installation phase while waiting |
|---|---|---|
| 1 | Verify the setup token | AwaitingToken |
| 2 | Create the platform admin | AwaitingAdmin |
| 3 | Name the platform org | AwaitingOrg |
| 4 | Confirm the management cluster | AwaitingCluster |
| 5 | Connect GitHub | AwaitingGitProvider |
| 6 | Hydrate the gitops repo | AwaitingGitopsRepo |
| 7 | Sync with Argo CD | Syncing, then Ready |
1. Verify the setup token
Paste the token from the Secret infrared-setup, key token (see Install on k3s). The token proves you have access to the cluster. It works until the platform admin exists; after that it no longer unlocks anything.
The browser remembers the token in a cookie. If you continue in another browser or tab that never presented it, the wizard asks for the token again ("Verify setup token in this browser") before it lets you create the admin.
2. Create the platform admin
Enter an email and a password of at least 12 characters for the first platform admin. Infrared stores a bcrypt hash of the password in the Secret infrared-admin and signs you in. This account administers the control plane; SSO arrives in phase 2. From here on, the wizard needs you signed in: if your session ends, sign in again to continue.
3. Name the platform org
The platform org administers the control plane. Choose a short name: it becomes the org's namespace, ir-org-<org>, so it must be a lowercase DNS label of 56 characters or fewer. Infrared creates the Organization, the namespace and a copy of the default AgentRole catalog for the org.
4. Confirm the management cluster
Infrared shows the cluster it detected itself running on: its name, flavor (k3s or eks), region and Kubernetes version. The name is the chart value managementCluster.name you installed with, and it becomes the folder registry/clusters/<cluster>/ in the gitops repo. Confirm it to continue. To use a different name, reinstall with a different managementCluster.name before you finish the wizard.
5. Connect GitHub
Enter the GitHub organization Infrared should manage. The wizard uses the GitHub App manifest flow:
- You are sent to GitHub with a prefilled App manifest: the name
infrared-<platform org>, its permissions (contents, pull requests, issues, administration and workflows write; checks and metadata read) and the URLs GitHub returns you to. - You click Create GitHub App on GitHub. GitHub hands the App ID, private key and secrets to Infrared and sends you on to install the App.
- You install the App on the GitHub organization. It needs to create the gitops repo, so choose All repositories.
- GitHub returns you to the wizard, which shows the App as installed.
Infrared creates a GitProvider named github in the platform org's namespace and verifies it can mint an installation token.
GitHub only accepts a webhook URL it can reach from the internet. When you open Infrared on a local or private address, such as a kubectl port-forward to localhost, the manifest has no webhook and the App is created without one. Infrared doesn't act on GitHub events yet, so nothing is lost; once Infrared has a public URL (externalURL), you can add the webhook to the App in GitHub's settings.
:::caution Where the private key is kept
In phase 1, the GitHub App's private key and webhook secret sit in Kubernetes Secrets in ir-org-<org>, referenced from the GitProvider. Restrict access to that namespace. In phase 2, secrets move to Infisical and reach the cluster through external-secrets.
:::
6. Hydrate the gitops repo
Infrared creates the gitops repo (default name gitops, private) in your GitHub organization and hydrates it from a pinned version of infrared-gitops-template. The operator commits as infrared[bot]. The repo gets:
- the gitops catalog of components, chosen for the cluster's flavor,
registry/clusters/<cluster>/with one Application per component, each annotated with its sync wave,- the app-of-apps root Application.
The GitopsRepo resource records the hydration commit and the template version. Infrared then installs Argo CD, gives it read access to the repo through the GitHub App, and applies the root Application.
7. Sync with Argo CD
Argo CD syncs the registry wave by wave. The wizard shows each wave and each Application's sync status (Synced or OutOfSync) and health (Healthy, Progressing, Degraded, Suspended or Missing), with a count of Healthy Applications, the current wave and the hydration commit.
| Wave | Applications |
|---|---|
| 0 | AppProjects |
| 10 | cert-manager, external-secrets, aws-load-balancer-controller (EKS only) |
| 15 | infisical |
| 25 | kpack |
| 26 | builds (only with builds.registry) |
| 30 | victoria-metrics-k8s-stack |
| 40 | infrared |
| 100 | argocd |
At wave 40, Argo CD adopts Infrared: the helm release you installed becomes an Application in the gitops repo, and the Secrets the chart generated (setup token, session key, MCP token) are kept. At wave 100, Argo CD starts managing itself. When every Application is Synced and Healthy, the Installation reaches Ready and Open Products takes you into Infrared.
A few minutes of Progressing is normal while charts pull images and databases start. If a wave doesn't move, see Troubleshooting.
After the wizard
- Upgrades are pin PRs. Infrared is now managed by gitops. To upgrade it, merge a pin PR that changes its pin in the gitops repo. Do not run
helm upgrade; Argo CD reverts it on the next sync. See Upgrades. - Your AgentRoles are ready to read and edit. Open Agents in the UI to review the catalog seeded into the platform org. See AgentRoles, AgentWorkflows and AgentWorkflowRuns.