Kubernetes with RubixKube

RubixKube runs on every conformant Kubernetes cluster on v1.24 or later. One kubectl apply installs the Observer into a dedicated namespace. Everything else runs in RubixKube Cloud. This page covers the install, what it deploys, common troubleshooting, and how to uninstall cleanly.

Prerequisites

kubectl configured

kubectl get nodes should succeed against the target cluster.

Cluster admin permissions

Required to create the rubixkube-system namespace, service account, and ClusterRole.

Outbound access

HTTPS to api.rubixkube.ai:443 and TCP to nats.rubixkube.ai:4222, reachable from the cluster.

A RubixKube workspace

Install

Copy the personal install command from the console. Your API key (prefix rk_) is already embedded.

kubectl apply -f "https://api.rubixkube.ai/install/observer.yaml?apiKey=rk_YOUR_API_KEY"

Always copy the command from the console. The embedded API key scopes the Observer to your workspace.

You should see:

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

Verify

Check the pod

kubectl get pods -n rubixkube-system

Wait for STATUS to show Running:

NAME                                  READY   STATUS    RESTARTS   AGE
rubixkube-observer-7d4b9c8f6d-abc12   1/1     Running   0          2m

Tail the logs

kubectl logs -n rubixkube-system deployment/rubixkube-observer --tail=20

Expect to see Connected to api.rubixkube.ai and topology sweep messages within the first minute.

Confirm in the console

Open Environments in the console. The environment card should switch from Connecting to Healthy and the Infrastructure view should populate with nodes, namespaces, and workloads.

What is being monitored

The Observer collects signals for every native Kubernetes object plus the common extensions.

Signal	Detail
Pods	State, restart count, resource usage, owner references
Deployments, StatefulSets, DaemonSets	Replica health, rollout state, condition history
Services and Ingress	Endpoint health, routing, LoadBalancer status
Nodes	CPU, memory, disk, allocatable and capacity, pressure conditions
Events	Cluster event bus, filtered and streamed structurally
PVs and PVCs	Binding state, storage class, capacity
ConfigMaps and Secrets (metadata only)	Names, keys, revision. No values unless explicitly enabled

Footprint

The Observer is deliberately light.

One pod. The Observer serves its own read-only Kubernetes tools, so no separate MCP server runs.
About 20Mi of RAM and 10 millicores on a one-node test cluster with 32 workloads. The pod requests 128Mi and is limited to 512Mi.
Under 10 millicores of CPU during normal operation.
Scales modestly with cluster size. Expect another 50Mi of RAM per 100 nodes.

Cloud-side agents (RCA Pipeline, Memory, Guardian, Remediation) run in RubixKube Cloud. Your cluster hosts only the Observer.

Upgrade

Run the install command again, copied from the console. It updates the Observer in place and keeps the environment, its history and its settings.

kubectl apply -f "https://api.rubixkube.ai/install/observer.yaml?apiKey=rk_YOUR_API_KEY"

Installs from before Observer 1.1.0 also ran a Kubernetes MCP server next to the Observer. It is no longer needed. Remove it after the upgrade:

kubectl -n rubixkube-system delete deploy/kubernetes-mcp-server svc/kubernetes-mcp-server sa/kubernetes-mcp-server
kubectl delete clusterrole,clusterrolebinding kubernetes-mcp-server-readonly

Then remove the kubernetes entry from the mcp-config ConfigMap, or delete the ConfigMap if that was its only entry:

kubectl -n rubixkube-system edit configmap mcp-config

Add your own MCP servers

The Observer reads extra MCP servers from the optional ConfigMap mcp-config (key mcp.json) in rubixkube-system. The install command never overwrites it.

kubectl -n rubixkube-system create configmap mcp-config --from-file=mcp.json=./mcp.json
kubectl -n rubixkube-system rollout restart deploy/rubixkube-observer

{
  "mcpServers": {
    "grafana": { "url": "http://mcp-grafana.monitoring.svc.cluster.local:8000/mcp" }
  }
}

Each server’s state (connected or failing, with the error) shows on the environment’s page in the console.

KIND and local development

Same install command works on KIND. Useful when you want to evaluate without touching a real cluster.

kind create cluster --name rubixkube-test
kubectl apply -f "https://api.rubixkube.ai/install/observer.yaml?apiKey=rk_YOUR_API_KEY"

KIND is the path most teams use for the tutorials before running against real infrastructure.

Troubleshooting

Pod stuck in ImagePullBackOff

The cluster cannot reach the Observer image registry. Check outbound egress to api.rubixkube.ai:443:

kubectl run test-curl --image=curlimages/curl -i --rm -- curl -I https://api.rubixkube.ai

If this fails, your cluster is behind a proxy or egress policy. Allowlist the two endpoints or reach out for an air-gapped deployment path.

Pod in CrashLoopBackOff

Almost always an invalid API key. Check the logs:

kubectl logs -n rubixkube-system deployment/rubixkube-observer --previous

If you see 401 Unauthorized or invalid api key, reinstall with the command copied fresh from the console.

Environment stuck on Connecting

Three common causes:

Pod is not Running yet. Recheck kubectl get pods -n rubixkube-system.
Outbound TCP to nats.rubixkube.ai:4222 is blocked. The control channel runs over HTTPS but the streaming channel uses NATS.
Clock skew on the node. Ensure NTP is running.

Observer high memory or CPU

Rare, but possible on very large clusters. Edit the deployment to raise limits, or reach out and we will help you size the Observer for your cluster shape.

kubectl edit deployment rubixkube-observer -n rubixkube-system

AKS and Azure

AKS clusters are supported today on the Kubernetes path. Install exactly as you would on EKS or GKE. Subscription-level Azure observation (App Service, Azure VMs) is on the roadmap, see Azure.

Uninstall

kubectl delete -f "https://api.rubixkube.ai/install/observer.yaml?apiKey=rk_YOUR_API_KEY"

This removes the namespace, service account, ClusterRole, binding, and deployment. The environment card in the console can then be deleted.

Connect your environment

The full install flow covering every supported environment.

Observer Agent concept

What the Observer does, where it runs, what it sees.

First tutorial

Monitor infrastructure health once the Observer is live.

​Prerequisites

kubectl configured

Cluster admin permissions

Outbound access

A RubixKube workspace

​Install

​Verify

Check the pod

Tail the logs

Confirm in the console

​What is being monitored

​Footprint

​Upgrade

​Add your own MCP servers

​KIND and local development

​Troubleshooting

​AKS and Azure

​Uninstall

​Related guides

Connect your environment

Observer Agent concept

First tutorial

Prerequisites

Install

Verify

What is being monitored

Footprint

Upgrade

Add your own MCP servers

KIND and local development

Troubleshooting

AKS and Azure

Uninstall

Related guides