Skip to main content
Welcome! This guide will help you install RubixKube on your local machine using KIND (Kubernetes in Docker). This is perfect for:
  • Testing RubixKube before deploying to production
  • Learning how RubixKube works in a safe environment
  • Development on your laptop without cloud costs
  • Training team members on RubixKube features
Complete Beginner?No problem! We’ll walk you through installing everything from scratch, even if you’ve never used Docker or Kubernetes before.

​
What You’ll Install

Before we can run RubixKube locally, we need a few tools:

Docker

Container runtime that runs Kubernetes

KIND

Runs Kubernetes clusters locally in Docker

kubectl

Command-line tool to interact with Kubernetes
Estimated Time:20-30 minutes for first-time installation (including downloads)

​
Step 1: Install Docker

Docker is required to run KIND. Choose your operating system below:
  • macOS
  • Windows
  • Linux

​
Install Docker Desktop on macOS

If you have Homebrew installed:
brew install --cask docker

​
Option 2: Download from Docker Website

  1. Visit Docker Desktop for Mac
  2. Click “Download for Mac”
  3. Choose your Mac type:
    • Apple Silicon (M1/M2/M3 Macs)
    • Intel Chip (older Macs)
  4. Open the downloaded .dmg file
  5. Drag Docker icon to Applications folder
  6. Launch Docker from Applications

​
Verify Docker Installation

Open Terminal and run:
docker --version
You should see output like:
Docker version 24.0.6, build ed223bc
First Time?Docker may ask for system permissions. Click “OK” to allow it.

​
Step 2: Install KIND

KIND (Kubernetes in Docker) creates Kubernetes clusters using Docker containers as nodes.
  • macOS
  • Windows
  • Linux

​
Install KIND on macOS

brew install kind

​
Manual Installation:

# Download KIND binary
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-darwin-amd64

# Make it executable
chmod +x ./kind

# Move to system path
sudo mv ./kind /usr/local/bin/kind

​
Verify KIND Installation

kind --version
Expected output:
kind version 0.20.0

​
Step 3: Install kubectl

kubectl is the command-line tool for interacting with Kubernetes clusters.
  • macOS
  • Windows
  • Linux

​
Install kubectl on macOS

brew install kubectl

​
Manual Installation:

# Download kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

# Make it executable
chmod +x ./kubectl

# Move to system path
sudo mv ./kubectl /usr/local/bin/kubectl

​
Verify kubectl Installation

kubectl version --client
Expected output:
Client Version: v1.28.2

​
Step 4: Create a KIND Cluster

Now that we have all prerequisites installed, let’s create a local Kubernetes cluster!

​
Create Your Cluster

Run this command in your terminal: 
kind create cluster --name rubixkube-local
What’s happening? - KIND creates a Kubernetes cluster running inside Docker containers
  • The cluster is named rubixkube-local
  • This takes 1-2 minutes

​
Expected Output:

Creating cluster "rubixkube-local" ...
  Ensuring node image (kindest/node:v1.27.3) 
  Preparing nodes 
  Writing configuration 
  Starting control-plane 
  Installing CNI 
  Installing StorageClass 
Set kubectl context to "kind-rubixkube-local"
You can now use your cluster with:

kubectl cluster-info --context kind-rubixkube-local
Pro Tip:The cluster automatically sets itself as your active Kubernetes context, so kubectl commands will target it.

​
Verify Your Cluster is Running

kubectl cluster-info
Expected output: 
Kubernetes control plane is running at https://127.0.0.1:xxxxx
CoreDNS is running at https://127.0.0.1:xxxxx/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Check that nodes are ready: 
kubectl get nodes
Expected output: 
NAME                            STATUS   ROLES           AGE   VERSION
rubixkube-local-control-plane   Ready    control-plane   1m    v1.27.3
Troubleshooting:If the node shows “NotReady”, wait 30 seconds and check again. It takes time to initialize.

​
Step 5: Install RubixKube Observer

