Install on k3s

k3s is the first validated target for Infrared. A single k3s node is enough for the management cluster while you evaluate it.

Versions

Until 0.1 is released, Infrared ships pre-releases on the 0.1 track: the chart version is 0.1.0-alpha.N and the app version v0.1.0-alpha.N. 0.1.0 itself is reserved for the release. Because these are semver pre-releases, helm install without --version skips them, so always name the version. The examples below use 0.1.0-alpha.3; use the newest pre-release you were given.

Before you start

• A k3s cluster, v1.30 or later, with kubectl pointed at it. One node with 4 vCPU and 8 GiB of memory runs the control plane and every component in the gitops catalog.
• helm 3.14 or later, which can install charts from OCI registries.
• A GitHub organization you administer. The setup wizard creates a GitHub App on it and a gitops repo in it.
• Pull access to Infrared's component images (below).

Where the chart and images come from

What	Where
Chart	oci://ghcr.io/darkshiftio/charts/infrared, version 0.1.0-alpha.N
Chart, git fallback	The public repo https://github.com/darkshiftio/infrared-chart, directory charts/infrared, at tag v0.1.0-alpha.N. Same chart, no registry needed.
Component images	Pinned in the chart by tag and digest (v0.1.0-alpha.N@sha256:...)

The chart package on ghcr is public; no login is needed. If helm answers 403 denied, it is sending stale ghcr credentials from your local docker or helm config: run helm registry logout ghcr.io and try again.

The component images are not on a public registry yet. Before you install, get from your Infrared contact a registry you can pull the pinned images from and, if it needs one, a pull credential. Create the pull Secret in the release namespace:

kubectl create namespace infrared
kubectl -n infrared create secret docker-registry infrared-pull \
  --docker-server=<registry> \
  --docker-username=<user> \
  --docker-password=<token>

Skip the Secret if your nodes can already pull from that registry (for example through a kubelet credential provider).

1. Install the chart

From the OCI registry:

helm install infrared oci://ghcr.io/darkshiftio/charts/infrared --version 0.1.0-alpha.3 \
  -n infrared --create-namespace \
  --set managementCluster.name=<cluster name> \
  --set image.registry=<registry> \
  --set 'imagePullSecrets[0].name=infrared-pull'

Or from the git fallback:

git clone --depth 1 --branch v0.1.0-alpha.3 https://github.com/darkshiftio/infrared-chart
helm install infrared ./infrared-chart/charts/infrared \
  -n infrared --create-namespace \
  --set managementCluster.name=<cluster name> \
  --set image.registry=<registry> \
  --set 'imagePullSecrets[0].name=infrared-pull'

• managementCluster.name becomes the folder registry/clusters/<cluster>/ in your gitops repo. The wizard confirms it; to change it, reinstall with a different value before you finish the wizard.
• builds.registry (optional) turns on product builds: set it to the registry prefix kpack pushes product images to, such as 123456789012.dkr.ecr.us-east-1.amazonaws.com/<org>. See Deliver a single app.
• gitops.templateVersion picks the gitops template the wizard hydrates your repo from. Each chart defaults to the template it was released with. Templates from v0.1.4 on pull Infrared's own chart from ghcr at sync time; v0.1.3 pulls it from the public git repo.
• The first entry in imagePullSecrets is also handed to the operator, which uses it for the clusters it bootstraps. Leave imagePullSecrets out if you skipped the Secret.
• --create-namespace is harmless when the namespace already exists.

Wait for the pods:

kubectl -n infrared get pods -w

The operator, API, MCP server and UI should each reach Running. The operator creates the Installation named infrared and detects the cluster it is running on.

kubectl get installation infrared

The phase starts at AwaitingToken.

2. Read the setup token

The chart generates a one-time setup token and stores it in the Secret infrared-setup, key token.

kubectl -n infrared get secret infrared-setup -o jsonpath='{.data.token}' | base64 -d; echo

To choose the token yourself, pass --set setup.token=<token> at install time, or point setup.existingSecret at a Secret you created with a token key.

3. Open the UI

kubectl -n infrared port-forward svc/infrared 8080:80

Open http://localhost:8080 and continue with the setup wizard.

A port-forward is enough for the whole wizard. Because localhost is not reachable from GitHub, the GitHub App is then created without a webhook; see Connect GitHub. If Infrared already has a public URL when you install it, pass --set externalURL=https://<host>. To add one after the wizard, see Expose Infrared over HTTPS.

Troubleshooting

Symptom	Likely cause	What to do
Pods stuck in ImagePullBackOff	The nodes cannot pull the pinned images: wrong image.registry, a missing pull Secret, or a Secret in the wrong namespace.	kubectl -n infrared describe pod <pod> shows the pull error. Check the registry and recreate the Secret in infrared.
helm install from oci:// fails with 403 denied	helm is sending stale ghcr credentials from your docker or helm config. The package itself is public.	Run helm registry logout ghcr.io (and docker logout ghcr.io), or install from the git fallback.
helm install says no chart version found	helm skips pre-releases without an explicit version.	Pass --version 0.1.0-alpha.N.
The Installation stays at AwaitingToken after you enter the token	The token was copied with a trailing newline or space.	Read it again with the command above and paste only the characters.
port-forward fails with service "infrared" not found	You installed with a release name other than infrared.	The Service is named after the release; use svc/<release>.

After setup

Once the setup wizard finishes, Argo CD adopts Infrared from the gitops repo. From then on, upgrade Infrared through the gitops repo, not with helm upgrade: Argo CD reverts a helm upgrade on its next sync. See Upgrades.