Install on GKE

GKE is where darkshift runs its own Infrared control plane, infrared.darkshift.io, and the install path we use every day. Infrared reaches Google Cloud through Workload Identity, never a key: for pulling its images, for backups to Cloud Storage and for 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 (darkshift's control plane runs 3 e2-standard-4 nodes, on-demand, which also run Infrared's own 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.

• Access to the chart and images, and the ir CLI, from darkshift. See What every self-hosted install needs.

• 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. There is no cloud load balancer to pay for. Infrared answers at a name such as infrared.example.com, and Product 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
  Pulling Infrared's images and chart	registryToken.gcpServiceAccount	infrared/registry-token	Read on the registry darkshift gives you
  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 license from darkshift, or start on the 48-hour trial (Licensing).

• A GitHub organization you administer, or none: Infrared can keep your repos in its own Gitea.

1. Write the install file

ir install reads one file, infrared.yaml, with the chart to install, its values file, and where each secret comes from. Secrets reach helm on a file descriptor from a file or a command, never as an argument and never in the file.

# infrared.yaml
install:
  chart: oci://<registry from darkshift>/charts/infrared
  version: <version from darkshift>
  values: infrared-values.yaml
  secrets:
    - value: platformTokens.cloudflareApiToken
      file: ~/.secrets/cloudflare-token
setup:                       # the setup wizard's answers, for --setup
  admin: {email: [email protected]}
  org: {name: acme, displayName: Acme}
  cluster: acme-cp
  forge: github              # or gitea
  gitops: {name: gitops, visibility: private}

# infrared-values.yaml
managementCluster:
  name: acme-cp
cloud: gcp
installation:
  edge: gateway
  previews:
    domain: apps.example.com                 # environments answer at <environment>.apps.example.com
    signInURL: https://infrared.example.com  # Infrared's own address
registryToken:
  gcpServiceAccount: infrared-registry@<project>.iam.gserviceaccount.com
cloudIdentity:
  gcpServiceAccount: infrared-cloud@<project>.iam.gserviceaccount.com

The chart's values are listed in Chart values below.

2. Install

ir install --context <your GKE context> -f infrared.yaml --license <license file> --setup --wait

ir always names the cluster by --context and never uses your current context. It:

1. runs the one helm install, as the release infrared in the namespace infrared, and writes the license into the Secret infrared-license;
2. with --setup, runs the setup wizard's steps from the file. The root user gets a password ir never keeps; ir saves an API token instead. Set the root user's real password later in Access → Break glass;
3. with --wait, waits until the Installation is Ready and every Argo CD Application is Synced and Healthy, then signs ir in at https://infrared.example.com.

Each phase prints a TIME step= line. Without --license, the install starts its 48-hour trial.

Then open it in a browser, signed in:

ir open

Or run the wizard in a browser

Leave out --setup --wait and ir install stops after the helm install. Read the one-time setup token, open the UI through a port-forward and follow the setup wizard:

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

Chart values

Value	What it does
managementCluster.name	Names the Cluster resource for this cluster and the folder registry/clusters/<cluster>/ in your gitops repo. Default infrared-mgmt.
cloud	gcp or aws: which of darkshift's registries the images and chart come from by default.
image.registry	Overrides the registry every component image is pulled from, as <registry>/infrared-<component>:<tag>@<digest>.
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.region	Pull Infrared's images with a short-lived token from Workload Identity on GKE, or ECR's token on AWS. No pull secret to manage.
cloudIdentity.*	The identity Infrared reaches your orgs' cloud accounts as. See Cloud accounts.
license.key, license.existingSecret	The license from darkshift, with --set-file, or the name of a Secret that holds it. ir install --license does this for you.
builds.registry	Turns on Product builds: the registry prefix kpack pushes Product images to, such as your Artifact Registry. See Deliver a single app.
backup.*	The backup destination, schedule and recipients; also settable 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.
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.

Next:

• add cloud accounts and workload clusters, built from the GKE or EKS template;
• set up backups to a Cloud Storage bucket;
• create your first Product.

Troubleshooting

Symptom	Likely cause	What to do
Pods stuck in ImagePullBackOff	The registry token can't read the registry: the service account lacks read on it, or its Workload Identity binding is missing.	The registry-token Job's logs in namespace infrared show the error. Check registryToken.gcpServiceAccount's roles and its roles/iam.workloadIdentityUser binding.
ir install says Infrared is already there	The cluster already has a release in infrared.	ir install never installs over an install. Use a fresh cluster, or restore onto one.
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 above, from this cluster's context.