Skip to content

Connect Kubernetes to Xplorr: OpenCost Cost Allocation for Any Cluster

Xplorr reads Kubernetes cost data from OpenCost, the open source Kubernetes cost monitor. Once a cluster is connected, Xplorr splits its cost by namespace, controller, pod and pod label, and reports idle capacity separately from workload cost.

Xplorr never talks to your Kubernetes API server and never holds cluster credentials. It only reads what OpenCost has already computed.

Xplorr reads what OpenCost has computed, so OpenCost has to be running in the cluster.

If you connect a private cluster the recommended way, the Xplorr chart installs it for you and you can skip this section. The chart also sets OpenCost’s CLUSTER_ID from the cluster name you give it, which is the part people most often get wrong.

Install it yourself if you use pull mode, or if you would rather run your own OpenCost. Follow the OpenCost installation guide. A default install exposes the OpenCost API on port 9003, as the service opencost in the opencost namespace.

Check that the API answers from inside the cluster before going further:

Terminal window
kubectl -n opencost port-forward service/opencost 9003:9003

Then, in another terminal:

Terminal window
curl -sS "http://localhost:9003/allocation?window=1d&aggregate=namespace&step=1d"

A healthy OpenCost returns JSON with "code": 200 and a data array. If that call fails, fix OpenCost first. Everything below depends on it.

Check CLUSTER_ID before you trust the numbers

Section titled “Check CLUSTER_ID before you trust the numbers”

This applies to an OpenCost you installed yourself. The Xplorr chart sets it from the cluster name, through a ConfigMap OpenCost reads it from, so the two cannot drift apart.

“OpenCost is running” is not the same as “OpenCost is configured for this cluster”. CLUSTER_ID is the name OpenCost stamps on everything it reports, and a values file copied from another environment carries the old name with it. Nothing in OpenCost complains, and the cost data looks perfectly normal.

Check what the running deployment actually has:

Terminal window
kubectl -n opencost get deploy opencost \
-o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="CLUSTER_ID")].value}'

If that prints another environment’s name, set it on the OpenCost side (extraEnv.CLUSTER_ID in the Helm values, or the CLUSTER_ID env var on the deployment) and roll it out.

This is not the cluster name you type into Xplorr. The two are independent:

Set where Used for
Xplorr cluster name Xplorr, when you add the cluster How the cluster appears in Xplorr, and which ingest token belongs to it
OpenCost CLUSTER_ID OpenCost’s own config in the cluster The label OpenCost puts on the data it serves to anyone reading its API

Xplorr attributes cost by the ingest token and the endpoint, not by CLUSTER_ID, so a wrong value does not misfile your cost in Xplorr. It does mislead anyone reading OpenCost directly for debugging, dashboards or other tooling. Fixing one does not fix the other.

By default OpenCost prices nodes from public on-demand rates. If the cluster runs on reservations, savings plans, spot or a negotiated rate, configure OpenCost’s own cloud pricing integration, or its numbers will be close but never right. See the OpenCost cloud costs configuration for the provider you run on.

A cluster whose cost looks plausible but consistently off by a fixed proportion is usually this, not Xplorr.

Dimension What you see
Namespace Total cost per namespace
Controller Cost per Deployment, StatefulSet, DaemonSet, Job and so on, with the controller kind shown beside it
Pod Cost per pod, with its namespace
Label Cost grouped by any pod label key OpenCost reported, for example team or app

Every row is broken into CPU, RAM, GPU, storage (persistent volumes), network (data transfer plus load balancers), shared cost and a total.

Node age and pods running now come from the Kubernetes API. OpenCost reports that a node existed on a day, not how old it is, and keeps no pod status. With the Helm chart (0.3.0 or later), the collector also lists nodes and pods each hour, so the Nodes tab shows each node’s age and whether it is Ready, and the Pod count on the Overview is the pods running now. The Pod table still lists every pod that ran in the range, since finished jobs and pods a rollout replaced cost money too, and marks the ones not running. Without it, the Pod count is every pod seen in the range and node age is blank.

Idle capacity is reported separately. Provisioned node capacity that no workload requested is never spread across namespaces. It appears as its own row so you can see how much of the cluster bill nobody asked for.

Pick the one that matches your network.

Method Best for What it needs
Push, recommended Private clusters, and most clusters generally Outbound HTTPS only. Nothing exposed to the internet.
Pull Clusters whose OpenCost endpoint Xplorr can already reach An ingress or load balancer in front of OpenCost