Now let’s install the RubixKube observer agent on your local cluster!

​
Get Your Installation Command

  1. Log in to RubixKube Console at console.rubixkube.ai
  2. After login, you’ll see the “Connect Your First Cluster” onboarding screen
  3. Copy the kubectl command shown on the page
It will look something like this: 
kubectl apply -f "https://api.rubixkube.ai/install/observer.yaml?apiKey=rk_YOUR_API_KEY_HERE"
RubixKube dashboard showing installation command
Important:Use YOUR specific command from the dashboard - it contains your unique API key!

​
Run the Installation Command

Paste your command into the terminal and press Enter: 
kubectl apply -f "https://api.rubixkube.ai/install/observer.yaml?apiKey=rk_YOUR_API_KEY_HERE"

​
Expected Output:

namespace/rubixkube-system created
serviceaccount/rubixkube-observer created
clusterrole.rbac.authorization.k8s.io/rubixkube-observer created
clusterrolebinding.rbac.authorization.k8s.io/rubixkube-observer created
deployment.apps/rubixkube-observer created
configmap/rubixkube-config created
secret/rubixkube-credentials created
What just happened?RubixKube installed an “observer” agent in your cluster that monitors your infrastructure and reports back to the RubixKube platform.

​
Step 6: Verify RubixKube Installation

Let’s make sure RubixKube is running correctly in your cluster!

​
Check if Pods are Running

kubectl get pods -n rubixkube-system
Initial output (pods are starting): 
NAME                                  READY   STATUS              RESTARTS   AGE
rubixkube-observer-7d4b9c8f6d-x7k2p   0/1     ContainerCreating   0          10s
Wait 30-60 seconds, then run the command again: 
kubectl get pods -n rubixkube-system
Success! You should see: 
NAME                                  READY   STATUS    RESTARTS   AGE
rubixkube-observer-7d4b9c8f6d-x7k2p   1/1     Running   0          1m
READY column shows: 1/1 (1 out of 1 containers ready)
STATUS column shows: Running
RESTARTS column shows: 0 (or low number)This means RubixKube observer is:
  • Successfully deployed
  • Running and healthy
  • Connected to RubixKube cloud
  • Monitoring your cluster
This means Docker couldn’t download the RubixKube image.Common causes: - Internet connection issues
  • Docker Hub rate limits
Solution: Wait 2-3 minutes and check again:
kubectl get pods -n rubixkube-system
If still failing after 5 minutes, delete and reinstall:
kubectl delete namespace rubixkube-system
# Wait 30 seconds, then run the install command again
This means the pod started but crashed.Check logs to see why: ```bash kubectl logs -n rubixkube-system deployment/rubixkube-observer

**Common causes:**    - Invalid API key
- Configuration error

**Solution:**    1. Double-check you used YOUR api key from the dashboard
2. Delete and reinstall with correct command:
```bash
kubectl delete namespace rubixkube-system
# Get fresh command from dashboard and run it
Get detailed information about the pod:
kubectl describe pod -n rubixkube-system -l app=rubixkube-observer
This shows:
  • Events (what happened during startup)
  • Container status
  • Resource usage
  • Error messages (if any)

​
Check Observer Logs

See what RubixKube observer is doing: 
kubectl logs -n rubixkube-system deployment/rubixkube-observer
Healthy logs look like: 
[INFO] RubixKube Observer starting...
[INFO] Connected to RubixKube API
[INFO] Cluster registration successful
[INFO] Starting infrastructure monitoring
[INFO] Watching namespaces: all
[INFO] Agent mesh initialized
Tip:If you see steady log output with [INFO] messages, everything is working correctly!

​
Verify in RubixKube Dashboard

  1. Go back to console.rubixkube.ai
  2. You should see your cluster appear in the dashboard
  3. The Observer Status should change from “Awaiting installation” to “Connected”
Note:It may take 1-2 minutes for your cluster to appear in the dashboard after the pod starts running.

​
Step 7: Deploy a Test Application (Optional)

