Installation

📦 Introduction

This guide will walk you through installing kubriX in different environments - from quick local demos to production-ready clusters.

kubriX is modular by design, so you can start small and scale as your needs grow.
Whether you’re exploring kubriX for the first time or deploying for team use, you’ll find the right path here.

---

✅ Prerequisites

Before installing kubriX, make sure you have:

• Kubernetes: v1.26+ (tested on KinD, K3s, EKS, AKS, GKE, and on-prem)

• Command-line tools:

  • kubectl – Kubernetes CLI
  • helm – Helm package manager
  • git – Version control
  • jq – json processor
  • yq – yaml processor
  • docker – Container runtime (for local installs only)
  • mkcert - tool for making locally-trusted development certificates (for local installs only)
  • kind - create a Kubernetes in Docker (for local installs only)

• Cluster resources:

  • Minimum: 4 CPU cores, 16 GB RAM, 20 GB storage
  • Recommended for production: 8+ CPU cores, 20 GB+ RAM

• Network connectivity to pull container images and helm charts from public repositories

💡 Info: completely air-gapped day-1 installations are not supported yet, but you can customize kubriX on day-2 to support air-gapped environments.

---

🛤 Choose Your Installation Path

Environment	Goal	Install Guide
GitHub Codespaces (Experimental)	Explore kubriX instantly in your browser	Codespaces Installation
Local KinD	Try kubriX quickly on your laptop	Demo-Stack local KinD
Demo Kubernetes Cluster	Test a demo stack on a K8s cluster on your preferred cloud provider	Demo-Stack on Kubernetes
Production Kubernetes Cluster	Set up kubriX for productive team use	Production Installation

💡 Tip: If you’re unsure where to start, try the KinD installation - it’s the fastest way to get kubriX running locally.

---

🔑 Post-Installation Steps

Create Github OAuth App and set secrets in vault

The Platform-Portal authenticates via GitHub OAuth App. Therefore you need to create a OAuth App in your developer settings. Click the button "New OAuth App".

For local KinD Cluster:

• Homepage URL: https://backstage.127-0-0-1.nip.io
• Authorization callback URL: https://backstage.127-0-0-1.nip.io/api/auth/github

For remote Kubernetes Cluster:

• Homepage URL and Authorization callback URL must match "https://backstage.${KUBRIX_CUSTOMER_DOMAIN}"

Example:

• Homepage URL: backstage.demo-johnny.kubrix.cloud
• Authorization callback URL: backstage.demo-johnny.kubrix.cloud/api/auth/github

After clicking "Register application", click on "Generate a new client secret".

Use the value of the "Client ID" for the variable GITHUB_CLIENTID in the step below. Use the generated client secret as the value for the variable GITHUB_CLIENTSECRET in the step below.

Then set GITHUB_CLIENTSECRET and GITHUB_CLIENTID from your Github OAuth App and set them in vault via kubectl/curl:

export GITHUB_CLIENTID="<client-id-from-step-before>"
export GITHUB_CLIENTSECRET="<client-secret-from-step-before>"
export VAULT_HOSTNAME=$(kubectl get ingress -o jsonpath='{.items[*].spec.rules[*].host}' -n vault)
export VAULT_TOKEN=$(kubectl get secret -n vault vault-init -o=jsonpath='{.data.root_token}'  | base64 -d)
curl -k --header "X-Vault-Token:$VAULT_TOKEN" --request PATCH --header "Content-Type: application/merge-patch+json" --data "{\"data\": {\"GITHUB_CLIENTSECRET\": \"${GITHUB_CLIENTSECRET}\", \"GITHUB_CLIENTID\": \"${GITHUB_CLIENTID}\"}}" https://${VAULT_HOSTNAME}/v1/kubrix-kv/data/portal/backstage/base
kubectl delete externalsecret -n backstage sx-cnp-secret
kubectl rollout restart deployment -n backstage sx-backstage

Define user entities in backstage

Before users can login via GitHub in backstage, there needs to be a matching User entity in your own kubriX repo in backstage-resources/entities/all.yaml

apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: <github-user>
spec:
  profile:
    displayName: <github-user>
    email: guest@example.com
    picture: https://api.dicebear.com/9.x/adventurer-neutral/svg
  memberOf: [kubrix]

Login

When kubriX installed sucessfully you can access the platform services via these URLs and login with these credentials:

Tool	URL	Username	Password
Backstage	https://backstage.127-0-0-1.nip.io	via github	via github
ArgoCD	https://argocd.127-0-0-1.nip.io/	admin	kubectl get secret -n argocd argocd-initial-admin-secret -o=jsonpath='{.data.password}' | base64 -d
Kargo	https://kargo.127-0-0-1.nip.io	admin	-
Grafana	https://grafana.127-0-0-1.nip.io	kubectl get secret -n grafana grafana-admin-secret -o=jsonpath='{.data.userKey}' | base64 -d	kubectl get secret -n grafana grafana-admin-secret -o=jsonpath='{.data.passwordKey}' | base64 -d
Keycloak	https://keycloak.127-0-0-1.nip.io	admin	kubectl get secret -n keycloak keycloak-admin -o=jsonpath='{.data.admin-password}' | base64 -d
FalcoUI	https://falco.127-0-0-1.nip.io	kubectl get secret -n falco falco-ui-creds -o=jsonpath='{.data.FALCOSIDEKICK_UI_USER}' | base64 -d | awk -F: '{print $1}'	kubectl get secret -n falco falco-ui-creds -o=jsonpath='{.data.FALCOSIDEKICK_UI_USER}' | base64 -d | awk -F: '{print $2}'

Verify installation

Check if all ArgoCD applications are synced and healthy:

kubectl get applications -n argocd

🐞 Known issue: The application sx-bootstrap-app can be OutOfSync periodically due to the sub-application sx-kyverno.
This will get fixed with https://github.com/suxess-it/kubriX/issues/1406

Next steps

• Configuration Guide – customize kubriX for your needs
• User Guide – start deploying apps

🩺 Troubleshooting Installation

If something goes wrong:

Verify if all apps are Synced and Healthy:

kubectl get applications -n argocd

Check if all pods are running:

kubectl get pods -A

Check logs of the unhealthy apps and pods:

kubectl logs -n <namespace> <pod-name>

💡 Tips: Try K8sGPT to analyze your environment. We will integrate this tool in the future probably also in kubriX.

Consult the Troubleshooting Guide for common fixes.

🗑 Uninstalling kubriX

local KinD cluster

Delete your local KinD cluster:

kind delete cluster --name kubrix-local-demo

Remote Kubernetes cluster

Delete your remote Kubernetes cluster via your cloud providers APIs.

Delete kubriX gitops repo

Also delete your created kubriX gitops repository you defined in variable KUBRIX_CUSTOMER_REPO on your Git-Server.

📂 Installation Guides

• Codespaces Installation
• Demo-Stack local KinD
• Demo-Stack Remote Kubernetes
• Production Kubernetes Installation