Setup & security guide · Kubernetes

The read-only Kubernetes agent

One small pod per cluster that reads what your workloads ask for and what they use, once a minute, and sends FinOpsAI one row per workload once an hour. No inbound ports, no writes, no secrets read, no labels, no images, no logs. This page is for the platform engineer who installs it and the security reviewer who approves it.

Time: about 5 minutes per cluster
Who: cluster admin (Helm) + a FinOpsAI Owner or Admin (token)
First data: posture within the first hour; usage-based findings after 3 days
Updated: October 25, 2026 · agent 0.3.3
On this page
Why an agent at allWhat it reads — and never readsRBACInstallVerifySecurity review answersUpgrade and removeFAQ

00Why an agent at all

Everything else FinOpsAI knows about Kubernetes comes from outside the cluster: the bill, the control plane and the cloud's monitoring. Those see clusters and node pools. They do not see that one Deployment asks for 2 cores and uses 0.07, or that a namespace has no LimitRange, or that a pod has no requests at all — and those are the facts that decide whether a node pool can ever shrink. The agent exists only to read those facts, in the least-privileged way a cluster allows, and it is optional: every FinOpsAI Kubernetes feature that can work without it does.

Without the agentCluster and pool costs, pool utilisation, control-plane fees, idle clusters, spot and Arm candidates, commitment coverage, namespace cost (where the cloud exports it), GKE's own rightsizing recommendations.
With the agentPer-workload requests vs usage (K-32), containers with no requests (K-34), fixed replicas without an HPA (K-35), namespaces without guardrails (K-36), finished pods and TTL-less Jobs (K-37), containers without a memory limit (K-38), CPU-throttled workloads (K-39), PodDisruptionBudgets that block node drain (K-40).

01What it reads — and never reads

Reads (Kubernetes API, list / get only)pods (namespace, owner, phase, resources.requests / limits per container), replicasets and jobs (owner chain only), nodes (allocatable), metrics.k8s.io pod usage, horizontalpodautoscalers (scaleTargetRef, min / max), limitranges and resourcequotas (presence per namespace), namespaces (names), poddisruptionbudgets (selector, minAvailable / maxUnavailable), and each node's kubelet /metrics/cadvisor through the API-server proxy for two counters: container_cpu_cfs_periods_total and container_cpu_cfs_throttled_periods_total.
Sends to FinOpsAI, once an hourPer workload: namespace, kind, name, replicas, CPU / memory requested and used (p95 and mean), and posture as counts and booleans — container count, containers without requests, containers without a memory limit, summed limits, HPA present + min / max, PDB present + whether it blocks a drain, throttled-period ratio. Per namespace: LimitRange present, ResourceQuota present, finished-pod count, TTL-less-Job count, workload count. Cluster: node count and allocatable totals.
Never readsSecrets, ConfigMaps, environment variables, container images, logs, exec, service accounts' tokens other than its own, Ingress / Service definitions, custom resources.
Never sendsLabel or annotation values (the PDB match uses pod labels in memory and discards them), node names, pod IPs, HPA / PDB / LimitRange object names, image names, anything from the cAdvisor text other than the two counters above.
Data class in FinOpsAIk8s_workload_names — namespace and workload names are the only customer-chosen text that leaves the cluster. Issuing the token is an attested, audit-logged consent to exactly that; revoking the token deletes the data FinOpsAI holds for the account.

The unit tests assert this contract: a payload built from a pod carrying labels, a secret-named PDB and an image reference is checked to contain none of them. agent/finopsai-k8s-agent/agent.test.mjs in the FinOpsAI repository; the test runs in CI before every release.

02RBAC — the whole ClusterRole

The chart creates one ServiceAccount, one ClusterRole and one ClusterRoleBinding. No verb other than get and list; no watch, no create, no patch, no delete, no exec.

apiGroupresourcesverbssince
""pods, nodes, namespaces, limitranges, resourcequotasget, list0.1.0 / 0.2.0
appsreplicasetsget, list0.1.0
batchjobsget, list0.1.0
metrics.k8s.iopodsget, list0.1.0
autoscalinghorizontalpodautoscalersget, list0.2.0
policypoddisruptionbudgetsget, list0.3.0
""nodes/proxyget0.3.0 — kubelet /metrics/cadvisor only; the agent issues no other proxy path

Every posture read is optional. Remove a rule from the ClusterRole and the agent logs once that the posture from it is not sent, keeps running, and FinOpsAI shows that source as "not read" rather than inventing a zero.

Pod security: runAsNonRoot, uid 65532, read-only root filesystem, all capabilities dropped, seccompProfile: RuntimeDefault, no hostNetwork, no ports, no volumes other than the projected service-account token. Requests 20m CPU / 64Mi; limits 200m / 192Mi.

03Install