Push mode is the default in the console, and the one that works for a cluster sitting behind a firewall or on a private network. Pull mode exists for clusters that already publish an OpenCost endpoint.

Behind an egress allowlist? The console shows the collector’s outbound destination, ingest.xplorr.io:443, in the Private cluster setup steps before you connect anything, and as a tooltip on the Waiting for collector status. That’s the one host push mode needs to reach; get it added to your allowlist before you start, rather than discovering it from a failed first run.

The ingest mode is fixed when the cluster is created. To change it, delete the cluster and add it again.

Both paths end up writing the same daily cost rows through the same upsert, so a day that arrives twice is replaced, never counted twice.

A CronJob runs inside your cluster. It reads OpenCost over cluster internal DNS and POSTs the response to Xplorr over outbound HTTPS, carrying a bearer token that can write cost data for that one cluster and nothing else.

Three steps, and the console gives you the command for the third.

Log in to console.xplorr.io and open Kubernetes from the left sidebar. Click Connect cluster. A member or an admin can do this; the person who connects a cluster owns it and can manage its tokens afterwards.

Fill in:

  • Cluster name (required, up to 120 characters), for example prod-eks
  • How cost data reaches Xplorr: choose Private cluster, which is selected by default and marked Recommended
  • Linked cloud account (optional): pick the cloud account that pays for the cluster nodes. See Link a cloud account below.
  • Accept cost data from the collector: leave checked

Click Connect. Xplorr opens the collector dialog straight away, because a push cluster does nothing until its collector is installed.

In the collector dialog, click Generate token.

The token appears once. It starts with xpk8s_ and is 32 bytes of random data behind that prefix.

Copy it now if you want it outside the manifest. Xplorr stores only a SHA-256 hash of it, so nobody, including Xplorr support, can show it to you again. If you lose it, generate a new one and revoke the old one.

What a token can do:

  • Write Kubernetes cost data for exactly one cluster in one organization
  • Nothing else. It cannot read cost data, cannot touch another cluster, and is not an API token.

The dialog shows a command with the token already in it. Copy it and run it:

Terminal window
helm repo add xplorr https://charts.xplorr.io
helm repo update
helm upgrade --install xplorr xplorr/xplorr \
--namespace xplorr --create-namespace \
--set clusterName='prod-eks' \
--set xplorr.clusterId='<the cluster id Xplorr shows you>' \
--set xplorr.ingestToken='xpk8s_...'

That installs three things: OpenCost, a ConfigMap giving OpenCost CLUSTER_ID from clusterName, and the collector.

The chart is public, at Xplorrio/charts. It has no Xplorr binary in it: the collector is a stock curlimages/curl image running two curls, and there is one template to read if someone has to approve it.

You don’t have to know this up front. With installOpenCost left at its default of true, a real helm install or helm upgrade checks for a Service named opencost in the cluster (in the opencost, monitoring and kube-system namespaces by default) before installing anything, and refuses the install if it finds one, naming the namespace and the exact flags to rerun with. It doesn’t reuse what it finds automatically, since a same-named Service that isn’t actually your OpenCost would otherwise silently decide the collector’s behavior. This check only runs on a real install or upgrade; helm template and --dry-run can’t see a live cluster, so a preview always renders as if nothing else is running.

To point the chart at an OpenCost you already run, set it explicitly:

Terminal window
helm upgrade --install xplorr xplorr/xplorr \
--namespace xplorr --create-namespace \
--set clusterName='prod-eks' \
--set xplorr.clusterId='<cluster id>' \
--set xplorr.ingestToken='xpk8s_...' \
--set installOpenCost=false \
--set openCostUrl=http://opencost.opencost.svc.cluster.local:9003

Then check its CLUSTER_ID yourself, because the chart is no longer setting it. If Helm can’t read Services in the namespaces it checks (a namespace-scoped install, for example), the detection finds nothing and installs a second OpenCost with no warning; check for an existing one yourself in that case before installing.

A token passed with --set is stored in Helm’s release Secret. To avoid that, put it in a Secret and point the chart at it:

