Merge pull request #37 from paperclipinc/feat/crd-v1-and-k3s

feat!: graduate HCloudNodeClass CRD to v1; add k3s bootstrap support

Author: stubbi

CONTRIBUTING.md

@@ -22,7 +22,7 @@ CI runs `make test`, `golangci-lint`, `make generate-verify` (fails if generated
 
 ## Code generation
 
-The `HCloudNodeClass` CRD and `zz_generated.deepcopy.go` are generated from the API types in `pkg/apis/v1alpha1` by `controller-gen`. If you change those types, run `make generate` and commit the regenerated files. CI will fail if they are out of date.
+The `HCloudNodeClass` CRD and `zz_generated.deepcopy.go` are generated from the API types in `pkg/apis/v1` by `controller-gen`. If you change those types, run `make generate` and commit the regenerated files. CI will fail if they are out of date.
 
 ## Testing conventions
 

README.md

@@ -74,7 +74,7 @@ The CRD ships in the chart's `crds/` directory and is installed automatically by
 Create an `HCloudNodeClass` describing how nodes are built, and a `NodePool` describing what Karpenter may provision:
 
 ```yaml
-apiVersion: karpenter.hetzner.cloud/v1alpha1
+apiVersion: karpenter.hetzner.cloud/v1
 kind: HCloudNodeClass
 metadata:
   name: default
@@ -156,12 +156,14 @@ comments explaining every field.
 |------|-------------|
 | [`examples/talos-nodeclass.yaml`](examples/talos-nodeclass.yaml) | Talos Linux, private-network cluster, image pinned via label selector, machineconfig from a Secret |
 | [`examples/ubuntu-nodeclass.yaml`](examples/ubuntu-nodeclass.yaml) | Ubuntu 24.04, kubeadm join via inline cloud-init `userData` |
+| [`examples/k3s-nodeclass.yaml`](examples/k3s-nodeclass.yaml) | k3s agent join via cloud-init on an Ubuntu image (for k3s-based clusters) |
 | [`examples/nodepool-multiarch.yaml`](examples/nodepool-multiarch.yaml) | Multi-arch pattern: one NodeClass, two NodePools (amd64 CCX + arm64 CAX) |
 
 ### Bootstrap guides
 
 - [Talos bootstrap guide](docs/talos-bootstrap.md) — obtaining the worker machineconfig, pinning images, and verifying node join.
 - [Ubuntu bootstrap recipe](docs/ubuntu-bootstrap.md) — kubeadm join via cloud-init, keeping tokens out of git, trade-offs vs Talos.
+- [k3s bootstrap recipe](docs/k3s-bootstrap.md) — k3s agent join via cloud-init, using the hcloud CCM for providerID; the natural path for k3s installers (hetzner-k3s, kube-hetzner).
 
 ## Configuration
 

charts/karpenter-provider-hetzner/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: karpenter-provider-hetzner
 description: Karpenter cloud provider for Hetzner Cloud
 type: application
-version: 1.0.0
-appVersion: "1.0.0"
+version: 2.0.0
+appVersion: "2.0.0"
 # home points at Paperclip.inc (the project's canonical page) so listing
 # "Homepage" links drive backlinks to the domain; GitHub stays as source.
 home: https://paperclip.inc/karpenter-hetzner
@@ -26,4 +26,12 @@ annotations:
       url: https://github.com/paperclipinc/karpenter-provider-hetzner
     - name: Talos bootstrap guide
       url: https://github.com/paperclipinc/karpenter-provider-hetzner/blob/main/docs/talos-bootstrap.md
+    - name: k3s bootstrap guide
+      url: https://github.com/paperclipinc/karpenter-provider-hetzner/blob/main/docs/k3s-bootstrap.md
   artifacthub.io/category: integration-delivery
+  artifacthub.io/containsSecurityUpdates: "false"
+  artifacthub.io/changes: |
+    - kind: changed
+      description: "BREAKING: HCloudNodeClass graduated from karpenter.hetzner.cloud/v1alpha1 to /v1; re-apply node classes (no conversion webhook)"
+    - kind: added
+      description: "k3s agent bootstrap example and guide (examples/k3s-nodeclass.yaml, docs/k3s-bootstrap.md)"

charts/karpenter-provider-hetzner/README.md

@@ -15,6 +15,23 @@ helm install karpenter-provider-hetzner ./charts/karpenter-provider-hetzner \
 
 `clusterName` is required; the controller fails to start without it.
 
+## Upgrading to 2.0.0 (CRD `v1`)
+
+Chart 2.0.0 graduates the `HCloudNodeClass` CRD from
+`karpenter.hetzner.cloud/v1alpha1` to the stable `/v1`. There is **no
+conversion webhook**, so this is a breaking change:
+
+```bash
+helm upgrade karpenter-provider-hetzner ./charts/karpenter-provider-hetzner -n kube-system
+# Helm does not upgrade CRDs in crds/ on its own — apply the new CRD, then
+# re-apply your node classes with apiVersion: karpenter.hetzner.cloud/v1:
+kubectl apply -f charts/karpenter-provider-hetzner/crds/
+kubectl apply -f your-nodeclasses-v1.yaml
+```
+
+Existing `v1alpha1` objects are not migrated automatically; recreate them under
+`v1` (the spec is unchanged — only the `apiVersion` differs).
+
 ## Values
 
 | Key | Default | Description |

charts/karpenter-provider-hetzner/crds/karpenter.hetzner.cloud_hcloudnodeclasses.yaml

@@ -22,7 +22,7 @@ spec:
     - jsonPath: .status.conditions[?(@.type=='Ready')].status
       name: Ready
       type: string
-    name: v1alpha1
+    name: v1
     schema:
       openAPIV3Schema:
         properties:

cmd/controller/main.go

@@ -11,8 +11,8 @@ import (
 	"sigs.k8s.io/karpenter/pkg/controllers/state"
 	"sigs.k8s.io/karpenter/pkg/operator"
 
-	// Register our v1alpha1 types.
-	_ "github.com/paperclipinc/karpenter-provider-hetzner/pkg/apis/v1alpha1"
+	// Register our HCloudNodeClass v1 types.
+	_ "github.com/paperclipinc/karpenter-provider-hetzner/pkg/apis/v1"
 
 	hetznercp "github.com/paperclipinc/karpenter-provider-hetzner/pkg/cloudprovider"
 	"github.com/paperclipinc/karpenter-provider-hetzner/pkg/controllers/nodeclass"

docs/integrations/README.md

@@ -0,0 +1,45 @@
+# Integrating karpenter-provider-hetzner with Hetzner installers
+
+Guidance and ready-to-use drafts for offering Karpenter autoscaling on top of
+the popular Hetzner Kubernetes installers.
+
+## Strategy
+
+All three target installers **already ship the Cluster Autoscaler**, so
+Karpenter is an *alternative* (per-pod instance-type selection + consolidation),
+not a missing feature. Two consequences shape every integration here:
+
+1. **Opt-in only.** Default-off; never replace the existing autoscaler. Guard
+   against running both at once.
+2. **Discussion before PR.** All three projects ask for it, none has a prior
+   Karpenter thread, and the provider is young — lead by gauging appetite and
+   disclosing the maintainer affiliation.
+
+## Targets
+
+| Installer | Distro | Fit | Status of draft here |
+|--|--|--|--|
+| [hcloud-k8s/terraform-hcloud-kubernetes](https://github.com/hcloud-k8s/terraform-hcloud-kubernetes) | Talos | **Best** — provider has Talos bootstrap; module already does worker machineconfig + inline manifests | `karpenter.tf` proposal + wiring guide |
+| [vitobotta/hetzner-k3s](https://github.com/vitobotta/hetzner-k3s) | k3s / Ubuntu | **Medium** — CLI-driven; k3s userData now documented; addresses a real CA limitation | discussion post + k3s example/guide in repo |
+| [kube-hetzner](https://github.com/kube-hetzner/terraform-hcloud-kube-hetzner) | k3s / MicroOS | **Hardest** — immutable MicroOS bootstrap is OS-specific | discussion post (feasibility-first) |
+
+## Contents
+
+- `terraform-hcloud-kubernetes/` — proposed `karpenter.tf`, `karpenter.variables.tf`,
+  and `INTEGRATION.md` (the lighthouse integration).
+- `discussion-posts/` — copy-paste GitHub Discussion drafts for all three.
+
+## Prerequisite work (in this repo)
+
+The k3s targets needed a worked k3s bootstrap path, which the provider now has:
+- [`examples/k3s-nodeclass.yaml`](../../examples/k3s-nodeclass.yaml)
+- [`docs/k3s-bootstrap.md`](../k3s-bootstrap.md)
+
+## Recommended sequence
+
+1. Post the three Discussions; gauge appetite.
+2. Land the **hcloud-k8s (Talos)** integration first — cleanest fit, draft ready.
+3. For **hetzner-k3s**, prototype the `autoscaling.provider` switch if the
+   maintainer is interested.
+4. For **kube-hetzner**, prove a MicroOS+k3s bootstrap end-to-end *before* any
+   module PR.

docs/integrations/discussion-posts/hcloud-k8s.md

@@ -0,0 +1,52 @@
+<!-- Post as a GitHub Discussion (Ideas) on hcloud-k8s/terraform-hcloud-kubernetes -->
+<!-- Title: Optional Karpenter autoscaling (karpenter-provider-hetzner) as an alternative to Cluster Autoscaler? -->
+
+### Summary
+
+Would you be open to an **opt-in** Karpenter integration alongside the existing
+Cluster Autoscaler, using [`karpenter-provider-hetzner`](https://github.com/paperclipinc/karpenter-provider-hetzner)?
+
+**Disclosure:** I help maintain `karpenter-provider-hetzner`, so I have an
+interest here. I'm raising this as a Discussion (not a surprise PR) precisely
+because the module already has solid Hetzner autoscaling — I want to check
+appetite before building anything.
+
+### Why this module specifically
+
+Of the popular Hetzner installers, this one is the cleanest fit for Karpenter:
+
+- The provider already supports **Talos worker bootstrap**.
+- This module already **generates Talos worker machineconfigs** and ships
+  components as **Talos inline manifests** — so the integration reuses existing
+  machinery (`data.talos_machine_configuration`, the `*_manifest` pattern)
+  rather than adding new bootstrap logic.
+- The hcloud CCM you already install provides the `hcloud://<id>` providerID
+  Karpenter needs.
+
+### What I'm proposing (not a replacement)
+
+Karpenter is an *alternative* to the Cluster Autoscaler, not a gap-filler — it
+does per-pod instance-type selection and consolidation instead of pre-declared
+ASGs. So I'd keep it strictly opt-in:
+
+- New `karpenter_nodepools` variable; empty by default → **zero change** for
+  current users.
+- A guard so Karpenter and `cluster_autoscaler_nodepools` can't both be enabled
+  (both want to own provisioning).
+- Follows `cluster_autoscaler.tf` exactly: `data.helm_template` to render the
+  chart, a generated worker machineconfig as the node `userData`, manifests
+  appended to `talos_inline_manifests`.
+
+I have a working draft of `karpenter.tf` + variables ready to share.
+
+### Open questions
+
+1. Is an alternative autoscaler something you'd want to carry, or do you prefer
+   to keep one autoscaling path?
+2. `karpenter-provider-hetzner` is young — would you want a stability bar (e.g.
+   N months / pinned chart, marked beta) before merge?
+3. Preference on shape: single shared `HCloudNodeClass` + per-pool NodePools
+   (what I drafted), or a richer per-pool NodeClass mapping?
+
+Happy to open the PR if there's interest. Thanks for the module — it's the
+nicest Talos-on-Hetzner setup out there.

docs/integrations/discussion-posts/hetzner-k3s.md

@@ -0,0 +1,52 @@
+<!-- Post as a GitHub Discussion on vitobotta/hetzner-k3s (per CONTRIBUTING: open a Discussion for feature suggestions first) -->
+<!-- Title: Optional Karpenter-based autoscaling as an alternative to Cluster Autoscaler? -->
+
+### Summary
+
+Would you consider an **opt-in** Karpenter autoscaling backend using
+[`karpenter-provider-hetzner`](https://github.com/paperclipinc/karpenter-provider-hetzner),
+selectable per cluster instead of the current Cluster Autoscaler?
+
+**Disclosure:** I help maintain `karpenter-provider-hetzner`. Following your
+CONTRIBUTING guidance, I'm opening a Discussion before any PR to gauge interest.
+
+### The motivation
+
+`hetzner-k3s` already documents a real limitation of the CA path:
+
+> "You can't specify different images for each autoscaled pool yet."
+
+More broadly, the CA Hetzner provider pre-declares fixed pools, so you can't mix
+instance types within a pool or get automatic consolidation. Karpenter is built
+exactly for this: it picks the cheapest Hetzner type that fits each pending pod
+(CX/CPX/CAX/CCX, amd64+arm64) and consolidates underused nodes.
+
+### How it would fit hetzner-k3s
+
+Karpenter is bootstrap-agnostic — Hetzner runs the node's `userData` as
+cloud-init, so a k3s agent join works the same way your CA cloud-init does
+today. The natural shape, mirroring how you already install the CA:
+
+- A config switch, e.g. `autoscaling: { provider: karpenter | cluster_autoscaler }`.
+- When `karpenter`, the CLI installs the provider (Helm) and generates the
+  `HCloudNodeClass` + `NodePool` manifests, with `userData` doing the k3s agent
+  join using the existing cluster token + server endpoint.
+- Reuses the hcloud CCM you already install (it sets the `hcloud://<id>`
+  providerID Karpenter needs; k3s servers run with `--disable-cloud-controller`
+  and agents with `cloud-provider=external`).
+
+I've written a worked k3s bootstrap example + guide for the provider so the join
+path is concrete:
+- https://github.com/paperclipinc/karpenter-provider-hetzner/blob/main/examples/k3s-nodeclass.yaml
+- https://github.com/paperclipinc/karpenter-provider-hetzner/blob/main/docs/k3s-bootstrap.md
+
+### Open questions
+
+1. Is a second, opt-in autoscaler something you'd want in `hetzner-k3s`, or out
+   of scope?
+2. The provider is young — would you want it marked experimental / pinned until
+   it has soak time?
+3. Config ergonomics: a global `autoscaling.provider` switch, or per-pool?
+
+Not looking to replace the CA — just to offer Karpenter where its
+consolidation / per-pod sizing helps. Happy to prototype if you're open to it.

docs/integrations/discussion-posts/kube-hetzner.md

@@ -0,0 +1,51 @@
+<!-- Post as a GitHub Discussion on kube-hetzner/terraform-hcloud-kube-hetzner -->
+<!-- Title: Interest in optional Karpenter autoscaling (k3s on MicroOS)? Feasibility check -->
+
+### Summary
+
+Gauging interest in an **opt-in** Karpenter autoscaling option using
+[`karpenter-provider-hetzner`](https://github.com/paperclipinc/karpenter-provider-hetzner),
+as an alternative to the current Cluster Autoscaler — and being upfront that
+MicroOS makes this the hardest of the Hetzner installers to support.
+
+**Disclosure:** I help maintain `karpenter-provider-hetzner`. This is a
+Discussion, not a PR — I want to validate feasibility and appetite with you
+first, because the honest answer may be "not yet."
+
+### The hard part (stated plainly)
+
+kube-hetzner runs **k3s on immutable openSUSE MicroOS**. Karpenter is
+bootstrap-agnostic (Hetzner runs the node `userData` as cloud-init), but the
+provider currently ships worked examples only for Ubuntu/kubeadm and Talos. A
+MicroOS path would need a cloud-init that reproduces your
+`autoscaler-cloudinit.yaml.tpl` flow — the k3s-agent install on the
+transactional-update OS, snapshot/reboot semantics, the shared k3s token and
+endpoint. That's real, MicroOS-specific work, not a thin addon.
+
+It would also overlap directly with your well-integrated Cluster Autoscaler
+path (same token/`HCLOUD_CLUSTER_CONFIG` plumbing), so it'd be a *second*
+autoscaler to maintain, not a gap-filler.
+
+### Why it might still be worth it
+
+Karpenter does per-pod instance-type selection across CX/CPX/CAX/CCX and
+consolidation, rather than fixed pre-declared pools. For users who want
+mixed-type bin-packing and aggressive scale-down, that's a meaningful upgrade
+over the CA model.
+
+### What I'd want from you before building anything
+
+1. Is an opt-in second autoscaler something kube-hetzner would consider, given
+   the maintenance surface?
+2. If yes — would you prefer I first prove a **MicroOS + k3s-agent** Karpenter
+   bootstrap works end-to-end (as a standalone example against a kube-hetzner
+   cluster) before any module PR? That de-risks the OS-specific part.
+3. Any prior context I'm missing — I searched issues/discussions and found no
+   existing Karpenter thread, but you'd know if it's been considered.
+
+For reference, here's the k3s (Ubuntu) bootstrap path I've already documented;
+the MicroOS variant would build on it:
+- https://github.com/paperclipinc/karpenter-provider-hetzner/blob/main/docs/k3s-bootstrap.md
+
+Thanks — kube-hetzner is the gold standard for k3s-on-Hetzner, so I'd rather do
+this right (or not at all) than bolt on something fragile.