Who does what. A FinOpsAI Owner or Admin issues the token in the app by clicks. The install itself is done once per cluster by the platform engineer who already runs it (cluster-admin rights and Helm) — the same person who installs any other cluster add-on. A workspace that holds only Kubernetes Cost Intelligence connects only the billing exports that bill its clusters (the GCP billing account, the AWS payer or account, the Azure billing scope) — no other cloud account is needed.

  1. FinOpsAI → Kubernetes → Workloads → the cloud account's card → Issue agent token An Owner or Admin reads the attestation (what the agent reads, the data class) and confirms. The token is shown once; it identifies the workspace and cloud account — the agent never names a tenant. Each cluster can use the same token or its own.
  2. A terminal with kubectl context on the cluster and Helm ≥ 3.8 Install from the public chart (no login, no repository to add):
    helm upgrade --install finopsai-agent \
      oci://asia-south1-docker.pkg.dev/samsoft-finopsai-prod/finopsai-agent/charts/finopsai-k8s-agent --version 0.3.3 \
      -n finopsai-agent --create-namespace \
      --set clusterName=<CLUSTER_NAME_AS_ON_THE_BILL> --set token=<TOKEN>
    clusterName must be the cluster's name as it appears on your cloud bill (the GKE / EKS / AKS cluster name), so workloads join to cost.
  3. Optional values --set api=https://api.finopsai.app (default) · --set windowMinutes=60 (5–180; the report period) · --set image.mode=configmap to run the same script from a ConfigMap on node:22-alpine if your clusters only pull from a mirror · nodeSelector, tolerations, resources as usual.

Supply chain. The image is a distroless Node.js build (gcr.io/distroless/nodejs22-debian12:nonroot) containing one file. Chart and image are published from FinOpsAI's CI to a public Artifact Registry repository; the chart's appVersion pins the image tag. Pin further with --set image.tag=<digest-tagged version> if your policy requires it.

04Verify

Podkubectl -n finopsai-agent get pods → one pod Running. Logs: kubectl -n finopsai-agent logs deploy/finopsai-agent → starting · cluster … · window 60 min, within a minute initial report sent (0.3.2 — the card appears at once), then after each 60-minute window sent N workload(s) · usage read.
In FinOpsAIKubernetes → Workloads: the card reads reporting with the last report time; Coverage & sources shows in-cluster agent: read and agent ≥ 0.3.0 (throttling · PDB): read. The rule pass starts within minutes of the first report; the Overview's engine board shows the workload and posture checks as fired, clear or pending.
If the card still says "issued, not seen"The agent could not reach api.finopsai.app (egress policy) or the token was not pasted whole. The pod log says which: token rejected vs a connection error. A token is 49 characters and starts with fka_; re-run the helm upgrade --install line with the token copied again — the Secret change rolls the pod on its own.
If the log says metrics.k8s.io unavailable (503) — sending requests onlymetrics-server is installed but not serving. On EKS this happens when the upstream components.yaml and the EKS metrics-server add-on were both installed (the add-on then shows CREATE_FAILED): remove the add-on, kubectl delete -f …/components.yaml, and create the add-on again. kubectl top nodes working is the check; the agent picks metrics up on its next sample without a restart.
If posture reads "not read"The ClusterRole was edited, or a policy engine blocked the proxy path. The pod log names the path it could not read.

05Security review answers

Direction of trafficOutbound only: HTTPS POST to api.finopsai.app once per window, bearer token in the Authorization header. The agent opens no listener.
CredentialA FinOpsAI-issued token, random, stored as a Kubernetes Secret by the chart and mounted as an environment variable. FinOpsAI stores only a hash. Revoke from the Workloads page at any time; a rotated token restarts the pod automatically (chart ≥ 0.2.1).
Cluster credentialsIts own projected service-account token, scoped by the ClusterRole above. No kubeconfig, no cloud credentials, no access to other namespaces' Secrets.
Data residencyRows are stored in FinOpsAI's Google Cloud project in asia-south1 (Mumbai), under your workspace, for 7 days of hourly samples per workload (older samples roll off).
Blast radius if the token leaksA holder could send fabricated workload rows for your account; FinOpsAI bounds every payload (2,000 workloads, DNS-label names, counts capped) and rate-limits by token. It cannot read anything.
Blast radius if the pod is compromisedThe ClusterRole: list / get on the resources above. No write, no Secrets, no exec. Egress to one host.
SourceOne file, no dependencies: agent/finopsai-k8s-agent/index.mjs (~220 lines) with unit tests. Available to customers under NDA for review.

06Upgrade and remove

Upgrade: the same helm upgrade --install with the new --version; values are kept with --reuse-values. Section 14 shows the version each cluster reports and says when a rule needs a newer agent.

Remove: helm uninstall finopsai-agent -n finopsai-agent, then Revoke the token on the Workloads page. Revoking deletes the workload rows FinOpsAI holds for that account; the audit log records both.

07FAQ

Does it work on EKS and AKS?

Yes — it uses only upstream APIs (metrics-server, autoscaling/v2, policy/v1, the kubelet's cAdvisor endpoint). metrics-server is installed by default on GKE and AKS; on EKS enable it once as the EKS add-on (aws eks create-addon --addon-name metrics-server, or tick it when creating the cluster) — use either the add-on or the upstream manifest, not both. Live-verified on GKE, EKS and AKS (October 2026). Without it the agent sends requests only and FinOpsAI shows usage as metrics-server not reachable.

Why not OpenCost or Prometheus?

Both are good; both need a Prometheus and a cost model. The agent needs neither — it reads requests and usage directly and FinOpsAI prices them from your bill, so the numbers reconcile with the invoice. If you already run OpenCost, keep it; the agent adds posture (HPA, PDB, guardrails, throttling) that OpenCost does not model.

Can it run in a cluster with no internet egress?

It needs HTTPS to api.finopsai.app (or a proxy that forwards to it: set HTTPS_PROXY through extraEnv). Images: use image.mode=configmap with your mirror's node:22-alpine.

Who to contact

finops@samsofttechnologies.com — include the cluster name, the agent version from the pod log, and the exact message FinOpsAI showed.