Terminal window
kubectl -n xplorr create secret generic xplorr-ingest \
--from-literal=token=xpk8s_...
helm upgrade --install xplorr xplorr/xplorr \
--namespace xplorr --create-namespace \
--set clusterName='prod-eks' \
--set xplorr.clusterId='<cluster id>' \
--set xplorr.existingSecret=xplorr-ingest
Value Default
clusterName Required. The name this cluster reports under, and OpenCost’s CLUSTER_ID
xplorr.clusterId Required. The cluster id from the console. A UUID, not clusterName
xplorr.ingestToken The token. Required unless xplorr.existingSecret is set
xplorr.existingSecret A Secret you manage, holding the token under the key token
xplorr.schedule 0 * * * * How often to send, UTC
xplorr.window 3d How far back each run sends
clusterState.enabled true Also list nodes and pods from the Kubernetes API each hour, for node age and pods running now. The collector gets its own ServiceAccount that may only list nodes and pods. Pods are read as name and status only, with no labels, annotations or specs. false gives the collector no Kubernetes API access
installOpenCost true false when you already run OpenCost
openCostUrl Your OpenCost API, required when installOpenCost is false
opencost.* Passed to the OpenCost chart unchanged

If a chart you did not write is not something you can run, the dialog also has the raw manifest behind Prefer kubectl?. Save it as xplorr-collector.yaml and apply it:

Terminal window
kubectl apply -f xplorr-collector.yaml

It installs the collector only, so OpenCost has to be running already and its CLUSTER_ID is yours to set. It contains three objects:

Object Name Purpose
Namespace xplorr-collector Holds the collector, separate from your workloads
Secret xplorr-ingest-token Holds the ingest token, read by the CronJob as an environment variable
CronJob xplorr-cost-collector Runs hourly, reads OpenCost, POSTs the result to Xplorr

Defaults in the generated manifest:

Setting Default Notes
Schedule 0 * * * * (hourly, UTC) concurrencyPolicy: Forbid, so runs never overlap
OpenCost URL http://opencost.opencost.svc.cluster.local:9003 Set through the OPENCOST_URL environment variable
Window 3d Each run re-sends the last three days, so a missed run heals itself
Image curlimages/curl, pinned to an exact tag A stock upstream image, not an Xplorr binary, so you can review what runs
Resources 10m CPU and 32Mi memory requested, 200m and 128Mi limits

The collector posts to https://ingest.xplorr.io/api/v1/kubernetes/ingest/<clusterId>, already filled in as XPLORR_INGEST_URL in the generated manifest, sending the ingest token as a bearer header. That is the only outbound destination it needs, so an egress allowlist only has to permit that host over HTTPS.

If OpenCost does not run in the opencost namespace, edit OPENCOST_URL in the CronJob before applying.

The manifest’s collector does not list nodes and pods (that needs the Helm chart’s clusterState), so node age and pods running now stay blank with it.

The collector pod is deliberately unprivileged: no ServiceAccount token is mounted, the root filesystem is read only, every Linux capability is dropped, it runs as a non root user, and the only secret it holds is the ingest token.

Force a first run rather than waiting for the hour.

Installed with Helm:

Terminal window
kubectl -n xplorr create job xplorr-first-run --from=cronjob/xplorr-collector
kubectl -n xplorr logs job/xplorr-first-run

Applied with kubectl:

Terminal window
kubectl -n xplorr-collector create job xplorr-first-run --from=cronjob/xplorr-cost-collector
kubectl -n xplorr-collector logs job/xplorr-first-run

A successful run logs how many bytes it collected from OpenCost, then sent to Xplorr. The token is never printed.

In the console, the cluster’s status moves from Waiting for collector to Receiving, and Last data shows when the collector last posted.

The collector dialog lists every token for the cluster, showing its prefix and last four characters, who created it, and when it was last used. You can:

  • Generate token to issue another one, for example to rotate without downtime. Issue the new token, re-run the install command with it (or apply the updated manifest), then revoke the old one.
  • Revoke a token. Any collector still using it stops being able to send cost data immediately. Cost data already collected is kept, and the revoked token stays in the list with its last used timestamp as an audit trail.

Creating and revoking tokens are both recorded in the audit log. Only the display prefix is recorded, never the token.

Use this only when Xplorr can reach your OpenCost endpoint from outside the cluster.

Put an ingress or load balancer in front of the OpenCost API (port 9003 by default) and protect it. OpenCost has no authentication of its own, so an endpoint exposed without protection lets anyone read your cluster cost data.

Protect it with a header your ingress checks, for example a bearer token or a shared secret header.

Open Kubernetes in the console, click Connect cluster, and choose Reachable from Xplorr.

