Skip to content

docs: reorder k8s-reporter Karpenter guidance to lead with pinning #299

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlexKantor87 merged 1 commit into from
Jul 1, 2026
Merged

docs: reorder k8s-reporter Karpenter guidance to lead with pinning #299

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions helm/k8s_reporter.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: A Helm chart for installing the Kosli K8S reporter as a cronjob.
# k8s-reporter

<Info>
This reference applies to **chart version 2.3.0**, which defaults to CLI **v2.12.0** via `appVersion`. Override with `image.tag`.
This reference applies to **chart version 2.3.1**, which defaults to CLI **v2.12.0** via `appVersion`. Override with `image.tag`.
</Info>

A Helm chart for installing the Kosli K8S reporter as a CronJob.
Expand Down Expand Up @@ -165,17 +165,9 @@ By default the reporter runs as a CronJob every 5 minutes. On clusters that use

The cause is Karpenter's `consolidateAfter` timer: Karpenter only consolidates a node once it has seen no pod scheduling activity on it for the configured window. A reporter pod arriving every 5 minutes keeps resetting that timer, so any node whose `consolidateAfter` is longer than the reporter interval never becomes eligible for consolidation (see [karpenter#1921](https://github.com/kubernetes-sigs/karpenter/issues/1921)). This is Karpenter working as designed, not a reporter bug.

There are three good ways to avoid it, in order of preference.
Frequent snapshots are what let Kosli surface drift or an unauthorized change quickly, so the best fix keeps the 5-minute cadence and moves the reporter out of Karpenter's way. Widening the interval trades away that detection speed and should be a last resort.

### 1. Widen the report interval

The simplest fix. Set `cronSchedule` longer than your NodePool's `consolidateAfter` so nodes get quiet windows long enough to consolidate. Environment snapshots rarely need 5-minute freshness.

```yaml
cronSchedule: "*/15 * * * *"
```

### 2. Pin the reporter to a stable node group
### 1. Pin the reporter to a stable node group (recommended)

If you run a stable managed node group that Karpenter does not manage, schedule the reporter there so it never disturbs Karpenter-managed nodes. Use `nodeSelector`, and `tolerations` if that node group is tainted:

Expand All @@ -202,9 +194,17 @@ affinity:
operator: DoesNotExist
```

### 3. Run the reporter out of the cluster
### 2. Run the reporter out of the cluster

For zero footprint on cluster nodes, run `kosli snapshot k8s` on a schedule outside the cluster (for example a CI cron job) with kubeconfig access. See the [Kubernetes environment reporting tutorial](/tutorials/report_k8s_envs).
For zero footprint on cluster nodes, run `kosli snapshot k8s` on a schedule outside the cluster (for example a CI cron job) with kubeconfig access, keeping your reporting cadence without placing a pod on the cluster's nodes. See the [Kubernetes environment reporting tutorial](/tutorials/report_k8s_envs).

### 3. Widen the report interval (last resort)

Only if you cannot pin the reporter or move it out of cluster: set `cronSchedule` longer than your NodePool's `consolidateAfter` so nodes get quiet windows long enough to consolidate. This works, but a longer interval widens the window in which a change can go unreported, so prefer the options above.

```yaml
cronSchedule: "*/15 * * * *"
```

<Warning>
`karpenter.sh/do-not-disrupt: "true"` is **not** a fix here. It prevents Karpenter from disrupting the pod, which protects a mid-run report from interruption but makes consolidation of that node *less* likely, not more. Likewise `cluster-autoscaler.kubernetes.io/safe-to-evict` only affects the Kubernetes Cluster Autoscaler and is ignored by Karpenter.
Expand Down