Install the Finout EKS Kubernetes Agent

This guide walks you through installing the Finout EKS Kubernetes Agent on your clusters. The agent collects workload metrics from your clusters and exports them to Finout for Kubernetes cost allocation.

Availability: Generally available for EKS.

For an overview of what the agent does and how it works, see Finout Kubernetes Agent overview.

Overview

The EKS Kubernetes Agent installation involves three steps:

1. Generate an API token – Create a dedicated authentication token for the agent in the Finout app.

2. Deploy via Helm – Paste your token credentials into the provided Helm command and run it against your EKS cluster.

3. Notify Finout Support – Let the Finout Support team know the agent is deployed and specify which AWS Cost Centers you'd like to enrich with Kubernetes cost allocation data.

Prerequisites

Before you begin, confirm the following:

• Finout account with Kubernetes EKS Agent role enabled: Contact your Finout Customer Success manager to have the EKS Kubernetes Agent role enabled on your account.

• Helm 3.8 or later: Required for OCI-based chart pulls (oci://).

• StorageClass: The agent buffers metric files on a 10 GiB PersistentVolume. A default StorageClass must be available, or you must provide one via --set centralCollector.persistence.storageClassName=<name>.

• Outbound HTTPS access: The agent uploads metrics over HTTPS. Ensure your cluster nodes can reach app.finout.io on port 443 and AWS S3 endpoints.

Step 1 - Generate an API token

1. In the Finout app, click your username in the top-right corner and select Admin Portal.

   
2. Navigate to API Tokens.

   

3. Click Generate Token.

4. Fill in the token details:

   • Description

   • Role: Select Finout K8s Agent.

   • Expiration: Set to Never expire.

     

5. Click Generate.

6. Copy both credentials and store them somewhere safe:

   • Client ID

   • Secret Key

The Secret Key is shown only once. If you leave this screen without copying it, you'll need to generate a new token.

Step 2 - Deploy the Kubernetes Agent via Helm

In the following command, replace FINOUT_CLIENT_ID and FINOUT_SECRET_KEY with the credentials generated in Step 1, and set <NAME_OF_YOUR_CLUSTER> to the name of the cluster you want to deploy the agent on:

helm upgrade --install finout-agent \
  oci://public.ecr.aws/finout/charts/finout-k8s-agent:0.8.2 \
  --namespace finout-agent \
  --create-namespace \
  --set centralCollector.uploader.auth.clientId="FINOUT_CLIENT_ID" \
  --set centralCollector.uploader.auth.secretKey="FINOUT_SECRET_KEY" \
  --set centralCollector.uploader.clusterId="<NAME_OF_YOUR_CLUSTER>"

Recommended: Set a priorityClass to ensure the agent is scheduled and remains running, even under node resource pressure, avoiding gaps in metric collection. See Advanced Configurations below.

Resource Sizing

The agent's resource needs scale with your cluster: kube-state-metrics and the central collector grow with pod count and label density, and the node collector with pods per node.

The chart ships with defaults that fit most clusters — deliberately not all of them, so small clusters don't reserve resources they'll never use.

Start from the tier recommendations below, then monitor the agent's components and adjust when they approach their limits.

Default configuration:

Component	Kind	Scope	CPU req / lim	Memory req / lim
Node Collector	DaemonSet	Per node	100m / 500m	350Mi / 700Mi
Central Collector	Deployment (1 replica)	Cluster	400m / 1000m	2Gi / 4Gi
kube-state-metrics	Deployment (1 replica)	Cluster	300m / 600m	2Gi / 4Gi

Recommended configuration:

Cluster Tier	Pods	Nodes	KSM CPU req / lim	KSM Memory req / lim	Central Collector CPU req / lim	Central Collector Memory req / lim
Small	< 2,000	< 50	150m / 1000m	512Mi / 2Gi	150m / 500m	512Mi / 2Gi
Medium	2,000 – 10,000	50 – 250	250m / 1000m	1Gi / 3Gi	250m / 500m	1Gi / 3Gi
Large	10,000 – 25,000	250 – 800	300m / 1000m	2Gi / 4Gi	300m / 600m	2Gi / 4Gi
Extra Large	> 25,000	> 800	500m / 1000m	3Gi / 6Gi	500m / 1000m	3Gi / 6Gi

Once the command completes successfully, the agent begins scraping metrics from your cluster and uploading them to Finout.

Advanced Configurations (Optional)

Schedule the agent reliably with a PriorityClass (Recommended)

On small or heavily-loaded clusters, the collector pods may fail to schedule when nodes don't have enough free CPU or memory. Giving them a higher scheduling priority lets Kubernetes preempt lower-priority pods to make room, so the agent schedules reliably. The Helm chart can create a (cluster-scoped) PriorityClass for you.

How to configure:

Add the following to your Helm command: --set priorityClass.create=true

Both the node collector and the central collector will automatically use the created PriorityClass.

The priority defaults to 1000000 - above ordinary application pods, but below Kubernetes' system-critical classes, so cluster-critical pods are never preempted.

To use a different value: --set priorityClass.create=true --set priorityClass.value=500000000

Note: creating a PriorityClass is a cluster-scoped operation, so the identity running Helm must have permission to create PriorityClasses.

Use an existing PriorityClass

If your cluster already defines a PriorityClass you'd like the agent to use, reference it directly instead of having the chart create one.

--set nodeCollector.priorityClassName=<your-priority-class> --set centralCollector.priorityClassName=<your-priority-class>

A priorityClassName set this way always takes precedence over the chart-created class.

Override the agent's default resource requests

You can override the chart's default for every agent's component.

For recommended values by cluster size, see the tier table in the Resource Footprint

How to configure:

To update the resources, extend the helm command with the following --set flags (or put the equivalent keys in your values file), and set the values that match your cluster tier: --set kube-state-metrics.resources.requests.cpu=300m \ --set kube-state-metrics.resources.requests.memory=2Gi \ --set kube-state-metrics.resources.limits.cpu=600m \ --set kube-state-metrics.resources.limits.memory=4Gi \ --set centralCollector.resources.requests.cpu=400m \ --set centralCollector.resources.requests.memory=2Gi \ --set centralCollector.resources.limits.cpu=1000m \ --set centralCollector.resources.limits.memory=4Gi \ --set nodeCollector.resources.requests.cpu=100m \ --set nodeCollector.resources.requests.memory=350Mi \ --set nodeCollector.resources.limits.cpu=500m \ --set nodeCollector.resources.limits.memory=700Mi

Increase the metrics buffer volume

The central collector buffers rotated metric files on a 10 GiB PersistentVolume before uploading them to Finout. On large clusters, or when uploads stall for an extended period, this buffer can fill up. Increase the volume size to give the collector more headroom.

How to configure:

Add the following to your Helm command, replacing <SIZE> with the size in GiB:

--set centralCollector.persistence.size=<SIZE>Gi

Example: --set centralCollector.persistence.size=20Gi

Use an existing Kubernetes secret for credentials

By default, the Helm chart creates a Kubernetes Secret using the clientId and secretKey values you provide. If your organization manages secrets and deployments externally, you can skip secret creation and reference an existing secret instead.

How to configure?

1. Add the following to your Helm command: --set centralCollector.uploader.auth.createSecret=false --set centralCollector.uploader.auth.existingSecretName=

2. When using this option, omit the credential flags from your base command: --set centralCollector.uploader.auth.clientId=$CLIENT_ID --set centralCollector.uploader.auth.secretKey=$SECRET_KEY

Your existing secret must contain the clientId and secretKey keys and be present in the same namespace as the agent before installation.

Central Collector Deployment Scheduling Configuration

To schedule the central collector pod on specific nodes, use centralCollector.nodeSelector. Example: --set centralCollector.nodeSelector.workload-type=monitoring

Set affinity on the central collector

To control pod placement using affinity rules, pass a JSON affinity object with --set-json.

Example: --set-json 'centralCollector.affinity={"nodeAffinity":{"requiredDuringSchedulingIgnoredDuringExecution":{"nodeSelectorTerms":[{"matchExpressions":[{"key":"topology.kubernetes.io/zone","operator":"In","values":["us-east-1a"]}]}]}}}'

Set tolerations on the central collector

To allow the central collector pod to be scheduled on tainted nodes, pass a JSON tolerations array with --set-json.

Example: --set-json 'centralCollector.tolerations=[{"key":"dedicated","operator":"Equal","value":"monitoring","effect":"NoSchedule"}]'

Prefer to review manifests before applying?

Use helm template to render the manifests locally first:

helm template finout-agent \
  oci://public.ecr.aws/finout/charts/finout-k8s-agent:0.8.2 \
  --no-hooks \
  --namespace finout-agent \
  --create-namespace \
  --set centralCollector.uploader.auth.clientId="FINOUT_CLIENT_ID" \
  --set centralCollector.uploader.auth.secretKey="FINOUT_SECRET_KEY" \
  --set centralCollector.uploader.clusterId="<NAME_OF_YOUR_CLUSTER>" \
  > finout-agent-manifests.yaml

Once reviewed, you can deploy the agent using standard Kubernetes tooling:

kubectl create namespace finout-agent
kubectl apply -f finout-agent-manifests.yaml

Uninstall The Kubernetes EKS Agent

If installed via Helm:

helm uninstall finout-agent --namespace finout-agent
kubectl delete namespace finout-agent

If installed via kubectl apply:

kubectl delete namespace finout-agent

Step 3 - Notify Finout Support

Let the Finout Support team know the agent is deployed and specify which AWS and/or GCP Cost Centers you'd like to enrich with Kubernetes cost allocation data.

If you are already enriching an AWS or GCP Cost Center using Kubernetes data from Prometheus or Datadog, you cannot enrich the same Cost Center using the Kubernetes Agent without migrating away from your existing method first.

Kubernetes Data Availability

Kubernetes cost and usage data will appear across Finout within 48 hours, matching the standard AWS billing data delivery window.

Health Metrics Availability

Once deployed, the Finout Kubernetes agent exposes Prometheus health metrics that let you confirm, from inside your cluster, that metrics are leaving it and reaching Finout.

Exposed Metrics

Metric	Type	Description
finout_uploader_oldest_pending_file_age_seconds	Gauge	The age of the oldest file still waiting to be uploaded. Stays low (seconds–minutes) while data flows. Climbs steadily the moment uploads stall. Absent when nothing is pending.
finout_uploader_files_pending	Gauge	Number of rotated metric files on the disk waiting to be uploaded.
finout_uploader_files_uploaded	Counter	Number of files successfully uploaded to Finout since the process started.
finout_uploader_upload_failures	Counter	Number of failed upload attempts since the process started. Counts attempts, not distinct files — a file that keeps failing increments this on every retry.
finout_uploader_disk_used_bytes	Gauge	Used bytes on the metrics data volume. Absent if the volume can't be read.
finout_uploader_disk_free_bytes	Gauge	Free bytes on the metrics data volume.
finout_uploader_disk_total_bytes	Gauge	Total writable bytes on the metrics data volume.

How To Access

The central-collector Service serves the metrics in Prometheus text format at /metrics on port 8889.

The central-collector Service ships with prometheus.io/scrape annotations on port 8889 (on by default), So, an annotation-based Prometheus in your cluster automatically discovers the endpoint. No operator required.

To check the endpoint manually:

1. Port-forward the Service:

   kubectl -n finout-agent port-forward svc/finout-agent-central-collector 8889:8889

2. Scrape the endpoint:

   curl localhost:8889/metrics

Configuration

Health metrics are enabled by default, controlled under centralCollector.uploader.healthMetrics in values.yaml:

centralCollector:
  uploader:
    healthMetrics:
      enabled: true
      port: 8889

      # Annotation-based discovery (default). Works without the Prometheus Operator.
      annotations:
        enabled: true

      # Prometheus Operator ServiceMonitor. Requires the ServiceMonitor CRD.
      serviceMonitor:
        enabled: false
        additionalLabels: {}   # Must match your Prometheus's serviceMonitorSelector,
                                # or the ServiceMonitor is silently ignored.
                                # kube-prometheus-stack defaults to `release: <prometheus-release-name>`.
        interval: 30s
        scrapeTimeout: 10s

If ServiceMonitor is your only scrape path, set annotations.enabled to false to avoid duplicate scrapes of the same endpoint.

You can also set these values with --set flags on your Helm command, the same way as the other options above.

For more information, please see the FAQs article.