Fill in:

  • Cluster name
  • OpenCost API URL, for example https://opencost.example.com. It must be http or https. Credentials in the URL are rejected; put them in the auth header instead. Cloud instance metadata addresses are refused.
  • Auth header name (optional, defaults to Authorization). Letters, digits and hyphens only.
  • Auth header value (optional, up to 4096 characters). Stored encrypted and never shown again. Xplorr sends it on every call.
  • Linked cloud account (optional)
  • Include in the daily sync: leave checked

Click Test connection before saving. Xplorr calls your endpoint for a one day window and reports how many allocations came back.

Save the cluster, then click Sync now on its row. Xplorr fetches recent days and loads them. After that the cluster refreshes on the daily schedule.

The Test button on the cluster row re-runs the connection check at any time without loading data.

Mode Cadence Window
Push Whatever the CronJob schedule says, hourly by default The last 3 days on every run
Pull A daily job, 03:30 UTC by default The last 3 days, or 30 days on a cluster’s first ever sync

Re-sending a day replaces it rather than adding to it, so overlapping windows are safe.

A collector may heal a gap but not rewrite arbitrary history: the ingest endpoint accepts allocation days within the last 120 days and ignores anything older or dated in the future.

Linking a cluster to the cloud account that pays for its nodes turns on allocation coverage: Xplorr compares the cluster cost OpenCost reported against the billed compute and managed Kubernetes cost of that account over the same period.

Coverage near 100% means the cluster explains its node spend. A low number usually means OpenCost is missing part of the cluster, or that the account pays for a lot besides this cluster.

Linking also decides who sees the cluster. Members and viewers see clusters linked to cloud accounts they have been granted access to. A cluster with no linked account is visible to admins only.

The Kubernetes page follows the account picked in the header, for the selected range (7, 30 or 90 days) and optionally a single cluster. It has five tabs:

  • Overview: cluster cost, idle capacity, a daily chart of allocated workload cost against idle capacity, and What changed, which compares each workload’s cost per day and average pods over the last 7 complete days with the 7 before
  • Workloads: the cost breakdown by Namespace, Controller, Pod, Node pool, Node and Label, showing CPU, RAM, GPU, Storage, Network, Shared and Total; requested against used; and Over provisioned workloads
  • Nodes: nodes and node pools, node efficiency and bin packing, commitment coverage, GPU cost and utilisation, and unused persistent volumes. With the Helm chart 0.3.0 or later, the Nodes table lists the nodes in the cluster now; nodes that ran in the range and have since been replaced or scaled away sit behind Show nodes that left, and their cost stays in the totals
  • Network: network cost per workload where the cluster reports it
  • Clusters: connected clusters, with source, linked account, status and last data

For an over provisioned workload, Get the change shows the right sized requests as a kubectl patch, Helm values and a Kustomize patch, each with a copy button. You apply it in your own cluster or repository; Xplorr only reads.

On the Label tab, pick a label key from the dropdown. Xplorr lists the label keys OpenCost actually reported for workloads in the range, so an empty dropdown means OpenCost sent no pod labels.

Badge Meaning
Receiving Push cluster, a collector has posted data
Waiting for collector Push cluster with a token issued, nothing posted yet
No token issued Push cluster with no active token. Open Collector and generate one.
Synced Pull cluster, last sync succeeded
Sync failed Pull cluster, last sync failed. The error is shown on the page.
Not synced yet Pull cluster that has never synced. Click Sync now.
Stale Push cluster whose collector has missed at least six hourly runs. Check that its CronJob still exists, that its token was not revoked, and that it can reach Xplorr.
Paused The cluster is off. Push clusters reject ingest, pull clusters are skipped by the daily job. Resume it from Edit.
  • Connecting the cluster before installing OpenCost. There is nothing to read. Install OpenCost first and confirm its API answers.
  • Reusing another cluster’s OpenCost values. CLUSTER_ID comes along with the copy and labels the data as the wrong environment. Xplorr still files the cost correctly, but anything read from OpenCost directly is mislabelled. See Check CLUSTER_ID.
  • Picking pull mode for a private cluster. If Xplorr cannot reach the endpoint, every sync fails. Use push mode; it is the default for a reason.
  • Leaving the OpenCost URL pointing at the wrong namespace. The generated manifest assumes OpenCost runs in the opencost namespace. Edit OPENCOST_URL if yours does not.
  • Losing the token and re-applying the old manifest. The token is shown once. Generate a new one, apply the new manifest, revoke the old token.
  • Exposing OpenCost without protection to make pull mode work. OpenCost has no authentication of its own. Always put an auth header in front of it.
  • Expecting a partial day. Xplorr stores whole UTC days. Today’s cost appears once the day is complete and the next run picks it up.

