Install on GKE

This guide installs Infrared with helm on a GKE cluster in your Google Cloud project, then finishes in the setup wizard. Infrared's chart and images are public. Infrared reaches Google Cloud through Workload Identity, never a key: to write backups to Cloud Storage, and to reach the cloud accounts your orgs add.

Before you start

• A GKE Standard cluster on the REGULAR release channel, with kubectl able to reach it. Build it from Infrared's GKE cluster template, gcp/gke-cluster in infrared-iac-modules, which we share with you when you start, or use a cluster you already have with:

  • Workload Identity on;
  • at least 3 nodes of 4 vCPU and 16 GiB, such as e2-standard-4, which also run your Products' builds;
  • nodes with external addresses, and a firewall that lets ports 80 and 443 reach them from Cloudflare's address ranges only. The template does this with public_nodes and public_http_cidrs.

• helm 3.8 or later and kubectl. Infrared's chart and images are public, so there is nothing to sign in to.

• A domain on Cloudflare, and a Cloudflare API token that can edit its DNS and issue origin certificates. Infrared's edge is an Envoy Gateway with one Envoy on every node, on the node's own ports 80 and 443, behind Cloudflare's proxy, so there is no cloud load balancer to pay for. Infrared answers at a name such as infrared.example.com, and your environments at <environment>.<domain>.

• Google service accounts in your project, each bound to its Kubernetes ServiceAccount by Workload Identity:

  Service account for	Chart value	Bound to	Roles
  Reaching your orgs' cloud accounts	cloudIdentity.gcpServiceAccount	infrared/infrared-cloud	None in the project. Each org grants it roles/iam.serviceAccountTokenCreator on a service account of its own
  Backups to Cloud Storage (optional)	the backup's gcs destination	the backup Jobs	Read and write on the bucket

• A forge: a GitHub organization you administer, or none, in which case Infrared keeps your repos in its own Gitea on the cluster.

• No license yet. Infrared 0.1 runs with no license through November 30, 2026 (UTC). See Licensing.

1. Write your values file

The chart infrared wraps the chart infrared-core, so every value goes under infrared-core:.

# infrared-values.yaml
infrared-core:
  managementCluster:
    name: acme-cp
  cloud: gcp
  image:
    registry: us-central1-docker.pkg.dev/darkshift-public/infrared            # Infrared's public images
  gitops:
    chartRepository: us-central1-docker.pkg.dev/darkshift-public/infrared/charts  # where Argo CD pulls Infrared's chart from for upgrades
  installation:
    edge: gateway
    previews:
      domain: apps.example.com                 # environments answer at <environment>.apps.example.com
      signInURL: https://infrared.example.com  # Infrared's own address
  cloudIdentity:
    gcpServiceAccount: infrared-cloud@<project>.iam.gserviceaccount.com
  # gitea:
  #   enabled: true                            # to keep your repos in Infrared's own Gitea instead of GitHub

Every value is in Chart values below. Never put a token in this file: tokens go to helm with --set-file, read from a file only you can read.

2. Install

helm install infrared oci://us-central1-docker.pkg.dev/darkshift-public/infrared/charts/infrared \
  --version 0.1.0 \
  --kube-context <your GKE context> \
  --namespace infrared --create-namespace \
  --values infrared-values.yaml \
  --set-file infrared-core.platformTokens.cloudflareApiToken=$HOME/.secrets/cloudflare-token

Name the cluster with --kube-context rather than relying on your current context. With a license from darkshift, add --set-file infrared-core.license.key=infrared.license; without one, the install runs in the open beta.

Watch the install come up:

kubectl --context <your GKE context> get installation infrared -w

3. Run the setup wizard

When the Installation reaches AwaitingToken, read the one-time setup token and open the UI through a port-forward:

kubectl --context <your GKE context> -n infrared get secret infrared-setup -o jsonpath='{.data.token}' | base64 -d; echo
kubectl --context <your GKE context> -n infrared port-forward svc/infrared 8080:80

