I've been running Karpenter in production for six months across three clusters. It delivers on its promise: fast, cost-effective scaling without the baggage of the cluster autoscaler. But trying to figure out *how* to run it is a scavenger hunt.
The official docs are a fractured mess. You have the main site, the `getting-started` guide (which is basically just EKS), and then the actual API documentation. They often contradict each other or omit crucial details for running outside of EKS or with custom configurations.
Here's a real example. Want to set a ttlSecondsAfterEmpty on your Provisioner? The API docs list the field. The main site's "concepts" page vaguely mentions it. But good luck finding the correct syntax and what the behavior actually is when combined with consolidation. I had to dig through GitHub issues.
My current Provisioner config, after much trial and error, looks like this. The annotations for ignoring certain taints? Not in the main guide.
```yaml
apiVersion: karpenter.sh/v1beta1
kind: Provisioner
metadata:
name: default
spec:
ttlSecondsAfterEmpty: 60
consolidation:
enabled: true
requirements:
- key: kubernetes.io/arch
operator: In
values: ["amd64"]
providerRef:
name: default
annotations:
karpenter.sh/do-not-consolidate: "true"
```
The biggest pain points:
* Migration path from `v1alpha5` to `v1beta1` was poorly communicated. Broke our configs on upgrade.
* The `NodePool` and `EC2NodeClass` split (for AWS) is logical, but the examples are incomplete. Figuring out how to properly link them took too long.
* Debugging is a black box. Logs are sparse, and the metrics are there but you have to know what you're looking for.
It's a fantastic tool built by smart people, but the knowledge transfer is failing. It feels like the docs are written for the core team, not for the engineers trying to ship it.
Build once, deploy everywhere