Status stays at “Waiting for collector”

The CronJob has not completed a successful run. Check it:

Terminal window
kubectl -n xplorr-collector get cronjob,job,pod
kubectl -n xplorr-collector logs job/<job-name>

Common causes: the CronJob was never created because the manifest was applied to the wrong cluster or context, egress to Xplorr is blocked, or OPENCOST_URL points somewhere OpenCost is not.

Invalid ingest token

The token in the Secret does not match any token for that cluster. Generate a new token, apply the refreshed manifest, and confirm the Secret really updated:

Terminal window
kubectl -n xplorr-collector get secret xplorr-ingest-token -o jsonpath='{.data.token}' | base64 -d | head -c 14

That prints only the recognisable prefix, which is enough to compare with the prefix shown in the console.

This ingest token has been revoked

Someone revoked it. Generate a new one and re-apply.

This cluster is configured for pull ingest

You applied a collector manifest to a cluster that was created in pull mode. Ingest mode cannot be changed after creation, so delete the cluster and add it again as a private cluster.

Payload too large or Too many allocation rows

The window is too wide for one request. The ingest endpoint caps the body size, the number of allocation sets per request and the number of rows. Reduce COST_WINDOW in the CronJob, for example from 3d to 1d, and let the hourly schedule keep the data current.

Too many ingest requests for this cluster

The collector is posting faster than the per cluster rate limit allows. An hourly schedule is far below it; a schedule of every minute is not.

OpenCost API not found

The URL does not serve the OpenCost allocation API. Xplorr tries /allocation and falls back to /allocation/compute for older releases. Give the base URL of the API, not a path below it.

OpenCost rejected the credentials

The auth header name or value is wrong for your ingress. Re-enter the value in the cluster dialog; a stored value is never shown again, so leaving it blank keeps the old one.

This address is not allowed

The URL points at a cloud instance metadata address. Those are refused deliberately. Use the real OpenCost endpoint.

Cluster cost looks far lower than the cloud bill

Check allocation coverage. OpenCost prices the nodes it can see, so a cluster spanning node groups OpenCost is not configured for, or an account paying for much more than this cluster, both show up as low coverage.

  • Cluster added in Xplorr with the right ingest mode
  • Push mode: token generated and the install command run
  • Push mode: a collector run completed and the status shows Receiving
  • Pull mode: OpenCost installed, exposed, protected, and its CLUSTER_ID checked
  • Pull mode: connection test passed and the first sync ran
  • OpenCost given your cloud pricing details, if the cluster runs on reservations, savings plans or spot
  • Cloud account linked, if you want allocation coverage
  • Namespace costs visible on the Kubernetes page

Does Xplorr need access to my Kubernetes API? No. In push mode the collector reads only the OpenCost HTTP API and mounts no ServiceAccount token. In pull mode Xplorr calls the OpenCost endpoint you give it. Neither path uses cluster credentials.

Do I have to open a port for push mode? No. The collector makes an outbound HTTPS request. Nothing in your cluster needs to be reachable from the internet.

Can one token write to several clusters? No. A token is scoped to one cluster in one organization. A token for cluster A cannot write cluster B.

Can I run the collector on a different schedule? Yes. Edit the schedule field in the CronJob. Each run re-sends a rolling window, so a slower schedule still produces complete days, just later.

Does Xplorr support clusters outside AWS, Azure and GCP? Yes for push mode. The collector only needs OpenCost and outbound HTTPS, so on premises and other hosted clusters work. Allocation coverage needs a linked cloud account, so it stays empty for a cluster with no cloud bill behind it.

Who can connect or delete a cluster? A member or an admin can connect one. Changing a cluster afterwards, including generating and revoking its ingest tokens, is for whoever owns it: an organization admin, the person who connected it, or an admin of the cloud account it is linked to. Deleting a cluster takes its cost history with it, so that stays with an organization admin. Viewers can read cost data for clusters linked to cloud accounts they have access to, and change nothing.

What happens to cost history if I delete a cluster? It is removed with the cluster. Export what you need first from Reports and Export.