Open http://localhost:8080 and follow the setup wizard: it creates the root user and the platform org, confirms the management cluster, connects GitHub or Gitea, creates your gitops repo, and hands Infrared to Argo CD. When it is Ready, Infrared answers at its own address, https://infrared.example.com.

Chart values

Each value goes under infrared-core: in your values file.

Value	What it does
managementCluster.name	Names the management cluster, and the folder registry/clusters/<cluster>/ in your gitops repo. Default infrared-mgmt.
cloud	gcp or aws: the cloud the management cluster runs in. Empty means gcp.
image.registry	The registry every component image is pulled from, as <registry>/infrared-<component>:<tag>@<digest>. Set it to Infrared's public registry, us-central1-docker.pkg.dev/darkshift-public/infrared.
gitops.chartRepository	The OCI repository Argo CD pulls Infrared's chart from for upgrades, with no oci://. Set it to us-central1-docker.pkg.dev/darkshift-public/infrared/charts.
installation.edge	gateway for the Envoy Gateway edge behind Cloudflare. Empty means Traefik Ingresses.
installation.previews.domain, installation.previews.signInURL	Where environments answer, and Infrared's own address.
registryToken.gcpServiceAccount, registryToken.aws.*	Only for images in a private registry: pulls them with a short-lived token, from Workload Identity on GKE or ECR on AWS. Leave it out for Infrared's public registry.
cloudIdentity.*	The identity Infrared reaches your orgs' cloud accounts as. See Cloud accounts.
license.key, license.existingSecret	The license from darkshift, passed with --set-file, or the name of a Secret that holds it.
gitea.enabled	Runs Gitea beside Infrared, so the setup wizard can keep your repos and gitops repo there instead of on GitHub. Off by default.
builds.registry	Turns on Product builds: the registry kpack pushes Product images to, such as your Artifact Registry. See Deliver a single app.
backup.*	Where backups go, when they are made and who can open them. You can also set this later in Settings → Backups. See Back up and restore.
platformTokens.*	Tokens Infrared's own components use, such as the Cloudflare token and an optional Google OAuth client for Sign in with Google. Always pass them as secrets.
api.flags	The install's own words and links: signInNotice (a line under the sign-in page's heading), usageNotice (a line on each org's Usage page saying who pays for agent runs), supportAddress, termsURL and privacyURL (links in the sign-in page's footer), and hideClusters (leaves Clusters off the rail, for an install whose orgs have no clusters of their own). After setup, change them in the install's values file in your gitops repo.
gitops.templateVersion	The gitops template your repo is hydrated from. Each chart defaults to the one it was released with.

After setup

Argo CD adopts Infrared from your gitops repo at sync wave 40. 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.

Then:

• set your org's model key and invite your team: see After the wizard;
• set up backups to a Cloud Storage bucket, if you skipped them in the wizard;
• add cloud accounts and workload clusters, built from the GKE or EKS template;
• create your first Product and ask for your first Change.

Troubleshooting

Symptom	Likely cause	What to do
Pods stuck in ImagePullBackOff	image.registry is not Infrared's public registry, or the cluster can't reach it. With a private registry, the registry token can't read it.	Check image.registry is us-central1-docker.pkg.dev/darkshift-public/infrared, and that nodes reach the internet. With registryToken.gcpServiceAccount, the registry-token Job's logs in the namespace infrared show the error.
Infrared's address doesn't answer	The edge's DNS records or origin certificate aren't there yet, or the Cloudflare token can't make them.	The Applications external-dns and edge in Argo CD show the error. Check the token's permissions on the zone.
The wizard says The setup token was not accepted	The token was copied incompletely, or comes from another install.	Read it again with the command in step 3, from this cluster's context.
helm install says the release infrared already exists	The cluster already has Infrared.	Install on a fresh cluster, or restore onto one.

For more, see Troubleshooting.