Want to see RubixKube in action? Let’s deploy a simple app to monitor!

​
Deploy Nginx

kubectl create deployment nginx --image=nginx:latest
kubectl expose deployment nginx --port=80 --type=NodePort

​
View Your Workloads

kubectl get deployments
kubectl get pods
kubectl get services

​
Check RubixKube Dashboard

Go to console.rubixkube.ai and navigate to:
  • Dashboard - See cluster health
  • Infrastructure - View your nginx deployment
  • Chat - Ask “What pods are running?”

​
Managing Your KIND Cluster

​
Useful Commands

List all KIND clusters: 
kind get clusters
Stop your cluster (cluster persists, just stops): 
docker stop rubixkube-local-control-plane
Start your cluster again: 
docker start rubixkube-local-control-plane
Delete your cluster (removes everything): 
kind delete cluster --name rubixkube-local
Create cluster with custom configuration: 
cat > kind-config.yaml <<'EOF'
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
EOF

kind create cluster --name rubixkube-local --config=kind-config.yaml

# Clean up config file
rm kind-config.yaml
This creates a cluster with 1 control plane and 2 worker nodes.

​
Common Issues & Solutions

Error: Cannot connect to the Docker daemonSolution: - macOS/Windows: Open Docker Desktop app and wait for it to start
  • Linux: Run sudo systemctl start docker
Error: failed to create clusterSolutions: 1. Ensure Docker has enough resources (4GB+ RAM recommended) 2. Check Docker is running: docker ps 3. Delete any existing cluster: kind delete cluster --name rubixkube-local 4. Try creating again
Error: kubectl: command not foundSolution: - Kubectl is not in your system PATH
  • Re-install kubectl and ensure it’s added to PATH
  • Try full path: /usr/local/bin/kubectl (macOS/Linux)
Error: address already in useSolution: Another process is using Kubernetes default ports.Delete existing KIND clusters:
kind delete cluster --name rubixkube-local
Or specify custom ports when creating cluster.

​
Check these:

  1. Verify API key is correct
kubectl get secret -n rubixkube-system rubixkube-credentials -o yaml
  1. Check pod events
kubectl describe pod -n rubixkube-system -l app=rubixkube-observer
  1. View logs
kubectl logs -n rubixkube-system deployment/rubixkube-observer
  1. Reinstall
kubectl delete namespace rubixkube-system
# Wait 30 seconds, then run install command again

​
Next Steps

Explore the Dashboard

Take a tour of the RubixKube console and learn the basics

Try Breaking Things

See RubixKube detect and fix issues automatically

Deploy to Production

Ready for production? Install on a real cloud cluster

Chat with Your Infrastructure

Learn how to use natural language to query your cluster

​
System Requirements

​
Minimum Requirements

ComponentRequirement
OSmacOS 10.15+, Windows 10+, Linux (any modern distro)
RAM4GB minimum, 8GB recommended
Disk Space20GB free space
CPU2 cores minimum, 4 cores recommended
DockerVersion 20.10+
InternetRequired for installation and RubixKube sync

​
For Production-Like Testing

ComponentRecommendation
RAM16GB+
CPU4+ cores
DiskSSD with 50GB+ free

​
Comparison: KIND vs Cloud

FeatureKIND (Local)Cloud Cluster
CostFreePaid
Setup Time5-10 minutes10-30 minutes
Use CaseTesting, LearningProduction
PerformanceLimited by your machineFull cloud resources
PersistenceData lost when cluster deletedPersistent storage
Internet AccessWorks offline (after setup)Always requires internet
Load BalancersSimulated onlyReal cloud load balancers
Best Practice:Start with KIND to learn RubixKube, then move to cloud for production workloads.

​
Need Help?

Support

Email us at [email protected]

Troubleshooting Guide

Visit our troubleshooting page

Community

Join our Slack community for help

Documentation

Browse our complete docs
Stuck?Don’t hesitate to reach out. We’re here to help you get started with RubixKube!